Early ad break notification v1
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
- 要建立廣告插播的對應直播活動 ID。這個 ID 可以是下列任一項：
- 直播的「資產金鑰」。
- 直播的「自訂素材資源金鑰」，可讓你指定專屬的 ID 字串，用於管理自己的金鑰空間。
- 直播的「內容來源 ID」和「內容 ID」。
注意：您必須啟用這類別的 ID 才能使用。如需更多資訊，請與客戶經理聯絡。
- 下一個廣告插播的預估時間長度。時間長度應盡量接近實際廣告插播的長度。
除了這些必要欄位外，您還可以傳送自訂指定參數、要套用的廣告插播範本名稱，或 SCTE35 Cue Out 資料 (如有)。
必要條件
如要使用 EABN API，您必須建立服務帳戶，並將帳戶新增至 Google Ad Manager 聯播網。
建立服務帳戶
如要建立服務帳戶來呼叫 EABN API，請完成下列步驟：- 如果您有 Google Cloud 帳戶，請使用 IAM 模組建立服務帳戶。詳情請參閱「建立及管理服務帳戶」。- 如果您沒有 Google Cloud 帳戶，請完成下列步驟，透過 Google API 控制台建立帳戶：
- 建立新專案或選取現有專案。
- 在「憑證」頁面中，按一下「管理服務帳戶」。
- 在「Service accounts」(服務帳戶) 頁面中，按一下「CREATE SERVICE ACCOUNT」(建立服務帳戶)。
- 在「Create Service account」(建立服務帳戶) 頁面中輸入帳戶詳細資料。然後按一下「建立」。
建立服務帳戶後，請複製帳戶的 JSON 金鑰，用於驗證。
啟用 API
建立服務帳戶後，請向客戶經理提供下列資訊，為您的帳戶啟用 API：
- 你的 Google Cloud 帳戶電子郵件地址
- 您的服務帳戶
- Google Ad Manager 聯播網的聯播網代碼。
客戶經理啟用 API 後，請完成下列步驟啟用 API：
- 在 Google API 程式庫中搜尋「Google Ad Manager Video API」。
- 按一下「啟用」。
注意：如果搜尋結果中沒有顯示 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 網址。以下各節將說明這些網址的差異，並提供要求和回應範例。
網址
即將到來的廣告插播通知有三個有效網址。您可以使用這三種型別建立廣告插播 (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
如要使用內容來源 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 結束提示點的 Base-64 編碼資料。可包含
splice_insert()
或
time_signal()
指令。
範例： |
要求範例
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¶m2=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¶m2=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"
}
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2025-08-21 (世界標準時間)。
[null,null,["上次更新時間：2025-08-21 (世界標準時間)。"],[[["\u003cp\u003eThe Early Ad Break Notification (EABN) API enables you to inform Google Ad Manager about upcoming ad breaks in live streams, including metadata, up to an hour in advance.\u003c/p\u003e\n"],["\u003cp\u003eTo use the EABN API, you must create a service account, add it to your Google Ad Manager network, and have the API enabled by your account manager.\u003c/p\u003e\n"],["\u003cp\u003eThe API requires the live stream identifier (asset key, custom asset key, or content source ID with content ID) and the expected ad break duration.\u003c/p\u003e\n"],["\u003cp\u003eYou can optionally include custom targeting parameters, an ad pod template name, and SCTE35 Cue Out data with your EABN requests.\u003c/p\u003e\n"],["\u003cp\u003eEABN requests are immutable, and subsequent requests for the same event are rejected until the break appears in the event's manifest.\u003c/p\u003e\n"]]],[],null,["# Early ad break notification v1\n\nUsing the Early Ad Break Notification API\n-----------------------------------------\n\n- The identifier of the corresponding live stream to which the ad break is being created. This identifier can be one of the following:\n- The \"Asset Key\" of the live stream.\n- The \"Custom Asset Key\" of the live stream, which allows you to manage your own key space by specifying your own identifier string.\n- The \"Content Source ID\" and the \"Content ID\" of the live stream.\n\nNote: You must be enabled to use this identifier type. For more information, contact your account manager.\n\n- The expected duration of the next ad break. The duration needs to be as close to the actual ad break length as possible.\n\nIn addition to these required fields, you can also send custom targeting parameters, the name of an ad pod template to apply, or SCTE35 Cue Out data, if available.\n\n### Prerequisites\n\nIn order to use the EABN API, you must create a service account and add the account to your Google Ad Manager network.\n\n#### Creating a service account\n\nTo create a service account for calling the EABN API, complete the following steps: - If you have a Google Cloud account, use the IAM module to create a service account. For more information, see [Creating and managing service accounts](//cloud.google.com/iam/docs/creating-managing-service-accounts). - If you do not have a Google Cloud account, complete the following steps to create one from the [Google API Console](//console.developers.google.com/apis/credentials/):\n\n1. Create a new project or select an existing project.\n2. In the **Credentials** page, click **Manage service accounts**.\n3. In the **Service accounts** page, click **CREATE SERVICE ACCOUNT**.\n4. In the **Create Service account** page, enter the account details. Then, click **CREATE**.\n\nOnce you have created a service account, copy the account's JSON key, which is used for authentication.\n\n#### Adding your service account to your Google Ad Manager network\n\nTo add your service account to your network, complete the steps in [Add a service account user for API access](//support.google.com/admanager/answer/6078734).\n\n### Enabling the API\n\nOnce you have created the service account, provide the following information to your account manager to enable the API for your account:\n\n- Your Google Cloud Account email address\n- Your service account\n- The Network Code of your Google Ad Manager Network.\n\nAfter the API has been enabled by your account manager, complete the following steps to enable the API:\n\n1. In the [Google API library](//console.developers.google.com/apis/library), search for \"Google Ad Manager Video API\".\n2. Click **ENABLE**.\n\nNote: If the API does not appear in the search results, contact your account manager to confirm that your account has been enabled for the DAI API.\n\n### Using the API\n\nYou can call the EABN API using JSON/REST requests.\n\n#### Authorization\n\nTo make authorized calls to the EABN API, you need to generate OAuth2 service account credentials using the JSON key from your service account and the scope `https://www.googleapis.com/auth/video-ads`. For more information, see [Using OAuth 2.0 for Server to Server Applications](https://developers.google.com/identity/protocols/oauth2/service-account).\n\nYou must include the resulting authorization token as an Auth header for each call to the EABN API.\n\n#### Sending an early ad break notification\n\nTo send an early ad break notification, send a POST request to one of the three valid EABN URLs, depending on how you prefer to specify the live stream. The following sections explain the differences between the URLs and provide request and response examples.\n\n##### URLs\n\nThere are three valid URLs for early ad break notification. You can use all three types to create an ad break (`POST`) or get the list of assigned ad breaks (`GET`).\n\nTo use the asset key of a live stream, use: \n\n POST admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks\n\n GET admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks\n\nTo use the custom asset key of a live stream, use: \n\n POST admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks\n\n GET admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks\n\nTo use the Content Source ID and Content ID approach, use: \n\n POST admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks\n\n GET admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks\n\nFor all the parameters:\n\n- `network_code` represents the network code of your Google Ad Manager network.\n- `asset_key` represents the asset key shown in your live stream details page.\n- `custom_asset_key` represents the custom asset key of your live stream.\n- `content_source_id` represents the id of a content source in Google Ad Manager.\n- `content_id` represents the id of a piece of content in Google Ad Manager.\n\nNote: The specified `content_source_id`/`content_id` pair must be associated with a live stream in Google Ad Manager.\n\n##### Request body - only used to create an Ad Break (POST)\n\n\u003cbr /\u003e\n\n| Object |||\n| \u003cbr /\u003e `expectedDuration` \u003cbr /\u003e | Required | The duration of this ad break, using Google's standard duration format (xx.xxxs where xx.xxx is the number of seconds) |\n| \u003cbr /\u003e `customParams` \u003cbr /\u003e | Optional | Key-value pairs to be included on ad requests for this break for custom criteria targeting in AM360, separated by \u003cbr /\u003e `=` and joined by `&` . Example: `key=value&key2=value2,value3` \u003cbr /\u003e For more information on targeting, see [Supply targeting parameters to your stream](//support.google.com/admanager/answer/7320899). |\n| \u003cbr /\u003e `podTemplateName` \u003cbr /\u003e | Optional | The ad pod template name |\n| \u003cbr /\u003e `scte35CueOut` \u003cbr /\u003e | Optional | Base-64-encoded data from the scte35 cue out. Can include the \u003cbr /\u003e `splice_insert()` or `time_signal()` command. Examples: - time_signal(): \u003cbr /\u003e `/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==` \u003cbr /\u003e - splice_insert(): \u003cbr /\u003e `/DAvAAAAAAAA///wFAVIAACPf+/+c2nALv4AUsz1AAAAAAAKAAhDVUVJAAABNWLbowo=` \u003cbr /\u003e |\n|----------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n\n\u003cbr /\u003e\n\n### Example requests\n\n##### Create an Ad Break\n\n POST admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks\n Content-Type: application/json\n Authorization: Bearer ...\n {\n \"expectedDuration\": \"30s\",\n \"scte35CueOut\": \"/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==\",\n \"customParams\": \"param1=value1¶m2=value2\",\n \"podTemplateName\": \"podtemplate\"\n }\n\n###### Response body\n\nThe response body contains all of the parameters sent in the `adBreak` object, as well as an additional `name` field, which contains the Google-wide standard ID of the created ad break. This field is returned in the following format: \n\n networks/{network_code}/assets/{asset_key}/adBreaks/{ad_break_id}\n\n###### Example response\n\n HTTP/1.1 200 OK\n {\n \"name\": \"networks/.../assets/.../adBreaks/1\",\n \"expectedDuration\": \"30s\",\n \"scte35CueOut\": \"/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==\",\n \"customParams\": \"param1=value1¶m2=value2\",\n \"podTemplateName\": \"podtemplate\"\n }\n\n##### List assigned Ad Breaks\n\n GET admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks\n Content-Type: application/json\n Authorization: Bearer ...\n\n###### Response body\n\nThe response body contains the ad breaks with an additional `breakState` field for each ad break assigned to the stream. `breakState` field supports the following values: \n\n // Ad break decisioning has started.\n BREAK_STATE_DECISIONED\n\n // Break has started to be delivered to end users.\n BREAK_STATE_COMPLETE\n\n###### Example response\n\n HTTP/1.1 200 OK\n {\n \"name\": \"networks/.../assets/.../adBreaks/1\",\n \"expectedDuration\": \"30s\",\n \"breakState\": \"BREAK_STATE_COMPLETE\"\n }"]]
