DAI API 目前处于 Beta 版阶段，在您的广告资源网中可能无法使用。如需了解详情，请与您的客户经理联系。我们建议在提供 IMA SDK 的平台上使用该 SDK。

此页面由 Cloud Translation API 翻译。

动态广告插播 VOD API

借助 Dynamic Ad Insertion API，您可以请求和跟踪 DAI 视频点播 (VOD) 串流。支持 HLS 和 DASH 串流。

服务：dai.google.com

stream 方法的路径相对于 https://dai.google.com

方法：串流

方法

方法
`stream`	`POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream` 为指定的内容来源和视频 ID 创建 HLS DAI 串流。 `POST /ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream` 为指定的内容来源和视频 ID 创建 DASH DAI 串流。

stream

POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

为指定的内容来源和视频 ID 创建 HLS DAI 串流。

POST /ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream

为指定的内容来源和视频 ID 创建 DASH DAI 串流。

HTTP 请求

POST https://dai.google.com/ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

POST https://dai.google.com/ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream

请求标头

参数

参数
`api‑key`	`string` 创建数据流时提供的 API 密钥必须对发布商的广告联盟有效。您可以将 API 密钥传递在 HTTP Authorization 标头中，而不是在请求正文中提供，格式如下： Authorization: DCLKDAI key="<api-key>"

api‑key

string

创建数据流时提供的 API 密钥必须对发布商的广告联盟有效。

您可以将 API 密钥传递在 HTTP Authorization 标头中，而不是在请求正文中提供，格式如下：

Authorization: DCLKDAI key="<api-key>"

路径参数

参数
`content-source`	`string` 数据流的 CMS ID。
`video-id`	`string` 直播的视频 ID。

请求正文

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

参数
`dai-ssb`	可选	设置为 `true` 可创建服务器端信标流。默认值为 `false`。默认数据流的跟踪由客户端发起，并在服务器端进行 ping。
DFP 定位参数	可选	其他定位参数。
替换视频流参数	可选	替换视频流创建参数的默认值。
HMAC 身份验证	可选	使用基于 HMAC 的令牌进行身份验证。

响应正文

如果成功，响应正文将包含一个新的 Stream。对于服务器端信标串流，此 Stream 仅包含 stream_id 和 stream_manifest 字段。

Open Measurement

Verifications 字段包含用于对非服务器端信标流进行 Open Measurement 验证的信息。Verifications 包含一个或多个 Verification 元素，其中列出了您需要使用第三方衡量代码验证广告素材播放情况的资源和元数据。仅支持 JavaScriptResource。如需了解详情，请参阅 IAB Tech Lab 和 VAST 4.1 规范。

方法：媒体验证

在播放过程中遇到广告媒体标识符后，请立即使用 stream 端点中的 media_verification_url 发出请求。media_verification_url 是绝对路径。对于服务器端信标流式传输，无需发出媒体验证请求，因为服务器会发起媒体验证。

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

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

HTTP 请求

