MediaTailor 参数参考 MediaTailor 配置别名 MediaTailor 传递 ADS 参数 MediaTailor别名疑难解答

MediaTailor 动态广告变量

AWS Elemental MediaTailor 向广告决策服务器 (ADS) 发出的请求包括有关当前观看会话的信息。这些信息可帮助 ADS 选择在响应中提供的最佳广告。在配置中 MediaTailor 配置 ADS 模板时，可以包括动态变量，也称为宏。动态变量是可替换的字符串。

动态变量可以采用以下形式：

静态值-从一个会话到下一个会话不变的值。例如， MediaTailor 期望从 ADS 获得的响应类型。
域变量 — 可用于 URL 域的动态变量，例如 URL http://my-ads-server.co m 的 my-ads-server .com部分。有关更多信息，请参阅 MediaTailor 域变量。
会话数据- MediaTailor 为每个会话提供的动态值，例如会话 ID。有关更多信息，请参阅 MediaTailor 会话变量。
玩家数据-玩家为每个会话提供的动态值。它们描述了内容查看器，并帮助广告公司确定哪些广告 MediaTailor 应该拼接到直播中。有关更多信息，请参阅 MediaTailor 玩家变量。

MediaTailor 参数参考和限制

AWS Elemental MediaTailor 提供了有关参数字符限制、长度限制以及清单查询参数和 ADS 参数支持的格式的全面信息。

清单查询参数字符限制

清单查询参数支持特定字符并具有定义的长度限制。

支持的字符（没有 URL 编码）

您可以直接在清单查询参数中使用以下字符：

字母数字字符（A-Z、a-z、0-9）
时期 (.)
连字符 (-)
下划线 (_)
反斜杠 (\)

支持的带有 URL 编码的字符

URL 编码时支持以下特殊字符：

时期 (.) = %2E
短划线 (-) = %2D
下划线 (_) = %5F
百分比 (%) = %25
波浪号 (~) = %7E
正斜杠 (/) = %2F
星号 (*) = %2A
等于 (=) = %3D
问题 (？) = %3F

支持网址编码

MediaTailor 当你在 URL 编码中使用百分号 (%)（例如，hello%20world = hello world = hello world）时，支持使用百分号 (%)。您可以使用任何 URL 编码字符，只要它们是符合 HTTP 规范的有效网址编码即可。

不支持的字符

如果没有 URL 编码，则不能在清单查询参数中使用以下字符：:、?、&、=%、/（正斜杠）。

重要

MediaTailor 不支持双字符，例如%%% 或 ==。由于字符限制，您不能使用 full URLs 作为清单查询参数值。

长度限制

所有清单查询参数（键和值的组合）的总长度不得超过 2000 个字符。

ADS 参数长度限制

以下长度限制适用于向 ADS 发出的请求中使用的参数：

ADS 参数名称：最多 10,000 个字符
ADS 参数值：最多 25,000 个字符
广告网址：最多 25,000 个字符

MediaTailor 配置别名和动态变量替换

AWS Elemental MediaTailor 配置别名允许在 URL 域和其他支持的字段中进行动态变量替换。使用此功能可在会话初始化 URLs 期间使用多个域并进行动态配置。

动态变量替换支持的字段

您可以在以下配置字段中使用动态变量：

VideoContentSourceUrl
AdDecisionServerUrl
LivePreroll.AdDecisionServerUrl
AdSegmentUrlPrefix
ContentSegmentUrlPrefix
TranscodeProfileName
SlateAdUrl
StartUrl
EndUrl

域级参数规则

当您在的域部分使用动态变量时 URLs，将适用以下限制：

域中使用的所有动态变量必须指定为 ConfigurationAliases
只能是 player_params
别名值列表必须详尽无遗
别名无效或缺失会导致 HTTP 400 错误

ConfigurationAliases API 参数结构

该 ConfigurationAliases 参数使用以下 JSON 结构：


{
    "ConfigurationAliases": {
        "player_params.origin_domain": {
            "pdx": "abc.mediapackage.us-west-2.amazonaws.com",
            "iad": "xyz.mediapackage.us-east-1.amazonaws.com"
        },
        "player_params.ad_type": {
            "customized": "abc12345",
            "default": "defaultAdType"
        }
    }
}

API 一致性

playerParams现在支持作为替代方案ads和adsParams提高 API 一致性。

缺少别名的后备行为

当找不到配置别名或配置别名无效时，将 MediaTailor 实现以下回退行为：

域变量：如果域变量别名缺失或无效，则请求将失败，并显示 HTTP 400 状态码。所有域变量都必须定义有效的别名。
非域变量：对于的非域部分中使用的变量 URLs （例如路径元素或查询参数），缺少别名会导致替换空字符串。
配置验证： MediaTailor 验证在配置创建和更新操作期间是否存在所有必需的别名。

高级多配置用例

配置别名可为以下场景启用复杂的多配置架构：

地理路由：使用特定地区的别名，根据观众的位置将请求路由到不同的来源或广告服务器。有关实施指南，请参阅CloudFront 源站故障转移。
基于内容的路由：将不同的内容类型定向到专门的来源或处理管道。有关路由行为的配置，请参阅为以下各项设置 CDN 路由行为 MediaTailor。
故障转移场景：使用别名切换实现自动故障转移的备份源和广告服务器。有关实施的详细信息，请参见 MediaTailor 使用 MQAR 实现多区域弹性和规划您的 CDN 集成 AWS Elemental MediaTailor。
A/B 测试：根据玩家参数路由流量，测试不同的广告服务器、来源或配置。有关负载测试指南，请参阅 CloudFront 使用真实用户监控功能为 Amazon 准备和运行性能测试。
设备特定优化：针对不同的设备类型或功能优化内容投放和广告投放。有关全面的指导，请参阅使用 MediaTailor、 MediaPackage和 CDN 设置清单筛选。
负载平衡：使用动态路由在多个来源或广告服务器之间分配负载。有关实施指导，请参见 MediaTailor 使用 MQAR 实现多区域弹性和规划您的 CDN 集成 AWS Elemental MediaTailor。

例使用别名完成配置

以下示例显示了包括配置别名和动态域变量的完整配置：


PUT /playbackConfiguration
{
    "Name": "aliasedConfig",
    "AdDecisionServerUrl": "https://abc.execute-api.us-west-2.amazonaws.com/ads?sid=[session.id]&ad_type=[player_params.ad_type]",
    "VideoContentSourceUrl": "https://[player_params.origin_domain].mediapackage.[player_params.region].amazonaws.com/out/v1/[player_params.endpoint_id]",
    
    "AdSegmentUrlPrefix": "https://[player_params.ad_cdn_domain]/ads/",
    "ContentSegmentUrlPrefix": "https://[player_params.content_cdn_domain]/content/",
    "TranscodeProfileName": "[player_params.transcode_profile]",
    "SlateAdUrl": "https://[player_params.slate_domain]/slate/[player_params.slate_type].mp4",
    "StartUrl": "https://[player_params.tracking_domain]/start?session=[session.id]",
    "EndUrl": "https://[player_params.tracking_domain]/end?session=[session.id]",
    
    "ConfigurationAliases": {
        "player_params.origin_domain": {
            "pdx": "abc",
            "iad": "xyz"
        },
        "player_params.region": {
            "pdx": "us-west-2",
            "iad": "us-east-1"
        },
        "player_params.endpoint_id": {
            "pdx": "abcd",
            "iad": "wxyz"
        },
        "player_params.ad_type": {
            "customized": "abc12345",
            "default": "defaultAdType"
        },
        "player_params.ad_cdn_domain": {
            "pdx": "ads-west.cdn.example.com",
            "iad": "ads-east.cdn.example.com"
        },
        "player_params.content_cdn_domain": {
            "pdx": "content-west.cdn.example.com",
            "iad": "content-east.cdn.example.com"
        },
        "player_params.transcode_profile": {
            "mobile": "mobile_optimized",
            "desktop": "high_quality",
            "tv": "4k_profile"
        },
        "player_params.slate_domain": {
            "pdx": "slate-west.example.com",
            "iad": "slate-east.example.com"
        },
        "player_params.slate_type": {
            "standard": "default_slate",
            "branded": "brand_slate"
        },
        "player_params.tracking_domain": {
            "pdx": "tracking-west.example.com",
            "iad": "tracking-east.example.com"
        }
    }
}

例使用别名进行会话初始化

使用上述配置，创建会话初始化请求，指定玩家变量和别名：


POST master.m3u8
{
    "playerParams": {
        "origin_domain": "pdx",
        "region": "pdx", 
        "endpoint_id": "pdx",
        "ad_type": "customized",
        "ad_cdn_domain": "pdx",
        "content_cdn_domain": "pdx",
        "transcode_profile": "mobile",
        "slate_domain": "pdx",
        "slate_type": "branded",
        "tracking_domain": "pdx"
    }
}

