Pod Serving API 目前处于封闭式 Beta 版测试阶段。如果您有兴趣详细了解 Pod Serving 或想要实现 Pod Serving API，请与您的 Google 客户经理联系。

此页面由 Cloud Translation API 翻译。

动态广告插播广告连播投放实时 API

借助 Dynamic Ad Insert API，您可以请求和跟踪 DAI 直播。

服务：dai.google.com

所有 URI 均相对于 https://dai.google.com。

方法：stream

方法
`stream`	`POST /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream` 注册 DAI DAI pod 投放直播会话。

HTTP 请求

POST https://dai.google.com/ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

路径参数

参数
`network_code`	`string` 发布商的 Google Ad Manager 广告资源网代码。
`custom_asset_key`	`string` Google Ad Manager 中与此事件相关联的自定义标识符。

请求正文

请求正文的类型为 application/x-www-form-urlencoded 并包含以下参数：

参数
DFP 定位参数	可选	其他定位参数。
替换视频流参数	可选	替换数据流创建参数的默认值。
HMAC 身份验证	可选	使用基于 HMAC 的令牌进行身份验证。

响应正文

如果成功，响应正文将包含一个新的 Stream 对象。

开放式衡量

DAI API 的 Verifications 字段中包含 Open Measurement 验证信息。此字段包含一个或多个 Verification 元素，其中列出了执行第三方衡量代码以验证广告素材播放所需的资源和元数据。仅支持 JavaScriptResource。如需了解详情，请参阅 IAB Tech Lab 和 VAST 4.1 规范。

方法：广告连播细分

方法
`pod segment`	`GET /linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/{pod_identifier}/profile/{profile_name}/{segment_number}.{segment_format}` 为给定事件 ID 创建 DAI 数据流。

HTTP 请求

GET https://dai.google.com/linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/{pod_identifier}/profile/{profile_name}/{segment_number}.{segment_format}

路径参数

参数
`network_code`	`string` 发布商的 Google Ad Manager 广告资源网代码。
`custom_asset_key`	`string` Google Ad Manager 中与此事件相关联的自定义标识符。
`pod_identifier`	支持以下格式： `pod/{integer}` 当前广告插播时间点的数字标识符。系统会为每个广告插播事件逐个分配广告连播 ID，从 `1` 开始。 `ad_break_id/{string}` 当前广告插播时间点的字符串标识符。重要提示：对于在直播事件中观看同一广告插播的所有用户，`pod_identifier` 的格式和值必须相同。清单操作程序必须在直播活动的整个生命周期内插入相同的 `pod_identifier` 格式。
`profile_name`	`string` 所请求的 Google Ad Manager DAI 编码配置文件的名称。编码配置文件必须是为所选事件配置的编码配置文件之一。
`segment_number`	`integer` 当前广告连播中所请求的细分受众群的索引（从零开始）。重要提示：使用 MP4 容器时，可以通过将 `segment_number` 设置为 `init` 来请求初始化片段。
`segment_format`	`string` 与请求的片段格式关联的文件扩展名。接受的扩展名包括：`ts`、`mp4`、`vtt`、`aac`、`ac3` 或 `eac3`。

查询参数

参数

stream_id

required

string

当前用户会话的串流 ID。对 stream 端点的成功请求会返回此值。

sd

required¹

integer

请求的片段的时长（以毫秒为单位）。

so

可选

请求的广告连播中相应广告片段的偏移量（以毫秒为单位）。如果您省略 so 参数，系统会通过片段时长乘以片段编号来计算此值。

pd

必需²

integer

广告连播的时长（以毫秒为单位）。

auth-token

required

string

当前广告连播的经过签名的网址编码 HMAC 令牌。

last

可选

boolean

表示广告插播时间点中的最后一个片段。对于所有其他细分，省略此参数。

scte35

可选

string

此广告插播时间点的 Base64 编码 SCTE-35 信号。

cust_params

可选

string

一组用于 Ad Manager 广告系列定位的键值对。这些对必须表示为经过网址编码的查询字符串。

示例：

参数	section = `sports` page = `golf,tennis`
`Request URL`	`...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...`

脚注

初始化段不需要 sd。 ↩
对于启用了无时长的广告插播的事件，无需使用 pd。 ↩

示例

GET https://dai.google.com/linear/pods/v1/seg/network/sandbox_dev/custom_asset/podserving-segredirect-custom-key/ad_break_id/adbreak-2/profile/8b8888cf79ad43f0800482ffc035a1ac_ts_a/1.ts?so=0&sd=10000&pd=30000&stream_id=8e19cbc6-850b-404c-99d7-860aa4a674cb:TEST

GET

响应正文

如果成功，响应正文将是一个与请求中指定的格式和参数匹配的可播放流片段。

方法：HLS 广告连播清单

检索直播的 HLS 广告连播清单，以便客户端视频播放器加载和播放。

方法
`GET`	`GET /linear/pods/v1/hls/network/{network_code}/custom_asset/{custom_asset}/pod/{pod_id}.m3u8;` 用于检索广告连播的 HLS 多变体播放列表的 API。

HTTP 请求

GET https://dai.google.com/linear/pods/v1/hls/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}.m3u8?stream_id={stream_id}&pd={pod_duration}

路径参数

参数
`network_code`	`string` 发布商的 Google Ad Manager 广告资源网代码。
`custom_asset_key`	`string` Google Ad Manager 中与此事件相关联的自定义标识符
`pod_id`	`integer` 当前广告插播时间点的数字标识符。系统会为每个广告插播事件逐个分配广告连播 ID，从 `1` 开始。对于当前事件中观看同一广告插播的所有用户，`pod_id` 必须相同。

查询参数

参数

stream_id

必需

string

当前用户会话的串流 ID。对 stream 端点的成功请求会返回此值。

pd

必需

integer

广告连播的时长（以毫秒为单位）。

scte35

可选

string

此广告插播时间点的 Base64 编码 SCTE-35 信号。

cust_params

可选

string

一组用于 Ad Manager 广告系列定位的键值对。这些对必须表示为经过网址编码的查询字符串。

示例：

参数	section = `sports` page = `golf,tennis`
`Request URL`	`...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...`

响应正文

如果成功，响应正文将是一个 HLS 多变体播放列表。

方法：DASH 广告连播清单

检索直播的 MPEG-DASH 广告连播清单，以便客户端视频播放器加载和播放。

方法
`GET`	`GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset}/stream/{stream_id}/pod/{pod_id}/manifest.mpd` 用于检索广告连播的 MPEG-DASH mpd 播放列表的 API。

HTTP 请求

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/stream/{stream_id}/pod/{pod_id}/manifest.mpd?pd={pod_duration}

路径参数

参数
`network_code`	`string` 发布商的 Google Ad Manager 广告资源网代码。
`custom_asset_key`	`string` 在 Google Ad Manager 中与此事件关联的自定义标识符
`stream_id`	`string` 当前用户会话的视频流 ID。成功向 `stream` 端点发出请求时，系统会返回此值。
`pod_id`	`integer` 当前广告插播时间点的数字标识符。系统会为每个广告插播事件逐个分配广告连播 ID，从 `1` 开始。对于当前事件中观看同一广告插播的所有用户，`pod_id` 必须相同。

查询参数

参数

pd

必需

integer

广告连播的时长（以毫秒为单位）。

scte35

可选

string

此广告插播时间点的 Base64 编码 SCTE-35 信号。

cust_params

可选

string

一组用于 Ad Manager 广告系列定位的键值对。这些对必须表示为经过网址编码的查询字符串。

示例：

参数	section = `sports` page = `golf,tennis`
`Request URL`	`...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...`

响应正文

如果成功，响应正文将是一个 MPEG-DASH mpd 播放列表。

方法：DASH pod 时间段模板

方法

方法
`pods`	`GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json` 向 Google Ad Manager 请求 DASH 时间段模板。此模板包含您必须使用视频流参数填充的宏。填充这些宏后，模板就会成为广告插播时间点，并且可以缝合到您的 DASH 清单中。重要提示：每次直播会话仅请求一次此模板，然后可对其进行缓存，以便在每个广告插播时间点重复使用。

pods

GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

向 Google Ad Manager 请求 DASH 时间段模板。此模板包含您必须使用视频流参数填充的宏。填充这些宏后，模板就会成为广告插播时间点，并且可以缝合到您的 DASH 清单中。

HTTP 请求

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

路径参数

参数
`network_code`	`string` 发布商的 Google Ad Manager 广告资源网代码。
`custom_asset_key`	`string` Google Ad Manager 中与此事件相关联的自定义标识符。

查询参数

参数
`stream_id`	required	`string` 当前用户会话的串流 ID。成功向 `stream` 端点发出请求时，系统会返回此值。

响应正文

如果成功，响应正文将包含一个新的 PodTemplateResponse 对象。

方法：媒体验证

在播放过程中遇到广告媒体标识符后，立即使用上文中从 stream 端点获取的 media_verification_url 发出请求。对于服务器端信标串流（服务器发起媒体验证），这些请求不是必需的。

对 media verification 端点的请求是幂等的。

方法
`media verification`	`GET /{media_verification_url}/{ad_media_id}` 向 API 通知媒体验证事件。

HTTP 请求

GET https://{media-verification-url}/{ad-media-id}

响应正文

media verification 会返回以下响应：

如果媒体验证成功且已发送所有 ping，则为 HTTP/1.1 204 No Content。
如果请求因网址格式不正确或到期时间而无法验证媒体，则为 HTTP/1.1 404 Not Found。
HTTP/1.1 404 Not Found（如果之前针对此 ID 的验证请求已成功）。
HTTP/1.1 409 Conflict，如果此时有其他请求正在发送 ping。

广告媒体 ID

广告媒体标识符将编码在单独的元数据轨道中，即 HLS 传输流的时间戳元数据或 mp4 文件的 emsg。广告媒体标识符始终以字符串 google_ 开头。

在发出每个广告验证请求之前，应将元数据条目的全部文本内容附加到广告验证网址中。

方法：metadata

位于 metadata_url 的元数据端点会返回用于构建广告界面的信息。元数据端点不适用于服务器端信标串流，在这种情况下，服务器负责发起广告媒体验证。

方法
`metadata`	`GET /{metadata_url}/{ad-media-id}` `GET /{metadata_url}` 检索广告元数据信息。

HTTP 请求

GET https://{metadata_url}/{ad-media-id}

GET https://{metadata_url}

响应正文

如果成功，响应将返回一个 PodMetadata 实例。

解析元数据

元数据分为三个部分：tags、ads 和广告 breaks。数据的入口点是 tags 部分。然后，迭代标记，找到名称是视频串流中找到的广告媒体 ID 前缀的第一个条目。例如，您的广告媒体 ID 可能如下所示：

google_1234567890

然后，您会找到一个名为 google_12345 的标记对象。在本例中，它与您的广告媒体 ID 匹配。找到正确的广告媒体前缀对象后，您可以查找广告 ID、广告插播 ID 和事件类型。然后，广告 ID 用于为 ads 对象编制索引，广告插播 ID 用于为 breaks 对象编制索引。

响应数据

数据流

用于以 JSON 格式呈现新创建的串流的资源列表。

JSON 表示法
{ "stream_id": string, "media_verification_url": string, "metadata_url": string, "session_update_url": string, "heartbeat_url": string, "polling_frequency": number, "pod_manifest_url": string, "manifest_format": string, }

JSON 表示法

{
  "stream_id": string,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "heartbeat_url": string,
  "polling_frequency": number,
  "pod_manifest_url": string,
  "manifest_format": string,
}

