Korzystanie z interfejsu API przerw na reklamę DAI

Interfejs Google Dynamic Ad Insertion (DAI) Ad Break API umożliwia tworzenie i zarządzanie danymi o czasie trwania i kierowaniu reklam w blokach reklamowych w transmisjach na żywo.

Ten przewodnik zawiera informacje o korzystaniu z interfejsu DAI Ad Break API do tworzenia, aktualizowania i usuwania przerw na reklamy w przypadku wydarzenia transmitowanego na żywo w usłudze Google DAI.

Wymagania wstępne

Aby korzystać z interfejsu DAI Ad Break API, musisz mieć:

Konfigurowanie dostępu do interfejsu API

Aby włączyć interfejs API, wykonaj te czynności:

  1. Utwórz konto usługi. Więcej informacji znajdziesz w artykule Tworzenie konta usługi.
  2. Dodaj konto usługi do sieci Google Ad Managera. Więcej informacji znajdziesz w artykule Dodawanie użytkownika konta usługi w celu uzyskania dostępu do interfejsu API.
  3. Podaj opiekunowi klienta w Google adres e-mail konta usługi i kod sieci Google Ad Managera.
  4. Włącz w projekcie w chmurze Google interfejs Google Ad Manager Video API. Więcej informacji znajdziesz w artykule Włączanie interfejsów API i usług dla aplikacji.

Uwierzytelnianie za pomocą OAuth2

Aby autoryzować żądania do interfejsu API, wykonaj te czynności:

  1. Wygeneruj token dostępu z zakresem https://www.googleapis.com/auth/video-ads.
  2. W każdym żądaniu do interfejsu API umieść token dostępu jako wartość Authorizationnagłówka HTTPBearer. Więcej informacji znajdziesz w artykule Wywoływanie interfejsów API Google.

Ten przykład generuje token OAuth z zakresem interfejsu DAI Ad Break API:

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

Jeśli operacja się powiedzie, zobaczysz ten token dostępu:

ya29.c.c0ASRK0GYUYU0...

Wysyłanie pierwszego żądania

Aby pobrać przerwy na reklamy w przypadku wydarzenia transmitowanego na żywo, użyj metody GET, aby wyświetlić listę wszystkichAdBreak encji według wygenerowanego przez system klucza zasobu wydarzenia lub Twojego niestandardowego klucza zasobu.

Interfejs DAI Ad Break API zwraca tylko obiekty AdBreak utworzone za pomocą interfejsu API, z wyłączeniem przerw na reklamy utworzonych na podstawie pliku manifestu, żądania segmentu bloku reklamowego lub żądania pliku manifestu bloku reklamowego.

Poniższy przykładowy request wyświetla listę encji AdBreak według wartości assetKey:

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"

Jeśli operacja się uda, zobaczysz tę odpowiedź w formacie JSON:

{
 "adBreaks": []
}

Gdy utworzysz dodatkowe jednostki AdBreak za pomocą interfejsu API i poprosisz o listę, zobaczysz tę odpowiedź 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"
}

Tworzenie encji AdBreak

Aby poinformować Google DAI o nadchodzącej przerwie na reklamę podczas transmisji na żywo, użyj metody POST.

  • Aby utworzyć nowy AdBreak, musisz poczekać, aż poprzedni przejdzie w stan BREAK_STATE_COMPLETE.
  • Możesz też usunąć oczekującą encję AdBreak, aby utworzyć nową.
  • Aby utworzyć więcej niż 1 element AdBreak dla jednego wydarzenia z transmisją na żywo, skontaktuj się z menedżerem konta w celu uzyskania zaawansowanej konfiguracji.

Poniższe przykładowe żądanie tworzy przerwę na reklamę, która ma się rozpocząć 3 czerwca 2025 r. o godzinie 15:00:00 czasu 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"
  }'

Jeśli operacja się uda, zobaczysz tę odpowiedź w formacie 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"
}

Wynik zawiera identyfikator przerwy na reklamę wymagany do pobierania, modyfikowania lub usuwania przerwy na reklamę. W przykładowej odpowiedzi utworzony identyfikator przerwy na reklamę to bcc402a6-9880-4b8b-8e4a-a8cd3688f854.

Pobieranie encji AdBreak

Użyj metody GET, aby pobrać szczegóły konkretnego elementu AdBreak, w tym metadane dotyczące stanu przerwy na reklamę i czasu jej trwania.

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'

Jeśli operacja się uda, zobaczysz tę odpowiedź w formacie 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"
}

Aktualizowanie jednostki AdBreak

Aby zmodyfikować nadchodzącą przerwę na reklamę przed rozpoczęciem podejmowania decyzji o reklamie, użyj metody 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"}'

Jeśli operacja się uda, zobaczysz tę odpowiedź w formacie 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"
}

Usuwanie elementu AdBreak

Użyj metody DELETE, aby anulować decyzję dotyczącą reklamy w przypadku przerwy na reklamę utworzonej za pomocą interfejsu API, zanim zacznie się ona wyświetlać.

Poniższe przykładowe żądanie usuwa przerwę na reklamę:

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

Jeśli operacja się uda, zobaczysz odpowiedź HTTP/1.1 200 OK.

Poznaj zaawansowane funkcje przerw na reklamy

Po utworzeniu przerw na reklamy i zarządzaniu nimi zapoznaj się z tymi funkcjami interfejsu DAI Ad Break API: