本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 函数快速入门指南
<a name="monetization-functions-quickstart"></a>

本指南将引导您创建第一个函数、将其附加到播放配置以及验证它是否已运行。最后，您将拥有一个工作函数，该函数可以对每个观看者的设备类型（`ctv``mobile`、或`desktop`）进行分类，并将其存储为每个广告请求中可用的播放器参数。

## 先决条件
<a name="monetization-functions-quickstart-prereqs"></a>

在开始之前，请确保已有 MediaTailor 播放配置。如果没有，请参阅[入门 MediaTailor](getting-started.md)。

## 步骤 1：创建 函数
<a name="monetization-functions-quickstart-step1"></a>

在此步骤中，您将创建一个函数，该函数根据用户代理字符串对查看者的设备类型进行分类，并将结果存储在玩家参数中。该函数使用带有[jsonata 表达式参考](monetization-functions-jsonata.md)表达式的自定义输出类型（不调用外部 API）来评估用户代理。

1. 打开 MediaTailor 控制台，网址为[https://console.aws.amazon.com/mediatailor/](https://console.aws.amazon.com/mediatailor/)。

1. 在导航窗格中，选择**函数**。

1. 选择**创建函数**。

1. 在创建向导模式中，选择**从头开始创建**，然后选择**继续**。

1. 在 “**函数类型**” 下，选择 “**自定义输出**” 图块。

1. 在**函数详细信息**下，输入以下内容：
   + **函数 ID**：`myFirstFunction`
   + **描述**：`Classify device type from user agent`

1. 在 “**自定义输出配置**” 下的 “**输出**” 部分中，添加一行：
   + **键**：`player_params.deviceType`
   + **值**：`{% $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 步：将该功能附加到播放配置
<a name="monetization-functions-quickstart-step2"></a>

将该函数映射到播放配置上的生命周期挂钩。映射告诉 MediaTailor 何时运行该函数。

1. 在导航窗格中，选择**配置**。

1. 选择要更新的播放配置。

1. 选择**编辑**。

1. 展开 “**函数配置**” 部分。

1. 对于**会话初始化挂钩**，请`myFirstFunction`从下拉列表中选择。

1. 选择**保存**。

这会附加`myFirstFunction`到[会话前初始化](monetization-functions-hooks-pre-session.md)生命周期挂钩上。生成的函数映射为：

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

MediaTailor 在此播放配置下，在每个新会话开始时运行一次该函数。

## 步骤 3：启动会话并验证函数已运行
<a name="monetization-functions-quickstart-step3"></a>

启动新的播放会话以触发该功能。向播放配置的会话初始化端点使用会话初始化请求。

MediaTailor 自动发布每次函数执行的 CloudWatch 指标，无需选择加入。启动会话后，检查`AWS/MediaTailor`命名空间中的以下指标以确认您的函数已运行：
+ `PreSessionInitHook.Invocations`— 确认钩子已开火。
+ `PreSessionInitHook.Errors`— 如果函数成功，则应为 0。
+ `Function.Invocations`— 确认已执行的单个函数。此指标包括`FunctionId``FunctionType`、和`HookType`维度，因此您可以进行`myFirstFunction`具体筛选。

如果该函数失败，则默认情况下会 MediaTailor 向 Manifest Logs 发出错误日志事件（无需配置）：
+ `PRE_SESSION_INIT_HOOK_ERROR`— 使用`errorType`和时 Hook-level 失败`cause`。
+ `PRE_SESSION_INIT_FUNCTION_ERROR`— Function-level 失败，具体`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) 有关错误类型和修复方法的完整列表，请参阅。

**注意**  
如需详细的成功日志记录，请在 Manifest Log 配置中选择加入`PRE_SESSION_INIT_HOOK_SUMMARY`和`PRE_SESSION_INIT_FUNCTION_COMPLETED`事件。摘要事件显示每次执行的挂钩结果。已完成的事件显示每个函数的输入、输出和 HTTP request/response 详细信息。默认情况下，它们处于禁用状态，以最大限度地降低日志成本。有关更多信息，请参阅 [故障排除和监控](monetization-functions-troubleshooting.md)。

## 幕后会发生什么
<a name="monetization-functions-quickstart-behind-scenes"></a>

以下是您刚刚创建的函数的完整请求流程：

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 请求网址中。

1. ADS 使用设备类型来返回定向广告创意。

1. MediaTailor 将广告拼接到清单中，然后将其返回给玩家。

如果函数因任何原因失败，则 MediaTailor 丢弃输出并像未附加任何函数一样继续运行。观看者仍然可以看到广告，只是没有设备类型定位。

## 建议的主题
<a name="monetization-functions-quickstart-suggested-topics"></a>

现在，播放配置中附带了一个可以正常运行的功能。从这里：
+ 要了解每个生命周期挂钩中都有哪些输入字段和输出命名空间可用，请参阅。[生命周期钩子](monetization-functions-hooks.md)
+ 要了解不同的函数类型以及如何将它们链接在一起，请参阅[函数类型和构成](monetization-functions-types.md)。
+ 要查看完整的工作示例，请参阅[函数示例](monetization-functions-examples.md)。