字段
`stream_id`	`string` GAM 数据流标识符。
`media_verification_url`	`string` 用作跟踪播放事件的基本端点的媒体验证网址。
`metadata_url`	`string` 用于轮询与即将进行的直播广告活动的定期信息有关的元数据网址。
`session_update_url`	`string` 用于更新此视频流的定位参数的会话更新网址。系统会在初始视频流创建请求期间捕获定位参数的原始值。
`heartbeat_url`	`string` 心跳 URL，用于保持服务器端信标流的活跃状态，必须每 {PollingFrequency} 秒 ping 一次。为服务器端信标流填充。
`polling_frequency`	`number` 请求 metadata_url 或 heartbeat_url 时的轮询频率（以秒为单位）。
`pod_manifest_url`	`string` 广告连播清单网址模板用于生成用于检索直播的广告连播清单的网址，对应于 HLS 中的多变体播放列表的网址或 DASH 中的 MPD。系统会为动态广告插播类型为 POD_SERVING_MANIFEST 的直播事件填充此字段。 https://developers.google.com/ad-manager/api/reference/v202305/LiveStreamEventService.DynamicAdInsertionType
`manifest_format`	`string` 清单格式是指从 pod_manifest_url 检索到的清单的格式，可以是 dash 或 hls。

PodMetadata

PodMetadata 包含有关广告、广告插播时间点和媒体 ID 代码的元数据信息。

JSON 表示法
{ "tags": map[string, object(TagSegment)], "ads": map[string, object(Ad)], "ad_breaks": map[string, object(AdBreak)], }

字段
`tags`	`map[string, object(TagSegment)]` 按标记前缀编入索引的代码段地图。
`ads`	`map[string, object(Ad)]` 按广告 ID 编入索引的广告映射。
`ad_breaks`	`map[string, object(AdBreak)]` 按广告插播 ID 编入索引的广告插播映射。

TagSegment

TagSegment 包含对广告、其广告插播时间点和事件类型的引用。不应向广告媒体验证端点 ping 类型为“progress”的 TagSegment。

JSON 表示法
{ "ad": string, "ad_break_id": string, "type": string, }

字段
`ad`	`string` 此代码所对应的广告的 ID。
`ad_break_id`	`string` 此代码的广告插播时段的 ID。
`type`	`string` 此代码的事件类型。

AdBreak

AdBreak 用于描述直播中的单个广告插播。它包含时长、类型（中间/前/后）和广告数量。

JSON 表示法
{ "type": string, "duration": number, "expected_duration": number, "ads": number, }

字段
`type`	`string` 有效的休息类型包括：前、中和后。
`duration`	`number` 此广告插播的总广告时长（以秒为单位）。
`expected_duration`	`number` 广告插播时间点的预计时长（以秒为单位），包括所有广告和所有可选广告。
`ads`	`number` 广告插播时间点中的广告数量。

JSON 表示法
{ "ad_break_id": string, "position": number, "duration": number, "title": string, "description": string, "advertiser": string, "ad_system": string, "ad_id": string, "creative_id": string, "creative_ad_id": string, "deal_id": string, "clickthrough_url": string, "click_tracking_urls": [], "verifications": [object(Verification)], "slate": boolean, "icons": [object(Icon)], "wrappers": [object(Wrapper)], "universal_ad_id": object(UniversalAdID), "extensions": [], "companions": [object(Companion)], "interactive_file": object(InteractiveFile), }

{
  "ad_break_id": string,
  "position": number,
  "duration": number,
  "title": string,
  "description": string,
  "advertiser": string,
  "ad_system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
  "clickthrough_url": string,
  "click_tracking_urls": [],
  "verifications": [object(Verification)],
  "slate": boolean,
  "icons": [object(Icon)],
  "wrappers": [object(Wrapper)],
  "universal_ad_id": object(UniversalAdID),
  "extensions": [],
  "companions": [object(Companion)],
  "interactive_file": object(InteractiveFile),
}

