DAI ミッドロール挿入点 API を使用する

Google ダイナミック広告挿入（DAI）のミッドロール挿入点 API を使用すると、ライブ ストリームのミッドロール挿入点のタイミングと広告ターゲティング データを作成、管理できます。

このガイドでは、DAI Ad Break API を使用して Google DAI ライブ配信イベントのミッドロール挿入点を作成、更新、削除する方法について説明します。

前提条件

DAI ミッドロール挿入点 API を使用するには、次のものが必要です。

API アクセスを設定する

この API を有効にするには、次の操作手順を行います。

  1. サービス アカウントを作成します。詳細については、サービス アカウントを作成するをご覧ください。
  2. サービス アカウントを Google アド マネージャー ネットワークに追加します。詳細については、API アクセス用のサービス アカウント ユーザーを追加するをご覧ください。
  3. サービス アカウントのメールアドレスと Google アド マネージャー ネットワークのコードを Google アカウント マネージャーに提供します。
  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 広告ブレーク 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 エンティティを削除して、新しいエンティティを作成することもできます。
  • 1 つのライブ配信イベントに対して複数の AdBreak エンティティを作成するには、アカウント マネージャーにお問い合わせのうえ、高度な設定を行ってください。

次のリクエスト例では、2025 年 6 月 3 日の 15 時 0 分 0 秒（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 広告ブレーク API の次の機能を確認します。