例参数处理流程

MediaTailor 用配置别名中的映射值替换别名字符串。处理后会产生以下请求：

广告请求：


https://abc.execute-api.us-west-2.amazonaws.com/ads?sid=[session.id]&ad_type=abc12345

VideoContentSource 请求：


https://abc.mediapackage.us-west-2.amazonaws.com/out/v1/abcd

AdSegmentUrlPrefix:
```
https://ads-west.cdn.example.com/ads/
```

ContentSegmentUrlPrefix:


https://content-west.cdn.example.com/content/

TranscodeProfileName:
```
mobile_optimized
```

SlateAdUrl:


https://slate-west.example.com/slate/brand_slate.mp4

StartUrl:


https://tracking-west.example.com/start?session=[session.id]

EndUrl:


https://tracking-west.example.com/end?session=[session.id]

MediaTailor 向 ADS 传递参数

AWS Elemental MediaTailor 支持使用以下步骤在向 ADS 发出的 MediaTailor 请求中设置动态变量。

有关查询参数支持的格式的信息，请参见MediaTailor 参数参考和限制。
有关配置别名和域变量，请参见MediaTailor 配置别名和动态变量替换。
有关 ADS 请求的其他自定义设置，请参阅高级用法。

会话初始化方法

MediaTailor 支持多种会话初始化和参数传递方法：

带有请求正文的 POST：


POST <master>.m3u8
{
    "adsParams": {"param1": "value1", "param2": "value2"},
    "playerParams": {"param3": "value3"}
}

URL 中的查询参数：


GET <master>.m3u8?ads.param1=value1&ads.param2=value2&playerParams.param3=value3

重要

在初始化时，只能指定一次参数。在转发之前，配置别名会解析为实际值。

将会话和播放器信息传递到 ADS

与 ADS 合作，确定其回复广告查询所需的信息 AWS Elemental MediaTailor。
在中创建使用满足 ADS MediaTailor 要求的模板 ADS 请求网址的配置。在 URL 中，包含静态参数和用于动态参数的占位符。在配置的 Ad decision server (广告决策服务器) 字段中输入您的模板 URL。

在以下示例模板 URL 中，correlation 提供会话数据，deviceType 提供播放器数据：
```
https://my.ads.server.com/path?correlation=[session.id]&deviceType=[player_params.deviceType]
```
在播放器上，为 AWS Elemental MediaTailor 配置会话发起请求以便为播放器数据提供参数。在会话发起请求中包含您的参数，并在后续会话请求中省略它们。

玩家为初始化会话而进行的调用类型决定了玩家（客户端）还是 MediaTailor （服务器）是否为会话提供广告跟踪报告。有关这两个选项的信息，请参阅报告广告跟踪数据。

根据您是需要服务器端还是客户端广告跟踪报告来进行以下类型的呼叫之一。在两个示例调用中，userID 适用于 ADS，auth_token 适用于源：
- （选项）要求服务器端广告跟踪报告 — 在要发送 MediaTailor 到 ADS 的参数前面加上前缀。ads为您希望 MediaTailor 将其发送到源服务器的参数消除前缀：
  
  以下示例显示了 HLS 和 DASH 的传入请求。 AWS Elemental MediaTailor MediaTailor deviceType在向 ADS 发出的请求中使用，auth_token在对源服务器的请求中使用。
  
  HLS 示例：
```
GET master.m3u8?ads.deviceType=ipad&auth_token=kjhdsaf7gh
```
  DASH 示例：
```
GET manifest.mpd?ads.deviceType=ipad&auth_token=kjhdsaf7gh
```
- （选项）调用客户端广告跟踪报告-为对象内的广告提供参数。adsParams
  
  HLS 示例：
```
POST master.m3u8
    {
        "adsParams": {
           "deviceType": "ipad"
       }
    }
```
  DASH 示例：
```
POST manifest.mpd
    {
        "adsParams": {
           "deviceType": "ipad"
       }
    }
```

当玩家发起会话时， AWS Elemental MediaTailor 使用会话数据和玩家的ads参数替换模板 ADS 请求网址中的变量。它将剩余参数从播放器传递到源服务器。

例 MediaTailor 带有广告变量的请求

以下示例显示了来自 AWS Elemental MediaTailor 的针对 ADS 和源服务器的调用（对应于上述播放器的会话初始化调用示例）。

MediaTailor 使用会话数据和玩家的设备类型调用 ADS：


https://my.ads.server.com/path?correlation=896976764&deviceType=ipad

