使用 DAI Ad Break API

借助 DAI Ad Break API，您可以创建直播中的广告插播时间点，并管理其时间和广告定位数据。

本指南介绍了如何使用 DAI Ad Break API 为 Google 动态广告插播 (DAI) 直播活动创建、更新和删除广告插播。

前提条件

如需使用 DAI 广告插播 API，您需要满足以下条件：

  • 启用了 admanagervideo.googleapis.com 服务的 Google Cloud 项目。如需了解详情，请参阅创建 Cloud 项目。
  • 具有 Google DAI 直播活动的 Google Ad Manager 广告资源网。如需了解详情，请参阅为 DAI 设置直播。

设置 API 访问权限

如需启用 API，请完成以下步骤：

  1. 创建一个服务账号。如需了解详情，请参阅创建服务账号。
  2. 将服务账号添加到您的 Google Ad Manager 广告资源网。 如需了解详情，请参阅添加服务账号用户以启用 API 访问权限。
  3. 向您的 Google 客户经理提供服务账号电子邮件地址和您的 Google Ad Manager 广告资源网代码。
  4. 在您的 Google Cloud 项目中启用 Google Ad Manager Video API。如需了解详情，请参阅为应用启用“API 和服务”。

使用 OAuth2 进行身份验证

如需授权您的 API 请求，请执行以下步骤：

  1. 使用 https://www.googleapis.com/auth/video-ads 范围生成访问令牌。
  2. 在每个请求中，将 API 的访问令牌作为 Authorization HTTP 标头 Bearer 值包含在内。如需了解详情，请参阅调用 Google API。

以下示例生成了一个具有 DAI Ad Break API 范围的 OAuth 令牌：

gcloud auth print-access-token --scopes='https://www.googleapis.com/auth/video-ads'

如果成功，您会看到以下访问令牌：

ya29.c.c0ASRK0GYUYU0...

发出第一个请求

如需检索直播活动的广告插播，请使用 GET 方法按活动的系统生成的资源键或您的自定义资源键列出所有 AdBreak 实体。

DAI 广告插播 API 仅返回通过该 API 创建的 AdBreak 实体，不包括通过清单、广告连播细分请求或广告连播清单请求创建的广告插播。

以下示例请求按 assetKey 值列出 AdBreak 实体：

curl -X GET "https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer OAUTH_TOKEN"

如果成功，您会看到以下 JSON 响应：

{
 "adBreaks": []
}

当您通过 API 创建更多 AdBreak 实体并请求列表时，您会看到以下 JSON 响应：

{
 "adBreaks": [
    {
      "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
      "expectedDuration": "30s",
      "expectedStartTime": "2025-06-03T15:00:00Z",
      "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
      "customParams": "param1=value1&param2=value2",
      "podTemplateName": "podtemplate"
      "breakState": "BREAK_STATE_SCHEDULED",
    },
    {
      "name": "networks/.../assets/.../adBreaks/cc68b0df-0257-46e7-8193-254060b6256c",
      "breakSequence": "1",
      "expectedDuration": "30s",
      "expectedStartTime": "2025-06-03T14:30:00Z",
      "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
      "customParams": "param1=value1&param2=value2",
      "podTemplateName": "podtemplate"
      "breakState": "BREAK_STATE_COMPLETE",
    },
    …
  ],
  "nextPageToken": "ChAIARIMCNDn97IGEJbhhYUC"
}

创建 AdBreak 实体

如需将直播活动的即将到来的广告插播时间点告知 Google DAI，请使用 POST 方法。

  • 如需创建新的 AdBreak 实体，您必须等待之前的实体转换为 BREAK_STATE_COMPLETE 状态。
  • 或者，您可以删除待处理的 AdBreak 实体，以便创建新实体。
  • 如需为单个直播活动创建多个 AdBreak 实体，请与您的客户经理联系以进行高级配置。

以下示例请求创建了一个预计于 2025 年 6 月 3 日 15:00:00 世界协调时间 (UTC) 开始的广告插播时间点：

curl -X POST "https://admanagervideo.googleapis.com/v1/adBreak/networks/{NETWORK_CODE}/assets/ASSET_KEY/adBreaks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer OAUTH_TOKEN" \
  -d '{
    "expectedDuration": "30s",
    "expectedStartTime": "2025-06-03T15:00:00Z",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "customParams": "param1=value1&param2=value2",
    "podTemplateName": "podtemplate"
  }'

如果成功，您会看到以下 JSON 响应：

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",  "expectedStartTime": "2025-06-03T15:00:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
  "breakState": "BREAK_STATE_SCHEDULED",
}

结果包含检索、修改或删除广告插播时间点所需的广告插播时间点 ID。在示例响应中，创建的广告插播时间点 ID 为 bcc402a6-9880-4b8b-8e4a-a8cd3688f854。

检索 AdBreak 实体

使用 GET 方法检索特定 AdBreak 实体的详细信息，包括广告插播时间点状态和时间元数据。

curl -X GET \
'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer OAUTH_TOKEN'

如果成功，您会看到以下 JSON 响应：

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",
  "expectedStartTime": "2025-06-03T15:10:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
  "breakState": "BREAK_STATE_SCHEDULED",
}

更新 AdBreak 实体

如需在开始做出广告决策之前修改即将到来的广告插播时间点，请使用 PATCH 方法：

curl -X PATCH 'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer OAUTH_TOKEN' \
  -d '{"expectedStartTime": "2025-06-03T15:10:00Z"}'

如果成功，您会看到以下 JSON 响应：

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",
  "expectedStartTime": "2025-06-03T15:10:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
  "breakState": "BREAK_STATE_SCHEDULED",
}

删除 AdBreak 实体

使用 DELETE 方法可在通过 API 创建的广告插播时间点开始投放之前取消该广告插播时间点的广告决策。

以下示例请求会删除广告插播时间点：

curl -X DELETE 'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Authorization: Bearer OAUTH_TOKEN'

如果成功，您会看到 HTTP/1.1 200 OK 响应。

了解高级广告插播时间点功能

创建和管理广告插播时间后，您可以探索 DAI Ad Break API 的以下功能：