Early ad break notification

使用 Early Ad Break Notification API

注意：此 API 仍处于 Beta 版阶段。如果您想申请 EABN 计划的访问权限，请与您的客户经理联系。

广告插播提前通知 (EABN) API 可让您在广告插播开始前，通过其元数据通知 Google Ad Manager 即将到来的广告插播时间点。您可以在广告插播时间点之前最长 1 小时发送通知请求。本指南介绍了如何启用和使用 EABN API，以及请求和响应示例。

注意：EABN 请求是不可变的，因此，插入点一经创建便无法修改。系统会拒绝为同一活动创建广告插播的后续请求，直到相应广告插播显示在该活动的清单中。

对 EABN API 的调用必须包含以下信息：

  • 正在为其创建广告插播时间点的相应直播活动的标识符。此标识符可以是下列其中一项：
  • 直播的“Asset Key”。
  • 直播活动的“自定义素材资源键”，可让您通过指定自己的标识符字符串来管理自己的键空间。
  • 直播活动的“内容来源 ID”和“Content ID”。

注意：您必须有权使用此标识符类型。如需了解详情，请与您的客户经理联系。

  • 下一个广告插播时间点的预计时长。时长需尽可能接近实际的广告插播时长。

除了这些必填字段之外，您还可以发送自定义定位参数、要应用的广告连播模板的名称或 SCTE35 Cue Out 数据（如果有）。

前提条件

若要使用 EABN API，您必须创建一个服务账号，并将该账号添加到您的 Google Ad Manager 广告资源网。

创建服务账号

如需创建用于调用 EABN API 的服务账号，请完成以下步骤：- 如果您有 Google Cloud 账号，请使用 IAM 模块创建服务账号。如需了解详情，请参阅创建和管理服务账号。- 如果您没有 Google Cloud 账号，请完成以下步骤，通过 Google API 控制台创建一个：

  1. 创建新项目或选择现有项目。
  2. 在凭据页面中，点击管理服务账号。
  3. 在服务账号页面中，点击创建服务账号。
  4. 在创建服务账号页面中，输入账号详细信息。然后，点击创建。

创建服务账号后，请复制该账号用于身份验证的 JSON 密钥。

向 Google Ad Manager 广告联盟添加服务账号

如需向网络添加服务账号，请完成添加服务账号用户以获取 API 访问权限中的步骤。

启用 API

创建服务账号后，请向客户经理提供以下信息，以便为您的账号启用 API：

  • 您的 Google Cloud 账号电子邮件地址
  • 您的服务账号
  • 您的 Google Ad Manager 广告资源网的广告资源网代码。

在客户经理启用此 API 后，请完成以下步骤以启用 API：

  1. 在 Google API 库中，搜索“Google Ad Manager Video API”。
  2. 点击启用。

注意：如果该 API 未出现在搜索结果中，请与您的客户经理联系，以确认您的账号已启用 DAI API。

使用此 API

您可以使用 JSON/REST 请求调用 EABN API。

授权

如需对 EABN API 进行授权调用，您需要使用服务账号中的 JSON 密钥和 https://www.googleapis.com/auth/video-ads 范围生成 OAuth2 服务账号凭据。有关详情，请参阅针对服务器对服务器应用使用 OAuth 2.0。

每次调用 EABN API 时，都必须添加生成的授权令牌作为 Auth 标头。

发送广告插播提前通知

若要发送广告插播提前通知，请发送 POST 请求至三个有效的 EABN 网址之一，具体取决于您要以何种方式指定直播视频流。以下部分介绍了网址之间的区别，并提供了请求和响应示例。

网址

广告插播提前通知有 3 个有效的网址。您可以使用这三种类型来创建广告插播时间点 (POST) 或获取已分配的广告插播时间点的列表 (GET)。

如需使用直播活动的素材资源键，请使用以下代码：

POST admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks

如需使用直播活动的自定义素材资源键，请使用以下代码：

POST admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks

要使用 Content Source ID 和 Content ID 方法，请使用：

POST admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks

对于所有参数：

  • network_code 表示您的 Google Ad Manager 广告资源网的广告资源网代码。
  • asset_key 代表直播详情页面中显示的素材资源键。
  • custom_asset_key 表示直播活动的自定义素材资源键。
  • content_source_id 表示 Google Ad Manager 中内容来源的 ID。
  • content_id 表示 Google Ad Manager 中一段内容的 ID。

注意：指定的 content_source_id/content_id 对必须与 Google Ad Manager 中的直播活动相关联。

请求正文 - 仅用于创建广告插播 (POST)

对象

expectedDuration

 必填 此广告插播时间点的时长，使用 Google 的标准时长格式（xx.xxxs，其中 xx.xxx 表示秒数）

customParams

 可选 在 AM360 中，将添加到此广告插播时间点的广告请求中且用于自定义条件定位的键值对，各键值对以

=

加入者为

&

.
示例：

key=value&key2=value2,value3


如需详细了解定位，请参阅向您的视频流提供定位参数。

podTemplateName

 可选 广告连播模板名称

scte35CueOut

 可选 scte35 cue out 中采用 Base-64 编码的数据。可包含

splice_insert()

或

time_signal()

命令。
示例：

  • time_signal():

    /DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==

  • splice_insert():

    /DAvAAAAAAAA///wFAVIAACPf+/+c2nALv4AUsz1AAAAAAAKAAhDVUVJAAABNWLbowo=

示例请求

创建广告插播时间点
POST admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …
{
    "expectedDuration": "30s",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "customParams": "param1=value1&param2=value2",
    "podTemplateName": "podtemplate"
}
响应正文

响应正文包含 adBreak 对象中发送的所有参数，以及一个额外的 name 字段，该字段包含所创建广告插播时间点的 Google 通用标准 ID。系统会按以下格式返回此字段：

networks/{network_code}/assets/{asset_key}/adBreaks/{ad_break_id}
示例响应
HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
}
列出已分配的广告插播时间点
GET admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …
响应正文

响应正文包含广告插播时间点，以及分配给数据流的每个广告插播时间点对应的额外 breakState 字段。breakState 字段支持以下值：

 // Ad break decisioning has started.
BREAK_STATE_DECISIONED

// Break has started to be delivered to end users.
BREAK_STATE_COMPLETE
示例响应
HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "breakState": "BREAK_STATE_COMPLETE"
}