View a markdown version of this page

函數快速入門指南 - AWS Elemental MediaTailor
先決條件步驟 1：建立 函數步驟 2：將函數連接至播放組態步驟 3：啟動工作階段並確認函數已執行幕後發生什麼事建議的主題

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

函數快速入門指南

本指南會逐步引導您建立第一個 函數、將其連接至播放組態，以及驗證其是否執行。最後，您將有一個工作函數，可分類每個檢視器的裝置類型 (ctv、 mobile或 desktop)，並將其儲存為每個 ADS 請求中可用的玩家參數。

先決條件

開始之前，請確定您擁有現有的 MediaTailor 播放組態。如果您沒有帳戶，請參閱 MediaTailor 入門。

步驟 1：建立 函數

在此步驟中，您會建立一個 函數，根據使用者代理程式字串來分類檢視器的裝置類型，並將結果存放在玩家參數中。函數使用自訂輸出類型 （無外部 API 呼叫） 搭配JSONata 表達式參考表達式來評估使用者代理程式。

  1. 在 https：//https://console.aws.amazon.com/mediatailor/ 開啟 MediaTailor 主控台。

  2. 在導覽視窗中，選擇函數。

  3. 選擇 Create function (建立函數)。

  4. 在建立精靈模態中，選取從頭開始建立，然後選擇繼續。

  5. 在函數類型下，選取自訂輸出圖磚。

  6. 在函數詳細資訊下，輸入下列內容：

    • 函數 ID： myFirstFunction

    • 描述: Classify device type from user agent

  7. 在自訂輸出組態下，於輸出區段中新增一列：

    • 索引鍵：player_params.deviceType

    • Value (值)：{% $contains(session.user_agent, 'CTV') ? 'ctv' : $contains(session.user_agent, 'Mobile') ? 'mobile' : 'desktop' %}

  8. 選擇建立函數。

成功通知會確認函數已建立，且系統會將您重新導向至函數詳細資訊頁面。

產生的函數組態為：

{
    "FunctionId": "myFirstFunction",
    "FunctionType": "CUSTOM_OUTPUT",
    "Description": "Classify device type from user agent",
    "CustomOutputConfiguration": {
        "Runtime": "JSONATA",
        "Output": {
            "player_params.deviceType": "{% $contains(session.user_agent, 'CTV') ? 'ctv' : $contains(session.user_agent, 'Mobile') ? 'mobile' : 'desktop' %}"
        }
    }
}

步驟 2：將函數連接至播放組態

將函數映射至播放組態上的生命週期掛鉤。映射會告知 MediaTailor 何時執行函數。

  1. 在導覽窗格中，選擇組態。

  2. 選擇您要更新的播放組態。

  3. 選擇編輯。

  4. 展開函數組態區段。

  5. 針對工作階段初始化掛鉤，myFirstFunction從下拉式清單中選取 。

  6. 選擇儲存。

這會連接到myFirstFunctionPRE_SESSION_INITIALIZATION生命週期掛鉤。產生的函數映射為：

{
    "FunctionMapping": {
        "PRE_SESSION_INITIALIZATION": "myFirstFunction"
    }
}

MediaTailor 會在此播放組態上的每個新工作階段開始時執行一次函數。

步驟 3：啟動工作階段並確認函數已執行

啟動新的播放工作階段以觸發 函數。將工作階段初始化請求用於播放組態的工作階段初始化端點。

MediaTailor 會自動為每個函數執行發佈 CloudWatch 指標 — 不需要選擇加入。啟動工作階段後，請檢查AWS/MediaTailor命名空間中的下列指標，以確認您的函數執行：

  • PreSessionInitHook.Invocations — 確認掛鉤已觸發。

  • PreSessionInitHook.Errors — 如果函數成功，應為 0。

  • Function.Invocations — 確認執行的個別函數。此指標包含 FunctionId、 FunctionType和 HookType維度，因此您可以myFirstFunction特別篩選 。

如果函數失敗，MediaTailor 預設會向資訊清單日誌發出錯誤日誌事件 （不需要組態）：

  • PRE_SESSION_INIT_HOOK_ERROR — 使用 errorType和 勾點層級失敗cause。

  • PRE_SESSION_INIT_FUNCTION_ERROR — 具有特定 functionId和 錯誤詳細資訊的函數層級失敗。

下列範例顯示函數表達式中語法錯誤的 PRE_SESSION_INIT_FUNCTION_ERROR事件：

{
    "eventTimestamp": "2024-01-01T12:00:00.076000000Z",
    "eventType": "PRE_SESSION_INIT_FUNCTION_ERROR",
    "eventDescription": "Function execution failed",
    "awsAccountId": "123456789012",
    "originId": "my-config",
    "sessionId": "session-123",
    "requestId": "req-abc",
    "eventId": "5dc6f040-0f72-4e8c-a64e-25eeef62708c",
    "functionId": "myFirstFunction",
    "functionType": "CUSTOM_OUTPUT",
    "executionTimeMs": 2,
    "errorType": "SYNTAX_ERROR",
    "cause": "Expected \")\" before end of expression",
    "input": {}
}

使用 eventId 欄位來關聯相同執行的勾點和函數錯誤事件。errorType 欄位會告訴您失敗的類別 — 故障診斷和監控 如需錯誤類型和修正的完整清單，請參閱 。

注意

如需詳細成功記錄，請在資訊清單日誌組態中選擇加入 PRE_SESSION_INIT_HOOK_SUMMARY和 PRE_SESSION_INIT_FUNCTION_COMPLETED事件。摘要事件會顯示每個執行的勾點結果。已完成的事件會顯示每個函數的輸入、輸出和 HTTP 請求/回應詳細資訊。這些預設為停用，以將日誌成本降至最低。如需詳細資訊，請參閱故障診斷和監控。

幕後發生什麼事

以下是您剛建立之函數的完整請求流程：

  1. 播放器使用 MediaTailor 啟動工作階段。

  2. MediaTailor 會觸發PRE_SESSION_INITIALIZATION生命週期掛鉤並執行 myFirstFunction。

  3. 函數會評估 session.user_agent 欄位，並將 ctv、 mobile或 寫入 desktop player_params.deviceType。

  4. MediaTailor 會建立工作階段，並將資訊清單傳回給玩家。

  5. 播放器在播放期間遇到廣告休息時間。

  6. MediaTailor 會觸發PRE_ADS_REQUEST生命週期掛鉤，然後建構 ADS 請求。由於 deviceType 存放在玩家參數中，因此可透過動態變數替換將其包含在 ADS 請求 URL 中。

  7. ADS 使用 裝置類型來傳回目標廣告創作。

  8. MediaTailor 會將廣告拼接到資訊清單中，並將其傳回給玩家。

如果函數因任何原因失敗，MediaTailor 會捨棄輸出並繼續，就像未連接函數一樣。檢視器仍會看到廣告，只是沒有裝置類型目標。

建議的主題

您現在已將工作函數連接至播放組態。從這裡：

  • 若要了解每個生命週期關聯中有哪些輸入欄位和輸出命名空間可用，請參閱 lifecycle hook。

  • 若要了解不同的函數類型以及如何將它們鏈結在一起，請參閱 函數類型和合成。

  • 若要查看完整的工作範例，請參閱 函數範例。