本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 函數快速入門指南
本指南會逐步引導您建立第一個 函數、將其連接至播放組態，以及驗證其是否執行。最後，您將有一個工作函數，可分類每個檢視器的裝置類型 (`ctv`、 `mobile`或 `desktop`)，並將其儲存為每個 ADS 請求中可用的玩家參數。
## 先決條件
開始之前，請確定您擁有現有的 MediaTailor 播放組態。如果您沒有帳戶，請參閱 [MediaTailor 入門](getting-started.md)。
## 步驟 1：建立 函數
在此步驟中，您會建立一個 函數，根據使用者代理程式字串來分類檢視器的裝置類型，並將結果存放在玩家參數中。函數使用自訂輸出類型 （無外部 API 呼叫） 搭配[JSONata 表達式參考](monetization-functions-jsonata.md)表達式來評估使用者代理程式。
1. 在 https：//[https://console.aws.amazon.com/mediatailor/](https://console.aws.amazon.com/mediatailor/) 開啟 MediaTailor 主控台。
1. 在導覽視窗中，選擇**函數**。
1. 選擇 **Create function (建立函數)**。
1. 在建立精靈模態中，選取**從頭開始建立**，然後選擇**繼續**。
1. 在**函數類型**下，選取**自訂輸出**圖磚。
1. 在**函數詳細資訊**下，輸入下列內容：
+ **函數 ID**： `myFirstFunction`
+ **描述:** `Classify device type from user agent`
1. 在**自訂輸出組態**下，於**輸出**區段中新增一列：
+ **索引鍵**：`player_params.deviceType`
+ **Value (值)**：`{% $contains(session.user_agent, 'CTV') ? 'ctv' : $contains(session.user_agent, 'Mobile') ? 'mobile' : 'desktop' %}`
1. 選擇**建立函數**。
成功通知會確認函數已建立，且系統會將您重新導向至函數詳細資訊頁面。
產生的函數組態為：
```
{
"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. 在導覽窗格中，選擇**組態**。
1. 選擇您要更新的播放組態。
1. 選擇**編輯**。
1. 展開**函數組態**區段。
1. 針對**工作階段初始化掛鉤**，`myFirstFunction`從下拉式清單中選取 。
1. 選擇**儲存**。
這會連接到`myFirstFunction`[PRE\_SESSION\_INITIALIZATION](monetization-functions-hooks-pre-session.md)生命週期掛鉤。產生的函數映射為：
```
{
"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` 欄位會告訴您失敗的類別 — [故障診斷和監控](monetization-functions-troubleshooting.md) 如需錯誤類型和修正的完整清單，請參閱 。
**注意**
如需詳細成功記錄，請在資訊清單日誌組態中選擇加入 `PRE_SESSION_INIT_HOOK_SUMMARY`和 `PRE_SESSION_INIT_FUNCTION_COMPLETED`事件。摘要事件會顯示每個執行的勾點結果。已完成的事件會顯示每個函數的輸入、輸出和 HTTP 請求/回應詳細資訊。這些預設為停用，以將日誌成本降至最低。如需詳細資訊，請參閱[故障診斷和監控](monetization-functions-troubleshooting.md)。
## 幕後發生什麼事
以下是您剛建立之函數的完整請求流程：
1. 播放器使用 MediaTailor 啟動工作階段。
1. MediaTailor 會觸發`PRE_SESSION_INITIALIZATION`生命週期掛鉤並執行 `myFirstFunction`。
1. 函數會評估 `session.user_agent` 欄位，並將 `ctv`、 `mobile`或 寫入 `desktop` `player_params.deviceType`。
1. MediaTailor 會建立工作階段，並將資訊清單傳回給玩家。
1. 播放器在播放期間遇到廣告休息時間。
1. MediaTailor 會觸發`PRE_ADS_REQUEST`生命週期掛鉤，然後建構 ADS 請求。由於 `deviceType` 存放在玩家參數中，因此可透過動態變數替換將其包含在 ADS 請求 URL 中。
1. ADS 使用 裝置類型來傳回目標廣告創作。
1. MediaTailor 會將廣告拼接到資訊清單中，並將其傳回給玩家。
如果函數因任何原因失敗，MediaTailor 會捨棄輸出並繼續，就像未連接函數一樣。檢視器仍會看到廣告，只是沒有裝置類型目標。
## 建議的主題
您現在已將工作函數連接至播放組態。從這裡：
+ 若要了解每個生命週期關聯中有哪些輸入欄位和輸出命名空間可用，請參閱 [lifecycle hook](monetization-functions-hooks.md)。
+ 若要了解不同的函數類型以及如何將它們鏈結在一起，請參閱 [函數類型和合成](monetization-functions-types.md)。
+ 若要查看完整的工作範例，請參閱 [函數範例](monetization-functions-examples.md)。