DAI Early Ad Break Notification API

使用 Google DAI 平台時，您可能需要為串流中下一個即將發生的直播/線性廣告插播提供指定資料。Early Ad Break Notification (EABN) API 可讓您使用鍵/值組合導入特定廣告插播專屬的指定目標，這樣就能在高流量串流中提高廣告決策的擴充性。

向 EABN API 發出的呼叫必須包含要指定的素材資源鍵，以及下一個廣告插播的預期時間長度。時間長度必須盡可能接近實際廣告插播長度。如果傳送的預期時間長度比提供的廣告插播時間長度短，填入廣告插播供應類型 (預設為空白插入畫面) 就會用於廣告插播的剩餘時間。如果傳送的預期時間長度大於提供的廣告插播時間長度，廣告時段可能會在廣告播放完畢前結束。

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

必要條件

建立服務帳戶

您必須具備 Google 服務帳戶，才能存取 EABN API。

  • 如果您有 Google Cloud 帳戶，可以使用 IAM 模組建立服務帳戶。詳情請參閱建立及管理服務帳戶一文。
  • 如果您沒有 Google Cloud 帳戶，可以前往 Google API 控制台建立服務帳戶，步驟如下：
    1. 建立新專案或選取現有專案。
    2. 在「憑證」頁面中，按一下「管理服務帳戶」。
    3. 在「服務帳戶」頁面中，按一下「建立服務帳戶」。
    4. 在「建立服務帳戶」頁面中，輸入帳戶詳細資料。然後按一下「建立」。

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

啟用 EABN API

建立服務帳戶後，請要求客戶經理為該帳戶啟用 EABN API。

啟用 DAI API

服務帳戶啟用 EABN API 後，請為帳戶啟用 DAI API：

  1. 在 Google API 程式庫中搜尋「DAI API」。

  2. 選取並啟用 DAI API。

使用 EABN API

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

驗證

如要向 EABN API 發出通過驗證的呼叫，您必須使用服務帳戶和範圍 https://www.googleapis.com/auth/video-ads 中的 JSON 金鑰，來產生 OAuth2 服務帳戶憑證。詳情請參閱「針對伺服器對伺服器應用程式使用 OAuth 2.0」。

每次呼叫 EABN API 時，都必須將產生的驗證權杖做為驗證標頭。

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

如要傳送「即將到來的廣告插播通知」，請使用以下網址和要求主體傳送 POST 要求：

POST dai.googleapis.com/v1/adBreaks

要求主體

物件
adBreak 需要 adBreak 屬性的包裝函式物件
assetKey 需要 要建立廣告插播的 LiveStreamEvent 的專屬 ID
expectedDuration 需要 這個廣告插播的時間長度，使用 Google 標準時間長度格式 (xx.xxxs，其中 xx.xxx 是秒數)
scte35CueOut 選用 來自 scte35 結束提示點的 Base-64 編碼資料。可包含 splice_insert() 或 time_signal() 指令。
範例：
  • time_signal()：
    /DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==
  • splice_insert()：/DAvAAAAAAAA///wFAVIAACPf+/+c2nALv4AUsz1AAAAAAAKAAhDVUVJAAABNWLbowo=
custParams 選用 針對這個廣告插播的廣告請求加入的鍵/值組合 (適用於 AM360 中的自訂條件指定目標，以 = 分隔且以 & 彙整)。
範例：
key=value&key2=value2,value3
如要進一步瞭解指定目標，請參閱「為串流提供指定目標參數」一文。
ptpln 選用 廣告連播範本名稱

回應標頭

HTTP/1.1 200 OK

回應主體

回應主體包含在 adBreak 物件中傳送的所有參數，以及額外的 daiBreakId 欄位，其中包含串流中已建立廣告插播的內部 DAI ID。

範例

要求

POST /v1/adBreaks HTTP/1.1
Content-Type: application/json

{
  "adBreak": {
    "assetKey": "asset1",
    "expectedDuration": "30s",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "custParams": "param1=value1&param2=value2",
    "ptpln": "podtemplate"
  }
}

回應

HTTP/1.1 200 OK

{
  "assetKey": "asset1",
  "expectedDuration": "30s",
  "custParams": "param1=value1&param2=value2",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "ptpln": "podtemplate",
  "daiBreakId": 1
}

實作範例 (Python)

from __future__ import absolute_import
from __future__ import division
from __future__ import print_function

from absl import app

from google.auth.transport.requests import AuthorizedSession
from google.oauth2 import service_account

SERVICE_ACCOUNT_KEY_FILE = "~/eabn_key.json"
ASSET_KEY = "asset1"

SCOPES = ['https://www.googleapis.com/auth/video-ads']
EABN_API_URL = 'https://dai.googleapis.com/v1/adBreaks'


def main():
  credentials = service_account.Credentials.from_service_account_file(
      SERVICE_ACCOUNT_KEY_FILE, scopes=SCOPES)

  authed_session = AuthorizedSession(credentials)

  data = {
      'assetKey': ASSET_KEY,
      'expectedDuration': '120s',
      'custParams': 'param1=value1&param2=value2',
      'scte35CueOut': '/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==',
  }

  r = authed_session.post(EABN_API_URL, json={'adBreak': data})
  print(r.status_code)
  print(r.headers)
  print(r.text)

if __name__ == '__main__':
  app.run(main)