本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# HTTP 请求
## 何时使用
在函数需要调用外部服务`HTTP_REQUEST`时使用。常见用例包括从解析提供商获取身份数据、从数据管理平台检索受众细分以及将会话信息发送到日志端点。
## 配置字段
`HTTP_REQUEST`函数具有以下字段：
+ **运行时 **-表达式语言。将此设置为`JSONATA`。
+ **MethodType**— HTTP 方法。支持的值为 `GET` 和 `POST`。
+ **网址 ** — 发送请求的目标网址。您可以使用静态网址或动态构建 URL 的 JSonata 表达式。
+ **标头 **-请求中包含的 HTTP 标头，指定为标头名称和值对。对动态标头值使用`{%...%}`表达式语法。静态值可以直接指定为字符串。
+ **正文 **-要发送的请求正文。与`POST`请求一起使用。您可以使用 JSonata 表达式来动态构建身体。
+ **RequestTimeoutMilliseconds**（必填）— 等待回复的时间。
+ **输出 **-定义 HTTP 调用完成后生成的值。每个条目将输出键（例如`player_params.envelope_id`）映射到可以引用该`response`对象的表达式。
有关适用于这些字段的大小限制和限制，请参阅[限制](monetization-functions-limits.md)。
## 请求的处理方式
MediaTailor 分两步处理`HTTP_REQUEST`函数：
1. **生成请求 ** — 根据当前 MediaTailor 会话状态计算`Url``Headers`、和`Body`表达式。这些评估值构成出站 HTTP 请求。
1. **处理响应 **-在 HTTP 调用完成后， MediaTailor 计算输出块中的表达式。这些表达式既可以引用原始会话状态，也可以引用调用返回的`response`对象。
## 响应字段
HTTP 调用完成后，您可以在输出表达式中引用以下字段：
| 字段 | Type | 说明 |
| --- | --- | --- |
| response.body | 对象或数组 | 响应正文解析为 JSON。null如果正文超过 20,000 个字符或不是有效的 JSON，则设置为。 |
| response.statusCode | 整数 | 外部服务返回的 HTTP 状态码。null在网络出现故障时设置为。 |
| response.text | 字符串 | 原始响应正文为字符串，截断为 20,000 个字符。"Internal Error"在网络出现故障时设置为。 |
**重要**
该`response.body`字段是响应超过 20,000 个字符`null`时的字段，即使响应是有效的 JSON 也是如此。
**注意**
响应对象仅在`HTTP_REQUEST`函数的 Output 模块中可用。您不能在 Url、Headers 或 Body 字段中引用响应字段。在中`SEQUENTIAL_EXECUTOR`，每个`HTTP_REQUEST`函数只能访问自己的响应。
值为`null`表示数据不可用。当 HTTP 调用失败（网络错误或超时）或者响应正文超过 20,000 个字符或不是有效的 JSON 时，就会发生这种情况。
## 网络故障行为
如果 HTTP 调用由于网络错误或超时而失败，`response.statusCode``response.body`则设置为`null`，且`response.text`设置为`"Internal Error"`。您的输出表达式仍在运行，因此`response.statusCode`在使用响应数据之前，请务必进行检查。
**提示**
使用条件表达式来优雅地处理故障：`{%response.statusCode = 200 ? response.body.value : 'default'%}`
## 示例：获取身份数据
以下函数在会话开始时调用身份解析 API，并将结果存储在玩家参数中。它是为`PRE_SESSION_INITIALIZATION`生命周期挂钩设计的。
```
{
"FunctionId": "fetchIdentityEnvelope",
"FunctionType": "HTTP_REQUEST",
"HttpRequestConfiguration": {
"Runtime": "JSONATA",
"MethodType": "GET",
"Url": "{%'https://identity.example.com/v1/resolve?ip=' & $encodeUrlComponent(session.client_ip)%}",
"Headers": {
"Authorization": "{%'Bearer my_api_token'%}",
"Accept": "application/json"
},
"RequestTimeoutMilliseconds": 2000,
"Output": {
"player_params.identity_envelope": "{%response.statusCode = 200 ? response.body.envelope : ''%}"
}
}
}
```
有关类似示例的完整演练，请参阅[函数示例](monetization-functions-examples.md)。