# レスポンスのキャプチャ (/ja/docs/requests/captures)

キャプチャは、リクエストのレスポンスにある値を、送信のたびに変数へ保存します。サインインのレスポンスからアクセストークンを`{{token}}`にキャプチャすると、
`{{token}}`を使うすべてのリクエストが、コピーなしで最新のトークンを送信します。トークンが更新されれば、すべてが新しいトークンを受け取ります。

キャプチャはリクエストとともに保存されるので、ワークスペースを持つ全員に有効で、**送信**をクリックしたときだけでなく、ランナーやフローでも動作します。

## レスポンスの値を保存する [#store-a-value-from-the-response]

キャプチャを作る最も簡単な方法は、レスポンスそのものから作ることです：

1. リクエストを送信します。Alpenglowの例では、**Auth › Sign in**を送信します。
2. **ボディ**タブで**JSONツリー**を選びます（該当するボディでは**フォーム**、**MessagePack**、**XML**）。
3. `access_token`などの値にポインタを合わせ、<strong>変数に保存…</strong>をクリックします。
4. **変数名**を入力するか、パスから提案された名前のままにします。すでに使われている名前は入力中に候補として表示され、選ぶとその変数を置き換えます（パネルに**tokenを置き換え**と表示されます）。
5. **保存先**で、ウインドウの環境（**環境「Staging」**）または**ワークスペース**を選びます。
6. **シークレット**にチェックを入れると、値はキーチェーンだけに保存され、ファイルには残りません。認証情報に見える名前（`token`、`secret`、`password`、`apiKey`など）では、最初からチェックが入っています。
7. **送信のたびに更新**にチェックを入れたままにすると、リクエストのキャプチャとして、リクエストとともに保存されます。外すと、値は一度だけ保存されます。
8. **保存**をクリックします。

<Shot id="requests-http-store-variable" alt="Sign inのJSONツリー上に表示された「変数に保存」パネル。パスは$.access_token、変数名はtoken、保存先はワークスペース、シークレットと送信のたびに更新にチェック" />

## キャプチャを編集する [#edit-captures]

リクエストのキャプチャは**変数**タブの**レスポンスから**にあり、リクエスト自身の変数の下に表示されます。各行が1つのキャプチャです：

| 列 | 内容 |
| --- | --- |
| チェックボックス | キャプチャを実行するかどうか。 |
| **変数** | 変数の名前。波括弧は付けません。 |
| **取得元** | レスポンスのどこから値を読むか。 |
| **パスまたは名前** | JSONPath、XPath、またはヘッダーやCookieの名前。 |
| **保存先** | **環境**（リクエスト送信時にウインドウで選ばれているもの）または**ワークスペース**。 |
| **シークレット** | このMacのキーチェーンに保存され、ワークスペースのファイルには残りません。すでにシークレットである変数は、そのままシークレットです。 |

新しい行は<strong>値を追加</strong>で追加し、削除は<strong>−</strong>ボタンで行います。送信後、各行には、値を保存できたときは緑のチェックマークが、できなかったときは理由付きのオレンジの警告が表示されます。

### 値の取得元 [#where-values-come-from]

| 取得元 | パスまたは名前 | 例 |
| --- | --- | --- |
| **JSON** | JSONボディへのJSONPath。 | `$.access_token` |
| **フォーム** | URLエンコードされたボディへのJSONPath。オブジェクトとして読みます。 | `$.access_token` |
| **MessagePack** | MessagePackのボディへのJSONPath。JSONとして読みます。 | `$.access_token` |
| **XML** | XMLボディへのXPath。 | `/auth/token` |
| **ヘッダー** | レスポンスヘッダーを名前で指定。 | `Location` |
| **Cookie** | レスポンスが設定するCookieを名前で指定。 | `session` |
| **ステータス** | ステータスコード。 | |
| **ボディ** | ボディ全体をテキストとして。 | |

## 環境かワークスペースか [#environment-or-workspace]

- **環境**は、送信時にウインドウで選ばれている環境に変数を書き込みます。ステージング用のトークンと本番用のトークンのように、サーバごとに異なる値に使います。
  環境が選ばれていないと、何も保存されず、行には環境を選ぶかワークスペースに保存するよう表示されます。
- **ワークスペース**は、どの環境が選ばれていても同じ、ワークスペース変数に書き込みます。

同じ名前なら環境の値がワークスペースの値より優先されるため、選択中の環境にその名前の変数があると、ワークスペースへのキャプチャは隠れます。
[環境](/docs/workspaces/environments)を参照してください。

## シークレット [#secrets]

キャプチャしたシークレットは、キーチェーンにだけ書き込まれます。ワークスペースのファイルには変数の名前は残りますが、値は残らないので、ワークスペースをコミットできます。
キャプチャするトークン、セッションID、キーには、すべて**シークレット**をオンにしてください。[シークレット](/docs/workspaces/secrets)を参照してください。

Alpenglowでは、**Auth › Sign in**が`$.access_token`をワークスペースのシークレット`token`にキャプチャし、**Orders**フォルダがそれをBearerトークンとして送信します。

## 何もキャプチャされないとき [#when-nothing-is-captured]

次の場合、キャプチャは変数をそのままにして、送信後に理由を表示します：

- レスポンスのステータスが400以上の場合：値を保持するのは400未満のレスポンスだけなので、サインインに失敗しても、有効なトークンが上書きされることはありません。
- パスがレスポンス内で何も見つけられない場合。
- ボディが32 MBより大きい場合。
- 環境に保存する設定で、環境が選ばれていない場合。
- 書き込みが許可されていない場合：AIエージェントがリクエストを送信するときは、そのポリシーが変数の変更を許可するかどうかを決めます。[エージェント](/docs/ai/agents)を参照してください。

## キャプチャかレスポンスの値か [#captures-or-response-values]

`{{$response('auth/sign-in', '$.access_token')}}`のような[動的な値](/docs/requests/dynamic-values#values-from-other-requests-responses)は、
1つのリクエストの最新のレスポンスを直接読み、なければ先にそのリクエストを送信します。キャプチャは代わりに値を変数にコピーするので、多くのリクエストが使う値や、
複数のリクエストが更新できる値に向いています。どちらも同じJSONPathとXPathを読みます。