本頁面由 Cloud Translation API 翻譯而成。

Early ad break notification

使用 Early Ad Break Notification API

注意：這個 API 仍在測試階段。如要申請 EABN 計畫的存取權，請與您的客戶經理聯絡。

Early Ad Break Notification (EABN) API 可讓您在廣告插播開始之前，透過中繼資料通知 Google Ad Manager 即將到來的廣告插播時間點。您最多可在廣告插播前一小時傳送通知要求。本指南說明如何啟用及使用 EABN API，以及要求與回應範例。

注意：EABN 要求不可變更，因此休息時間一旦建立，就無法修改。日後為相同事件建立廣告插播的後續請求都會遭到拒絕，直到該事件的資訊清單出現這些廣告插播時間點為止。

對 EABN API 的呼叫必須包含以下資訊：

建立廣告時段的對應直播活動 ID。此 ID 可以是下列其中一種：
直播的「素材資源金鑰」。
直播的「自訂資產金鑰」，可讓你指定自己的 ID 字串，藉此管理自己的金鑰空間。
直播的「Content 來源 ID」和「Content ID」。

注意：你必須啟用才能使用這個 ID 類型。詳情請洽詢您的客戶經理。

下一個廣告插播的預期時間長度。時間長度必須盡可能接近實際廣告插播長度。

除了這些必填欄位，您還可以傳送自訂指定目標參數、要套用的廣告連播範本名稱，或 SCTE35 提示輸出資料 (如果有的話)。

必要條件

如要使用 EABN API，您必須建立服務帳戶，並將該帳戶新增至您的 Google Ad Manager 聯播網。

建立服務帳戶

如要建立呼叫 EABN API 的服務帳戶，請完成下列步驟：- 如果您有 Google Cloud 帳戶，請使用 IAM 模組建立服務帳戶。詳情請參閱「建立及管理服務帳戶」。- 如果您沒有 Google Cloud 帳戶，請按照下列步驟透過 Google API 控制台建立帳戶：

建立新專案或選取現有專案。
在「憑證」頁面中，按一下「管理服務帳戶」。
在「服務帳戶」頁面中，按一下「建立服務帳戶」。
在「Create Service account」(建立服務帳戶) 頁面中，輸入帳戶詳細資料。接著點選「建立」。

建立服務帳戶後，請複製帳戶的 JSON 金鑰，該金鑰用於驗證。

正在將服務帳戶加進 Google Ad Manager 聯播網

如要將服務帳戶新增至網路，請完成新增服務帳戶使用者以存取 API 一文中的步驟。

啟用 API

建立服務帳戶後，請將下列資訊提供給客戶經理，以便為帳戶啟用 API：

您的 Google Cloud 帳戶電子郵件地址
您的服務帳戶
Google Ad Manager 聯播網的聯播網代碼。

客戶經理啟用 API 後，請完成下列步驟來啟用 API：

在 Google API 程式庫中，搜尋「Google Ad Manager Video API」。
按一下「ENABLE」(啟用)。

注意：如果搜尋結果並未顯示這個 API，請與您的客戶經理聯絡，確認您的帳戶已啟用 DAI API。

使用 API

您可以使用 JSON/REST 要求呼叫 EABN API。

授權

如要對 EABN API 進行授權呼叫，您必須利用服務帳戶和 https://www.googleapis.com/auth/video-ads 範圍的 JSON 金鑰產生 OAuth2 服務帳戶憑證。詳情請參閱「針對伺服器對伺服器應用程式使用 OAuth 2.0」一文。

每次呼叫 EABN API 時，您須將產生的授權權杖新增為驗證標頭。

傳送「即將到來的廣告插播通知」

如要傳送「即將到來的廣告插播通知」，請依據您想指定直播活動的方式，將 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

如要採用 Content 來源 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()` 指令示例： 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"
}