--- title: api description: 既存の認証を使い、公開APIの一覧を確認してリクエストする。 canonical_url: https://orchestor.io/docs/cli/api markdown_url: https://orchestor.io/docs/cli/api.md contentType: reference --- # api `orc api` は、ターミナルからOrchestor APIへ認証付きのHTTPリクエストを送信するコマンドです。他のCLIコマンドと同じ認証情報を使用し、公開API契約に含まれるメソッドとパスを一覧から確認して、クエリーやJSON本文を指定した呼び出しを実行できます。専用コマンドがない操作の探索、応答を調べるデバッグ、スクリプトへの組み込みに使用します。実行前に [`orc auth login`](https://orchestor.io/docs/cli/auth.md) でログインするか、CLIが使用する認証を設定してください。接続先はCLIに設定されたOrchestor APIで、現在の認証主体の権限が適用されます。一覧は公開契約のカタログであり、操作権限の判定結果ではありません。 ## 使い方 ```bash title="terminal" orc api list ``` *公開APIのメソッド、パス、説明を確認します。* ```bash title="terminal" orc api request GET /v1/users/me ``` *現在の認証主体のプロフィールを取得します。* ## サブコマンド ### `list` CLIに同梱された公開API契約から、HTTPメソッド、パス、operationId、説明を一覧で返します。認証が必要です。アカウントごとの操作権限は絞り込まず、リクエスト実行時にサーバーが確認します。 `orc api ls` は `orc api list` の別名です。 ```bash title="terminal" orc api list [options] ``` #### 使用例 ```bash title="terminal" orc api list --json ``` *スクリプト向けにAPIの一覧をJSONで返します。* ### `request` HTTPメソッドと、`/` から始まるAPIパスを指定して実行します。対応するメソッドは `GET`、`POST`、`PUT`、`PATCH`、`DELETE` です。メソッドの省略や本文からの自動推定は行いません。パスは `api list` に表示される公開契約に一致する必要があります。`{id}` などのパスパラメーターは実際のリソースIDに置き換えてください。クエリーは引用符で囲んだパスに指定します。未知のクエリーや、同じ項目をパスとフラグで重ねた指定はエラーになります。JSON本文を持つ作成・更新操作では `--stdin` でJSONオブジェクトを渡し、API契約の型・必須項目に従って検証します。 ```bash title="terminal" orc api request [options] ``` #### 使用例 `profile.json` に `{"locale":"ja"}` のようなJSONオブジェクトを保存します。プロフィール変更には人間のアカウント認証とサーバー側の権限が必要です。 ```bash title="terminal" orc api request PATCH /v1/users/me --stdin < profile.json ``` *保存したJSONからプロフィールを更新します。* ### `ls` List public contract operations; server authorization still applies ```bash title="terminal" orc api ls [options] ``` ## 使用例 ### 現在の認証主体を取得する保存済みの認証を引き継いで、自分のプロフィールをJSON envelopeで返します。 ```bash title="terminal" orc api request GET /v1/users/me ``` *現在の認証主体を取得する* ### Workspaceを指定して情報を取得する `--workspace` で送信する `X-Workspace-ID` を指定します。指定したWorkspaceへのアクセス権はサーバーが確認します。 ```bash title="terminal" orc api request GET /v1/workspaces/ --workspace ``` *Workspaceを指定して情報を取得する* ### JSONファイルからリクエスト本文を渡す本文を持つ作成・更新操作で使用します。ファイルのリダイレクトも、パイプで渡すJSONも同じ標準入力として扱います。 ```bash title="terminal" orc api request PATCH /v1/users/me --stdin < profile.json ``` *JSONファイルからリクエスト本文を渡す* ### クエリーで一覧の取得件数を指定する対象APIが定義するクエリーをパスに追加します。クエリーの名前、型、必須条件は公開API契約に従います。 ```bash title="terminal" orc api request GET '/v1/workspaces?limit=10' ``` *クエリーで一覧の取得件数を指定する* ### 一覧の全ページを取得する cursorによるページ分割を持つAPIでは、全ページのレコードを1行ずつNDJSONで出力します。`--json`、`--pretty`、JSONなどの `--format` とは併用できません。必要に応じて `--output` でファイルに保存してください。 ```bash title="terminal" orc api request GET /v1/workspaces --page-all ``` *一覧の全ページを取得する* ### 削除の確認を省略する削除対象を確認してから実行してください。`--yes` はCLIの確認を省略します。サーバーの認可や削除条件は引き続き適用されます。 ```bash title="terminal" orc api request DELETE /v1/brands/ --workspace --yes ``` *削除の確認を省略する* ### 応答の項目を取り出す `--field` は応答の項目を取り出すフラグです。リクエスト本文のフィールドを追加する用途ではありません。 ```bash title="terminal" orc api request GET /v1/users/me --field id --raw ``` *応答の項目を取り出す* ### リクエストの所要時間を確認する応答を標準出力へ、所要時間を標準エラー出力へ返します。 ```bash title="terminal" orc api request GET /v1/users/me --timing ``` *リクエストの所要時間を確認する* ## 動作の流れ 1. CLIが現在の認証情報を解決します。 2. メソッドとパスを同梱された公開API契約と照合し、クエリーとJSON本文を検証します。 3. 設定されたAPIへ認証を付けて送信します。Workspaceを指定した場合は `X-Workspace-ID` も付与します。 4. サーバーが現在の認証主体のアクセス権を確認し、CLIが応答を出力します。既定の出力は `success`、`data`、`metadata` を持つJSON envelopeです。資格情報のフィールドは出力時に秘匿されます。失敗理由は標準エラー出力に返し、スクリプトでは終了コードで成功・失敗を判定してください。探索には `orc api list` を使います。API契約はCLIに同梱されており、実行のたびに取得するものではありません。外部URL、`//` から始まるパス、パスの遡り、内部・バックエンド専用APIは受け付けず、リダイレクトにも追従しません。 ## グローバルオプション `orc api` では、次の[グローバルオプション](https://orchestor.io/docs/cli/global-flags.md)を使用できます。 - [`--help`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%98%E3%83%AB%E3%83%97) - [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%AF%E3%83%BC%E3%82%AF%E3%82%B9%E3%83%9A%E3%83%BC%E3%82%B9) - [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-%E5%87%BA%E5%8A%9B) - [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-%E5%87%BA%E5%8A%9B) - [`--format`](https://orchestor.io/docs/cli/global-flags.md#%E5%87%BA%E5%8A%9B%E5%BD%A2%E5%BC%8F) - [`--field`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%95%E3%82%A3%E3%83%BC%E3%83%AB%E3%83%89%E3%81%AE%E6%8A%BD%E5%87%BA) - [`--fields`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%95%E3%82%A3%E3%83%BC%E3%83%AB%E3%83%89%E3%81%AE%E6%8A%BD%E5%87%BA) - [`--raw`](https://orchestor.io/docs/cli/global-flags.md#%E5%80%A4%E3%81%A0%E3%81%91%E3%82%92%E5%87%BA%E5%8A%9B) - [`--output`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%81%B8%E3%81%AE%E5%87%BA%E5%8A%9B) - [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%9A%E3%83%BC%E3%82%B8%E9%80%81%E3%82%8A) - [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88%E3%81%AE%E4%BA%8B%E5%89%8D%E7%A2%BA%E8%AA%8D) - [`--yes`](https://orchestor.io/docs/cli/global-flags.md#%E7%A2%BA%E8%AA%8D%E3%81%AE%E7%9C%81%E7%95%A5) - [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#%E6%A8%99%E6%BA%96%E5%85%A5%E5%8A%9B) - [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#%E6%A8%99%E6%BA%96%E5%85%A5%E5%8A%9B) - [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#%E3%81%99%E3%81%B9%E3%81%A6%E3%81%AE%E3%83%9A%E3%83%BC%E3%82%B8%E3%82%92%E5%8F%96%E5%BE%97) - [`--timing`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88%E6%99%82%E9%96%93) 各オプションの詳細と使用例は、[グローバルオプション](https://orchestor.io/docs/cli/global-flags.md)を参照してください。 ## トラブルシューティング ### メソッドやパスが受け付けられない `orc api list` でメソッドとパスを確認してください。パスの末尾、リソースID、メソッドも契約に一致する必要があります。新しいAPIが一覧にない場合はCLIのバージョンを確認してください。 ### 認証や権限のエラーになる認証を確認し、必要に応じて [`orc auth login`](https://orchestor.io/docs/cli/auth.md) でログインし直してください。Workspaceを指定した場合は、そのWorkspaceへのアクセス権も確認してください。一覧にある操作でも、現在のアカウントに許可されているとは限りません。 ### JSON本文の検証に失敗する `--stdin` に有効なJSONオブジェクトを渡し、対象APIの必須項目と型を確認してください。配列や単一の文字列はリソース定義として受け付けません。本文は `POST`、`PUT`、`PATCH` の操作で使用します。 ### 非対話環境で削除できない `DELETE` は確認を必要とします。スクリプトでは削除対象を確認した上で `--yes` を指定してください。これは操作権限を変更するものではありません。 ## 関連項目 - [認証](https://orchestor.io/docs/cli/auth.md) - [Workspace](https://orchestor.io/docs/cli/workspace.md) - [グローバルオプション](https://orchestor.io/docs/cli/global-flags.md) --- [Documentation index](https://orchestor.io/docs/llms.txt)