字段
`ad_break_id`	`string` 此广告的广告插播时段的 ID。
`position`	`number` 此广告在广告插播时段中的位置，从 1 开始。
`duration`	`number` 广告时长（以秒为单位）。
`title`	`string` 广告的标题（可选）。
`description`	`string` 广告的可选广告内容描述。
`advertiser`	`string` 可选的广告客户标识符。
`ad_system`	`string` 可选广告系统。
`ad_id`	`string` 可选广告 ID。
`creative_id`	`string` 可选广告素材 ID。
`creative_ad_id`	`string` 可选的广告素材广告 ID。
`deal_id`	`string` 可选的交易 ID。
`clickthrough_url`	`string` 可选的点击后到达网址。
`click_tracking_urls`	`string` 可选的点击跟踪网址。
`verifications`	`[object(Verification)]` 可选的 Open Measurement 验证条目，其中会列出执行第三方衡量代码以验证广告素材播放所需的资源和元数据。
`slate`	`boolean` 可选布尔值，表示当前条目是可选广告。
`icons`	`[object(Icon)]` 图标列表，如果为空则省略。
`wrappers`	`[object(Wrapper)]` 封装容器列表，如果为空，则省略。
`universal_ad_id`	`object(UniversalAdID)` 可选的通用广告 ID。
`extensions`	`string` VAST 中所有 <Extension> 节点的可选列表。
`companions`	`[object(Companion)]` 可选随播广告，可与此广告一起展示。
`interactive_file`	`object(InteractiveFile)` 应在广告播放期间展示的可选互动广告素材 (SIMID)。

PodTemplateResponse

PodTemplateResponse 表示返回给 VTP 以进行 pod 拼接的 JSON 载荷。

JSON 表示法
{ "dash_period_template": string, "segment_duration_ms": int64, }

字段
`dash_period_template`	`string` DashPeriodTemplate 是该时间段的 XML 模板，该模板在拼接前填充了适当的数据。
`segment_duration_ms`	`int64` SegmentDurationMS 是时段细分的时长（以毫秒为单位）。

图标

Icon 包含有关 VAST 图标的信息。

JSON 表示法
{ "click_data": object(ClickData), "creative_type": string, "click_fallback_images": [object(FallbackImage)], "height": int32, "width": int32, "resource": string, "type": string, "x_position": string, "y_position": string, "program": string, "alt_text": string, }

JSON 表示法

{
  "click_data": object(ClickData),
  "creative_type": string,
  "click_fallback_images": [object(FallbackImage)],
  "height": int32,
  "width": int32,
  "resource": string,
  "type": string,
  "x_position": string,
  "y_position": string,
  "program": string,
  "alt_text": string,
}

字段
`click_data`	`object(ClickData)`
`creative_type`	`string`
`click_fallback_images`	`[object(FallbackImage)]`
`height`	`int32`
`width`	`int32`
`resource`	`string`
`type`	`string`
`x_position`	`string`
`y_position`	`string`
`program`	`string`
`alt_text`	`string`

ClickData

ClickData 包含有关图标点击的信息。

JSON 表示法
{ "url": string, }

字段
`url`	`string`

FallbackImage

FallbackImage 包含 VAST 后备图片的相关信息。

JSON 表示法
{ "creative_type": string, "height": int32, "width": int32, "resource": string, "alt_text": string, }

字段
`creative_type`	`string`
`height`	`int32`
`width`	`int32`
`resource`	`string`
`alt_text`	`string`

Wrapper

Wrapper 包含封装容器广告的相关信息。如果不存在交易 ID，则不包含交易 ID。

JSON 表示法
{ "system": string, "ad_id": string, "creative_id": string, "creative_ad_id": string, "deal_id": string, }

