View a markdown version of this page

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

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

功能快速入门指南

本指南将引导您创建第一个函数、将其附加到播放配置以及验证其是否已运行。最后，您将拥有一个有效的功能，可以对每位观众的设备类型（ctv、或desktop）进行分类mobile，并将其存储为每个 ADS 请求中可用的玩家参数。

先决条件

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

步骤 1：创建 函数

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

  1. 打开 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与Pre-session 初始化生命周期挂钩有关。生成的函数映射是：

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

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

第 3 步：启动会话并验证功能已运行

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

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

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

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

  • Function.Invocations— 确认已执行的单个函数。此指标包括FunctionIdFunctionType、和HookType维度，因此您可以进行myFirstFunction具体筛选。

如果该函数失败，则默认向清单日志 MediaTailor 发送错误日志事件（无需配置）：

  • PRE_SESSION_INIT_HOOK_ERROR— 使用errorType和时 Hook-level 失败cause。

  • PRE_SESSION_INIT_FUNCTION_ERROR— 具体functionId和错误详细信息 Function-level 失败。

以下示例显示了函数表达式中语法错误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 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在玩家参数中，因此可以通过动态变量替换将其包含在广告请求网址中。

  7. ADS 使用设备类型返回定向广告素材。

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

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

建议的主题

现在，您已在播放配置中附加了一项有效功能。从这里开始：

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

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

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