本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# HTTP 請求
## 使用情況
當您的函數需要呼叫外部服務`HTTP_REQUEST`時使用 。常見的使用案例包括從解析提供者擷取身分資料、從資料管理平台擷取受眾客群，以及將工作階段資訊傳送至記錄端點。
## 組態欄位
`HTTP_REQUEST` 函數具有下列欄位：
+ **執行時間** — 表達式語言。將此設定為 `JSONATA`。
+ **MethodType** — HTTP 方法。支援的值為 `GET` 和 `POST`。
+ **Url** — 傳送請求的 URL。您可以使用靜態 URL 或動態建置 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 | Integer | 外部服務傳回的 HTTP 狀態碼。在網路故障null時將 設定為 。 |
| response.text | String | 原始回應內文做為字串，截斷為 20，000 個字元。在網路故障"Internal Error"時將 設定為 。 |
**重要**
`response.body` 欄位是回應超過 20，000 個字元`null`時，即使回應是有效的 JSON。
**注意**
回應物件僅適用於 `HTTP_REQUEST`函數的輸出區塊。您無法參考 Url、標頭或內文欄位中的回應欄位。在 中`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)。