MediaTailor 使用玩家的授权令牌调用源服务器。

HLS 示例：


https://my.origin.server.com/master.m3u8?auth_token=kjhdsaf7gh

DASH 示例：


https://my.origin.server.com/manifest.mpd?auth_token=kjhdsaf7gh

高级用法

您可以通过播放器和会话数据以多种方式自定义 ADS 请求。您只需要包含 ADS 主机名即可。

以下示例显示了一些可用来自定义请求的方法：

连接播放器参数和会话参数以创建新参数。示例：
```
https://my.ads.com?key1=[player_params.value1][session.id]
```
使用播放器参数作为路径元素的一部分。示例：
```
https://my.ads.com/[player_params.path]?key=value
```
使用播放器参数传递路径元素和键本身，而不仅仅是值。示例：
```
https://my.ads.com/[player_params.path]?[player_params.key1]=[player_params.value1]
```

MediaTailor 配置别名疑难解答

AWS Elemental MediaTailor 为常见的配置别名问题和错误场景提供系统的故障排除指导。

配置别名验证错误

当配置别名丢失或无效时， MediaTailor 会返回特定的错误响应以帮助识别问题。

常见的错误场景

下表描述了常见的配置别名错误及其解决步骤：

错误	原因	解决方案
HTTP 400：玩家参数别名无效	中找不到玩家参数值 ConfigurationAliases	验证玩家参数值是否作为键存在于相应的 ConfigurationAliases 映射中
HTTP 400：缺少所需的配置别名	使用没有相应 ConfigurationAliases条目的域变量	将缺少的玩家参数添加到 ConfigurationAliases 包含所有必需的别名映射中
HTTP 400：配置验证失败	ConfigurationAliases 结构格式错误或不完整	验证 JSON 结构并确保所有域变量都有相应的别名
中的空字符串替换 URLs	未找到非域变量别名	添加缺失的别名映射或在中提供默认值 ConfigurationAliases

验证清单

使用以下清单来验证您的配置别名设置：

域变量覆盖率：确保域部分中使用的所有变量 URLs 都有相应的 ConfigurationAliases 条目
别名完整性：验证所有可能的玩家参数值是否都作为键包含在别名映射中
JSON 结构：验证 ConfigurationAliases JSON 的格式和嵌套是否正确
参数命名：确认所有玩家参数都使用前player_params.缀
值一致性：确保别名值对于其预期用途（URLs、配置文件名称等）有效

调试配置别名解析

按照这种系统的方法来调试配置别名解析问题。

Step-by-step 调试方法

使用以下步骤来识别和解决配置别名问题：

配置别名调试程序

验证配置结构：确认您的播放配置包括格式正确的内容 ConfigurationAliases


{
    "ConfigurationAliases": {
        "player_params.example_param": {
            "alias1": "value1",
            "alias2": "value2"
        }
    }
}

检查玩家参数格式：确保会话初始化包括格式正确的玩家参数
```
{
    "playerParams": {
        "example_param": "alias1"
    }
}
```
验证别名映射：确认玩家参数值 (“alias1") 作为键存在于映射中 ConfigurationAliases
使用简单配置进行测试：从最低配置开始以找出问题
监控错误响应：检查 MediaTailor错误响应中是否有特定的验证消息
验证已解决 URLs：确认最终解决方案有效 URLs 且可访问

配置别名最佳实践

请遵循这些最佳实践，以确保可靠的配置别名实现。

安全性注意事项

使用配置别名时，请实施以下安全措施：

输入验证：在别名解析中使用所有玩家参数值之前，请先对其进行验证
别名值清理：确保别名值仅包含预期的字符和格式
域名限制：将域别名限制为可信、受控的域名
访问控制：仅限授权人员修改配置

性能优化

使用以下建议优化配置别名性能：

尽量减少别名数：仅使用必要的别名以减少处理开销
高效命名：对别名和参数使用清晰、一致的命名约定
默认值：为常见用例提供合理的默认别名
配置缓存：利用 MediaTailor配置缓存提高性能

维护和监控

通过以下做法保持可靠的配置别名操作：

定期验证：定期验证所有别名映射是否为最新且功能正常
错误监控：监控与别名缺失或无效相关的 HTTP 400 错误
文档：保持所有别名映射及其用途的清晰文档
测试程序：对所有别名组合实施全面测试

有关使用动态域、会话和玩家变量的更多信息，请选择适用的主题。

主题

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

预处理广告

MediaTailor 参数疑难解答