字段
`system`	`string` 广告系统标识符。
`ad_id`	`string` 用于封装容器广告的广告 ID。
`creative_id`	`string` 用于封装容器广告的广告素材 ID。
`creative_ad_id`	`string` 用于封装容器广告的广告素材 ID。
`deal_id`	`string` 可选的封装容器广告交易 ID。

验证

“验证”部分包含 Open Measurement 的信息，有助于第三方可见度和验证衡量。目前仅支持 JavaScript 资源。请参阅 https://iabtechlab.com/standards/open-measurement-sdk/

JSON 表示法
{ "vendor": string, "java_script_resources": [object(JavaScriptResource)], "tracking_events": [object(TrackingEvent)], "parameters": string, }

字段
`vendor`	`string` 验证供应商。
`java_script_resources`	`[object(JavaScriptResource)]` 用于验证的 JavaScript 资源列表。
`tracking_events`	`[object(TrackingEvent)]` 用于验证的跟踪事件列表。
`parameters`	`string` 传递给引导程序验证代码的不透明字符串。

JavaScriptResource

JavaScriptResource 包含用于通过 JavaScript 进行验证的信息。

JSON 表示法
{ "script_url": string, "api_framework": string, "browser_optional": boolean, }

字段
`script_url`	`string` JavaScript 载荷的 URI。
`api_framework`	`string` APIFramework 是执行验证码的视频框架的名称。
`browser_optional`	`boolean` 此脚本是否可以在浏览器之外运行。

TrackingEvent

TrackingEvent 包含客户端在特定情况下应对其执行 ping 操作的网址。

JSON 表示法
{ "event": string, "uri": string, }

字段
`event`	`string` 跟踪事件的类型。
`uri`	`string` 要进行 ping 的跟踪事件。

UniversalAdID

UniversalAdID 用于提供在各个广告系统中维护的唯一广告素材标识符。

JSON 表示法
{ "id_value": string, "id_registry": string, }

字段
`id_value`	`string` 广告所选广告素材的通用广告 ID。
`id_registry`	`string` 一个字符串，用于标识注册库网站的网址，其中包含所选广告素材的通用广告 ID 目录。

随播广告

随播广告包含可与广告一起展示的随播广告的相关信息。

JSON 表示法
{ "click_data": object(ClickData), "creative_type": string, "height": int32, "width": int32, "resource": string, "type": string, "ad_slot_id": string, "api_framework": string, "tracking_events": [object(TrackingEvent)], }

JSON 表示法

{
  "click_data": object(ClickData),
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "type": string,
  "ad_slot_id": string,
  "api_framework": string,
  "tracking_events": [object(TrackingEvent)],
}

字段
`click_data`	`object(ClickData)` 此随播广告的点击数据。
`creative_type`	`string` VAST 中 <StaticResource> 节点上的 CreativeType 属性（如果它是静态类型的随播广告素材）。
`height`	`int32` 此配套项的高度（以像素为单位）。
`width`	`int32` 此随播广告的宽度（以像素为单位）。
`resource`	`string` 对于静态和 iframe 随播广告，这将成为要加载和显示的网址。对于 HTML 随播广告，这应是应作为随播广告显示的 HTML 代码段。
`type`	`string` 此随播广告素材的类型。它可以是静态、iframe 或 HTML。
`ad_slot_id`	`string` 此随播广告的广告位 ID。
`api_framework`	`string` 此配套应用的 API 框架。
`tracking_events`	`[object(TrackingEvent)]` 此配套应用的跟踪事件列表。

InteractiveFile

InteractiveFile 包含应在广告播放期间显示的互动式广告素材（即 SIMID）的信息。

JSON 表示法
{ "resource": string, "type": string, "variable_duration": boolean, "ad_parameters": string, }

字段
`resource`	`string` 指向互动广告素材的网址。
`type`	`string` 作为资源提供的文件的 MIME 类型。
`variable_duration`	`boolean` 此广告素材是否会请求延长时长。
`ad_parameters`	`string` VAST 中的 <AdParameters> 节点的值。