View a markdown version of this page

HTTP_REQUEST - AWS Elemental MediaTailor
使用情況組態欄位如何處理請求回應欄位網路故障行為範例：擷取身分資料

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

HTTP_REQUEST

使用情況

當您的函數需要呼叫外部服務HTTP_REQUEST時使用 。常見的使用案例包括從解析提供者擷取身分資料、從資料管理平台擷取受眾客群，以及將工作階段資訊傳送至記錄端點。

組態欄位

HTTP_REQUEST 函數具有下列欄位：

  • 執行時間 — 表達式語言。將此設定為 JSONATA。

  • MethodType — HTTP 方法。支援的值為 GET 和 POST。

  • Url — 傳送請求的 URL。您可以使用靜態 URL 或動態建置 URL 的 JSONata 表達式。

  • 標頭 — 要包含在請求中的 HTTP 標頭，指定為標頭名稱和值對。使用動態標頭值的{%...%}表達式語法。靜態值可以直接指定為字串。

  • 內文 — 要傳送的請求內文。與 POST 請求搭配使用。您可以使用 JSONata 表達式動態建置內文。

  • RequestTimeoutMilliseconds （必要） — 等待回應的時間長度。

  • 輸出 — 定義 HTTP 呼叫完成後要產生的值。每個項目都會將輸出索引鍵 （例如 player_params.envelope_id) 映射至可以參考response物件的表達式。

如需適用於這些欄位的大小限制，請參閱 限制。

如何處理請求

MediaTailor 會以兩個步驟處理 HTTP_REQUEST函數：

  1. 建置請求 — MediaTailor Url會根據目前的工作階段狀態評估 Headers、 和 Body運算式。這些評估值會形成傳出 HTTP 請求。

  2. 處理回應 — 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 : ''%}"
        }
    }
}

如需類似範例的完整演練，請參閱 函數範例。