DAI Ad Break API verwenden

Mit der DAI Ad Break API kannst du Werbeunterbrechungen in deinen Livestreams erstellen und verwalten sowie Timing- und Anzeigenausrichtungsdaten für Werbeunterbrechungen verwalten.

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

Vorbereitung

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

  • Ein Google Cloud-Projekt mit aktiviertem admanagervideo.googleapis.com-Dienst. Weitere Informationen finden Sie unter Cloud-Projekt erstellen.
  • Ein Google Ad Manager-Netzwerk mit einem Google DAI-Livestream-Event. Weitere Informationen finden Sie unter Livestream für DAI einrichten.

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 den API-Zugriff hinzufügen.
  3. Geben Sie die E-Mail-Adresse des Dienstkontos und Ihren Google Ad Manager-Netzwerkcode an Ihren Google-Kundenbetreuer weiter.
  4. Aktivieren Sie die Google Ad Manager Video API in Ihrem Google Cloud-Projekt. Weitere Informationen finden Sie unter APIs & Dienste für Ihre App aktivieren.

Mit OAuth2 authentifizieren

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 der 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

Wenn du Werbeunterbrechungen für ein Livestream-Event abrufen möchtest, verwende die Methode GET, um alle AdBreak-Entitäten anhand des vom System generierten Asset-Schlüssels des Events oder deines benutzerdefinierten Asset-Schlüssels aufzulisten.

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.

In der folgenden Beispielanfrage 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 wird die folgende JSON-Antwort angezeigt:

{
 "adBreaks": []
}

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

{
 "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 zu erhalten.

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 wird die folgende JSON-Antwort angezeigt:

{
  "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 Pausen-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 der 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 wird die folgende JSON-Antwort angezeigt:

{
  "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 vor Beginn der Anzeigenentscheidung ändern möchten, 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 wird die folgende JSON-Antwort angezeigt:

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

Verwenden Sie die Methode DELETE, um die Anzeigenentscheidung für eine über die API erstellte Werbeunterbrechung zu stornieren, bevor die Auslieferung der Werbeunterbrechung beginnt.

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'

Bei Erfolg 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: