DAI Ad Break API verwenden

Mit der DAI Ad Break API können Sie Werbeunterbrechungen in Ihren 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

Um die DAI Ad Break API zu verwenden, 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 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.

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-Header Bearer-Wert 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.

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 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 eine AdBreak-Einheit 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 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 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 anstehende 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 DELETE-Methode, um die Anzeigenentscheidung für eine über die API erstellte Werbeunterbrechung zu stornieren, bevor die Auslieferung der Werbeunterbrechung beginnt.

Mit der folgenden Beispielanfrage 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: