Echolotレスポンスのキャプチャ
トークンやIDなど、レスポンスの値を送信のたびに変数へ保存し、ほかのすべてのリクエストが最新の値を読めるようにします。
キャプチャは、リクエストのレスポンスにある値を、送信のたびに変数へ保存します。サインインのレスポンスからアクセストークンを{{token}}にキャプチャすると、
{{token}}を使うすべてのリクエストが、コピーなしで最新のトークンを送信します。トークンが更新されれば、すべてが新しいトークンを受け取ります。
キャプチャはリクエストとともに保存されるので、ワークスペースを持つ全員に有効で、送信をクリックしたときだけでなく、ランナーやフローでも動作します。
レスポンスの値を保存する
キャプチャを作る最も簡単な方法は、レスポンスそのものから作ることです：
- リクエストを送信します。Alpenglowの例では、Auth › Sign inを送信します。
- ボディタブでJSONツリーを選びます（該当するボディではフォーム、MessagePack、XML）。
access_tokenなどの値にポインタを合わせ、変数に保存…をクリックします。- 変数名を入力するか、パスから提案された名前のままにします。すでに使われている名前は入力中に候補として表示され、選ぶとその変数を置き換えます（パネルにtokenを置き換えと表示されます）。
- 保存先で、ウインドウの環境（環境「Staging」）またはワークスペースを選びます。
- シークレットにチェックを入れると、値はキーチェーンだけに保存され、ファイルには残りません。認証情報に見える名前（
token、secret、password、apiKeyなど）では、最初からチェックが入っています。 - 送信のたびに更新にチェックを入れたままにすると、リクエストのキャプチャとして、リクエストとともに保存されます。外すと、値は一度だけ保存されます。
- 保存をクリックします。
キャプチャを編集する
リクエストのキャプチャは変数タブのレスポンスからにあり、リクエスト自身の変数の下に表示されます。各行が1つのキャプチャです：
| 列 | 内容 |
|---|---|
| チェックボックス | キャプチャを実行するかどうか。 |
| 変数 | 変数の名前。波括弧は付けません。 |
| 取得元 | レスポンスのどこから値を読むか。 |
| パスまたは名前 | JSONPath、XPath、またはヘッダーやCookieの名前。 |
| 保存先 | 環境（リクエスト送信時にウインドウで選ばれているもの）またはワークスペース。 |
| シークレット | このMacのキーチェーンに保存され、ワークスペースのファイルには残りません。すでにシークレットである変数は、そのままシークレットです。 |
新しい行は値を追加で追加し、削除は−ボタンで行います。送信後、各行には、値を保存できたときは緑のチェックマークが、できなかったときは理由付きのオレンジの警告が表示されます。
値の取得元
| 取得元 | パスまたは名前 | 例 |
|---|---|---|
| JSON | JSONボディへのJSONPath。 | $.access_token |
| フォーム | URLエンコードされたボディへのJSONPath。オブジェクトとして読みます。 | $.access_token |
| MessagePack | MessagePackのボディへのJSONPath。JSONとして読みます。 | $.access_token |
| XML | XMLボディへのXPath。 | /auth/token |
| ヘッダー | レスポンスヘッダーを名前で指定。 | Location |
| Cookie | レスポンスが設定するCookieを名前で指定。 | session |
| ステータス | ステータスコード。 | |
| ボディ | ボディ全体をテキストとして。 |
環境かワークスペースか
- 環境は、送信時にウインドウで選ばれている環境に変数を書き込みます。ステージング用のトークンと本番用のトークンのように、サーバごとに異なる値に使います。 環境が選ばれていないと、何も保存されず、行には環境を選ぶかワークスペースに保存するよう表示されます。
- ワークスペースは、どの環境が選ばれていても同じ、ワークスペース変数に書き込みます。
同じ名前なら環境の値がワークスペースの値より優先されるため、選択中の環境にその名前の変数があると、ワークスペースへのキャプチャは隠れます。 環境を参照してください。
シークレット
キャプチャしたシークレットは、キーチェーンにだけ書き込まれます。ワークスペースのファイルには変数の名前は残りますが、値は残らないので、ワークスペースをコミットできます。 キャプチャするトークン、セッションID、キーには、すべてシークレットをオンにしてください。シークレットを参照してください。
Alpenglowでは、Auth › Sign inが$.access_tokenをワークスペースのシークレットtokenにキャプチャし、OrdersフォルダがそれをBearerトークンとして送信します。
何もキャプチャされないとき
次の場合、キャプチャは変数をそのままにして、送信後に理由を表示します：
- レスポンスのステータスが400以上の場合：値を保持するのは400未満のレスポンスだけなので、サインインに失敗しても、有効なトークンが上書きされることはありません。
- パスがレスポンス内で何も見つけられない場合。
- ボディが32 MBより大きい場合。
- 環境に保存する設定で、環境が選ばれていない場合。
- 書き込みが許可されていない場合：AIエージェントがリクエストを送信するときは、そのポリシーが変数の変更を許可するかどうかを決めます。エージェントを参照してください。
キャプチャかレスポンスの値か
{{$response('auth/sign-in', '$.access_token')}}のような動的な値は、
1つのリクエストの最新のレスポンスを直接読み、なければ先にそのリクエストを送信します。キャプチャは代わりに値を変数にコピーするので、多くのリクエストが使う値や、
複数のリクエストが更新できる値に向いています。どちらも同じJSONPathとXPathを読みます。