DAI Ad Break API verwenden

Mit der Google Dynamic Ad Insertion (DAI) Ad Break API können Sie das Timing und die Daten für das Anzeigen-Targeting von Werbeunterbrechungen in Ihren Livestreams erstellen und verwalten.

In diesem Leitfaden wird beschrieben, wie Sie mit der DAI Ad Break API eine Werbeunterbrechung für ein Google DAI-Livestream-Event erstellen, aktualisieren und löschen.

Vorbereitung

Für die Verwendung der DAI Ad Break API benötigen Sie Folgendes:

API-Zugriff einrichten

Führen Sie folgende Schritte aus, um die API zu aktivieren:

  1. Erstellen Sie ein Dienstkonto. Weitere Informationen finden Sie unter Dienstkonto erstellen.
  2. Fügen Sie das Dienstkonto Ihrem Google Ad Manager-Netzwerk hinzu. Weitere Informationen finden Sie unter Dienstkontonutzer für API-Zugriff hinzufügen.
  3. Geben Sie die E‑Mail-Adresse des Dienstkontos und Ihren Google Ad Manager-Netzwerkcode an Ihren Google Account Manager weiter.
  4. Aktivieren Sie die Google Ad Manager Video API in Ihrem Google Cloud-Projekt. Weitere Informationen finden Sie unter APIs und Dienste für Ihre App aktivieren.

Authentifizierung mit OAuth 2.0

So autorisieren Sie Ihre API-Anfragen:

  1. Generieren Sie das Zugriffstoken mit dem Bereich https://www.googleapis.com/auth/video-ads.
  2. Fügen Sie in jede Anfrage das Zugriffstoken für die API als Authorization-HTTP-Headerwert Bearer ein. Weitere Informationen finden Sie unter Google APIs aufrufen.

Im folgenden Beispiel wird ein OAuth-Token mit dem Bereich „DAI Ad Break API“ generiert:

gcloud auth print-access-token --scopes='https://www.googleapis.com/auth/video-ads'

Bei Erfolg wird das folgende Zugriffstoken angezeigt:

ya29.c.c0ASRK0GYUYU0...

Erste Anfrage stellen

Verwende die Methode GET, um Werbeunterbrechungen für ein Livestream-Event abzurufen. Damit kannst du alle AdBreak-Entitäten anhand des systemgenerierten Asset-Schlüssels des Events oder deines benutzerdefinierten Asset-Schlüssels auflisten.

Die DAI Ad Break API gibt nur AdBreak-Entitäten zurück, die über die API erstellt wurden. Das gilt nicht für Werbeunterbrechungen, die über das Manifest, die Pod-Segmentanfrage oder die Pod-Manifestanfrage erstellt wurden.

Im folgenden Beispiel werden die AdBreak-Entitäten nach einem assetKey-Wert aufgelistet:

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"

Bei Erfolg sehen Sie die folgende JSON-Antwort:

{
 "adBreaks": []
}

Wenn Sie über die API zusätzliche AdBreak-Entitäten erstellen und die Liste anfordern, sehen Sie die folgende JSON-Antwort:

{
 "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-Entität erstellen

Verwenden Sie die Methode POST, um Google DAI über eine bevorstehende Werbeunterbrechung für ein Livestream-Ereignis zu informieren.

  • Wenn Sie eine neue AdBreak-Einheit erstellen möchten, müssen Sie warten, bis die vorherige den Status BREAK_STATE_COMPLETE erreicht hat.
  • Alternativ können Sie die ausstehende AdBreak-Entität löschen, um eine neue zu erstellen.
  • Wenn Sie mehr als ein AdBreak-Objekt für ein einzelnes Livestream-Ereignis erstellen möchten, wenden Sie sich an Ihren Account Manager, um eine erweiterte Konfiguration vorzunehmen.

Mit der folgenden Beispielanfrage wird eine Werbeunterbrechung erstellt, die voraussichtlich am 3. Juni 2025 um 15:00:00 Uhr UTC beginnt:

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"
  }'

Bei Erfolg sehen Sie die folgende JSON-Antwort:

{
  "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"
}

Das Ergebnis enthält die ID der Werbeunterbrechung, die zum Abrufen, Ändern oder Löschen der Werbeunterbrechung erforderlich ist. In der Beispielantwort lautet die erstellte Werbeunterbrechungs-ID bcc402a6-9880-4b8b-8e4a-a8cd3688f854.

AdBreak-Entität abrufen

Verwenden Sie die Methode GET, um die Details einer bestimmten AdBreak-Entität abzurufen, einschließlich des Status von Werbeunterbrechungen und Timing-Metadaten.

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'

Bei Erfolg sehen Sie die folgende JSON-Antwort:

{
  "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-Entität aktualisieren

Wenn Sie eine bevorstehende Werbeunterbrechung ändern möchten, bevor die Anzeigenauswahl beginnt, verwenden Sie die Methode 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"}'

Bei Erfolg sehen Sie die folgende JSON-Antwort:

{
  "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-Entität löschen

Mit der Methode DELETE können Sie die Anzeigenentscheidung für eine über die API erstellte Werbeunterbrechung vor Beginn der Auslieferung der Werbeunterbrechung abbrechen.

Im folgenden Beispiel wird eine Werbeunterbrechung gelöscht:

curl -X DELETE 'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Authorization: Bearer OAUTH_TOKEN'

Wenn der Vorgang erfolgreich war, wird die Antwort HTTP/1.1 200 OK angezeigt.

Erweiterte Funktionen für Werbeunterbrechungen

Nachdem Sie Werbeunterbrechungen erstellt und verwaltet haben, können Sie sich diese Funktionen der DAI Ad Break API ansehen: