使用 DAI 廣告插播 API

透過 DAI 廣告插播 API，您可以在直播中建立及管理廣告插播的時間和廣告指定目標資料。

本指南說明如何使用 DAI Ad Break API，為 Google 動態廣告插播 (DAI) 直播活動建立、更新及刪除廣告插播。

必要條件

如要使用 DAI 廣告插播 API，您需要：

設定 API 存取權

如要啟用 API，請完成下列步驟：

  1. 建立服務帳戶。詳情請參閱「建立服務帳戶」。
  2. 將服務帳戶新增至 Google Ad Manager 聯播網。 詳情請參閱「新增服務帳戶使用者以獲得 API 權限」。
  3. 將服務帳戶電子郵件地址和 Google Ad Manager 聯播網代碼提供給 Google 帳戶管理員。
  4. 在 Google Cloud 專案中啟用 Google Ad Manager Video API。詳情請參閱「為應用程式啟用『API 和服務』」。

使用 OAuth2 進行驗證

如要授權 API 要求，請按照下列步驟操作：

  1. 使用 https://www.googleapis.com/auth/video-ads 範圍產生存取憑證。
  2. 在每項要求中，將 API 的存取權杖做為 AuthorizationHTTP 標頭Bearer值。詳情請參閱「呼叫 Google API」。

下列範例會使用 DAI 廣告插播 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 日下午 3 點 (世界標準時間) 開始的廣告插播：

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 廣告插播 API 的下列功能：