Korzystanie z interfejsu DAI Ad Break API

Interfejs DAI Ad Break API umożliwia tworzenie i zarządzanie danymi o czasie trwania i kierowaniu reklam przerw reklamowych w transmisjach na żywo.

Z tego przewodnika dowiesz się, jak za pomocą interfejsu DAI Ad Break API tworzyć, aktualizować i usuwać przerwę na reklamę w przypadku wydarzenia transmitowanego na żywo z wykorzystaniem dynamicznego wstawiania reklam (DAI) w Google.

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 Google Ad Manager Video API w projekcie Google Cloud. Więcej informacji znajdziesz w artykule Włączanie interfejsów API i usług dla aplikacji.

Uwierzytelnianie za pomocą OAuth2

Aby autoryzować żądania 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ą tego interfejsu. Nie obejmuje on przerw na reklamy utworzonych na podstawie pliku manifestu, żądania segmentu bloku reklamowego ani żą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 obiekty 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 AdBreak dla jednego wydarzenia z transmisją na żywo, skontaktuj się z menedżerem konta w celu uzyskania zaawansowanej konfiguracji.

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ę, który jest 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 encji AdBreak

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

Użyj metody DELETE, aby anulować decyzję o reklamie w przypadku przerwy na reklamę utworzonej za pomocą interfejsu API, zanim zacznie się 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.

Więcej informacji o zaawansowanych funkcjach przerw na reklamę

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