View a markdown version of this page

函数快速入门指南 - AWS Elemental MediaTailor
先决条件步骤 1：创建 函数第 2 步：将该功能附加到播放配置步骤 3：启动会话并验证函数已运行幕后会发生什么建议的主题

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

函数快速入门指南

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

先决条件

在开始之前，请确保已有 MediaTailor 播放配置。如果没有，请参阅入门 MediaTailor。

步骤 1：创建 函数

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

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

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

  3. 选择创建函数。

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

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

  6. 在函数详细信息下，输入以下内容：

    • 函数 ID：myFirstFunction

    • 描述：Classify device type from user agent

  7. 在 “自定义输出配置” 下的 “输出” 部分中，添加一行：

    • 键：player_params.deviceType

    • 值：{% $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. 选择保存。

这会附加myFirstFunction到会话前初始化生命周期挂钩上。生成的函数映射为：

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

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

步骤 3：启动会话并验证函数已运行

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

MediaTailor 自动发布每次函数执行的 CloudWatch 指标，无需选择加入。启动会话后，检查AWS/MediaTailor命名空间中的以下指标以确认您的函数已运行：

  • PreSessionInitHook.Invocations— 确认钩子已开火。

  • PreSessionInitHook.Errors— 如果函数成功，则应为 0。

  • Function.Invocations— 确认已执行的单个函数。此指标包括FunctionIdFunctionType、和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字段告诉你失败的类别 — 故障排除和监控 有关错误类型和修复方法的完整列表，请参阅。

注意

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

幕后会发生什么

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

  1. 玩家与发起会话。 MediaTailor

  2. MediaTailor 触发PRE_SESSION_INITIALIZATION生命周期挂钩并运行myFirstFunction。

  3. 该函数对session.user_agent字段进行求值并写入ctvmobile、或desktop。player_params.deviceType

  4. MediaTailor 创建会话并将清单返回给玩家。

  5. 玩家在播放过程中遇到广告中断。

  6. MediaTailor 触发PRE_ADS_REQUEST生命周期挂钩，然后构造 ADS 请求。由于存储deviceType在玩家参数中，因此可以通过动态变量替换将其包含在 ADS 请求网址中。

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

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

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

建议的主题

现在，播放配置中附带了一个可以正常运行的功能。从这里：

  • 要了解每个生命周期挂钩中都有哪些输入字段和输出命名空间可用，请参阅。生命周期钩子

  • 要了解不同的函数类型以及如何将它们链接在一起，请参阅函数类型和构成。

  • 要查看完整的工作示例，请参阅函数示例。