GET {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，如果之前针对此身份证件的验证请求已成功。
HTTP/1.1 409 Conflict，如果此时有其他请求正在发送 ping。

广告媒体 ID (HLS)

广告媒体标识符将使用键 TXXX 编码在 HLS 时间戳元数据中，该键预留用于“用户定义的文本信息”帧。帧的内容将不加密，并且始终以文本 "google_" 开头。

应将框架的完整文本内容附加到每个广告验证请求的 media_verification_url。

广告媒体 ID (DASH)

广告媒体标识符将通过使用 DASH 的 EventStream 元素插入清单中。

每个 EventStream 的 Scheme ID URI 均为 urn:google:dai:2018。这些事件的 messageData 属性将包含以 “google_” 开头的广告媒体 ID。应将 messageData 属性的全部内容附加到每个广告验证请求的 media_verification_url。

响应数据

数据流

Stream 用于以 JSON 格式呈现新创建的数据流的所有资源列表。

JSON 表示法
{ "stream_id": string, "total_duration": number, "content_duration": number, "valid_for": string, "valid_until": string, "subtitles": [object(Subtitle)], "hls_master_playlist": string, "stream_manifest": string, "media_verification_url": string, "apple_tv": object(AppleTV), "ad_breaks": [object(AdBreak)], }

JSON 表示法

{
  "stream_id": string,
  "total_duration": number,
  "content_duration": number,
  "valid_for": string,
  "valid_until": string,
  "subtitles": [object(Subtitle)],
  "hls_master_playlist": string,
  "stream_manifest": string,
  "media_verification_url": string,
  "apple_tv": object(AppleTV),
  "ad_breaks": [object(AdBreak)],
}

字段
`stream_id`	`string` 数据流标识符。
`total_duration`	`number` 直播时长（以秒为单位）。
`content_duration`	`number` 内容时长（不含广告，以秒为单位）。
`valid_for`	`string` 时长串流有效，格式为“00h00m00s”。
`valid_until`	`string` 数据流有效期的截止日期（采用 RFC 3339 格式）。
`subtitles`	`[object(Subtitle)]` 字幕列表。如果为空，则省略。仅限 HLS。
`hls_master_playlist`	`string` （已废弃）HLS 主播放列表网址。使用 stream_manifest。仅限 HLS。
`stream_manifest`	`string` 数据流的清单。对应于 HLS 中的主播放列表和 DASH 中的 MPD。在创建服务器端信标串流时，除了“stream_id”之外，响应中只会出现此字段。
`media_verification_url`	`string` 媒体验证网址。
`apple_tv`	`object(AppleTV)` 特定于 AppleTV 设备的可选信息。仅限 HLS。
`ad_breaks`	`[object(AdBreak)]` 广告插播列表。如果为空，则省略。

AppleTV

AppleTV 包含特定于 Apple TV 设备的信息。

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

字段
`interstitials_url`	`string` 插页式广告网址。

AdBreak

AdBreak 用于描述直播中的单个广告插播。它包含位置、时长、类型（插播/前贴片/后贴片）和广告列表。

JSON 表示法
{ "type": string, "start": number, "duration": number, "ads": [object(Ad)], }

字段
`type`	`string` 有效的休息类型包括：mid、pre 和 post。
`start`	`number` 广告插播开始时刻在直播中的秒数位置。
`duration`	`number` 广告插播时长（以秒为单位）。
`ads`	`[object(Ad)]` 广告列表。如果为空，则省略。

JSON 表示法
{ "seq": number, "start": 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, "icons": [object(Icon)], "wrappers": [object(Wrapper)], "events": [object(Event)], "verifications": [object(Verification)], "universal_ad_id": object(UniversalAdID), "companions": [object(Companion)], "interactive_file": object(InteractiveFile), "skip_metadata": object(SkipMetadata), "extensions": [], }

{
  "seq": number,
  "start": 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,
  "icons": [object(Icon)],
  "wrappers": [object(Wrapper)],
  "events": [object(Event)],
  "verifications": [object(Verification)],
  "universal_ad_id": object(UniversalAdID),
  "companions": [object(Companion)],
  "interactive_file": object(InteractiveFile),
  "skip_metadata": object(SkipMetadata),
  "extensions": [],
}

字段
`seq`	`number` 广告在广告插播时段中的位置。
`start`	`number` 广告在视频流中的开始位置（以秒为单位）。
`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` 可选的点击后到达网址。
`icons`	`[object(Icon)]` 图标列表，如果为空则省略。
`wrappers`	`[object(Wrapper)]` 封装容器列表。如果为空，则省略。
`events`	`[object(Event)]` 广告中的事件列表。
`verifications`	`[object(Verification)]` 可选的 Open Measurement 验证条目，其中列出了执行第三方衡量代码以验证广告素材播放所需的资源和元数据。
`universal_ad_id`	`object(UniversalAdID)` 可选的通用广告 ID。
`companions`	`[object(Companion)]` 可选随播广告，可与此广告一起展示。
`interactive_file`	`object(InteractiveFile)` 应在广告播放期间展示的可选互动式广告素材 (SIMID)。
`skip_metadata`	`object(SkipMetadata)` 可跳过式广告的可选元数据。如果设置了此属性，则表示广告可跳过，并包含有关如何处理跳过界面和跟踪事件的说明。
`extensions`	`string` VAST 中所有 <Extension> 节点的可选列表。

事件

Event 包含事件类型和事件的呈现时间。

JSON 表示法
{ "time": number, "type": string, }

字段
`time`	`number` 此活动的展示时间。
`type`	`string` 此事件的类型。

副标题

字幕用于描述视频流的旁边字幕轨道。它存储两种字幕格式：TTML 和 WebVTT。TTMLPath 属性包含 TTML 旁加文件的网址，WebVTTPath 属性同样包含 WebVTT 旁加文件的网址。

JSON 表示法
{ "language": string, "language_name": string, "ttml": string, "webvtt": string, }

字段
`language`	`string` 语言代码，例如“en”或“de”。
`language_name`	`string` 语言的描述性名称。如果同一语言存在多组字幕，则用于区分特定字幕组
`ttml`	`string` 指向 TTML 辅助文件的可选网址。
`webvtt`	`string` 指向 WebVTT 辅助文件的可选网址。

SkipMetadata

SkipMetadata 会提供客户端处理可跳过广告的跳过事件所需的信息。

JSON 表示法
{ "offset": number, "tracking_url": string, }

字段
`offset`	`number` 偏移量表示播放器应等待广告播放多少秒后才能呈现“跳过”按钮。如果未在 VAST 中提供，则省略。
`tracking_url`	`string` Tracking网址包含应在跳过事件时对其执行 ping 操作的网址。

图标

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 目录。

随播广告

companion 包含可能随广告一起显示的随播广告的信息。

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` 如果随播广告素材类型为 static，则为 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> 节点的值。

动态广告插播 VOD API 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

服务：dai.google.com

方法：串流

HTTP 请求

请求标头

路径参数

请求正文

响应正文

Open Measurement

方法：媒体验证

HTTP 请求

响应正文

广告媒体 ID (HLS)

广告媒体 ID (DASH)

响应数据

数据流

AppleTV

AdBreak

广告

事件

副标题

SkipMetadata

图标

ClickData

FallbackImage

Wrapper

验证

JavaScriptResource

TrackingEvent

UniversalAdID

随播广告

InteractiveFile

动态广告插播 VOD API