# 响应捕获 (/zh/docs/requests/captures)

捕获会在每次发送之后，把请求响应中的一个值保留到变量里。把登录响应中的访问令牌捕获到 `{{token}}`，每个使用 `{{token}}` 的请求发送的都是最新的令牌，无需手动拷贝。
令牌刷新时，它们都会拿到新的令牌。

捕获与请求一起存储，所以拥有该工作区的每个人都能使用，无论是在运行器、流程中，还是在你点按 **发送** 时。

## 存入响应中的值 [#store-a-value-from-the-response]

创建捕获最快的办法，是直接在响应上操作：

1. 发送请求。在 Alpenglow 示例中，发送 **Auth › Sign in**。
2. 在 **正文** 标签页中，选择 **JSON 树**（对于相应的正文，也可以选择 **表单**、**MessagePack** 或 **XML**）。
3. 将指针停留在值上，例如 `access_token`，然后点按 **存入变量…**。
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]

请求的捕获在它的 **变量** 标签页中，位于 **来自响应** 下，在请求自己的变量下方。每一行是一个捕获：

| 列 | 内容 |
| --- | --- |
| 复选框 | 该捕获是否运行。 |
| **变量** | 变量的名称，不带花括号。 |
| **来源** | 从响应的哪个位置读取值。 |
| **路径或名称** | JSONPath、XPath，或标头或 Cookie 的名称。 |
| **存储到** | **环境**（发送请求时为窗口选定的那个）或 **工作区**。 |
| **密钥** | 存储在这台 Mac 的钥匙串中，从不写入工作区文件。已是机密的变量仍保持为机密。 |

点按 **添加值** 添加新的一行，点按 **−** 按钮移除一行。发送之后，每一行在成功存入其值时显示绿色对勾，没有成功时则显示橙色警告和原因。

### 值从哪里来 [#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)会直接读取某个请求的最新响应，
如果它还没有响应，就先发送它。捕获则是把值拷贝到变量中，适合许多请求都会用到、或多个请求都能刷新的值。两者读取的 JSONPath 和 XPath 相同。