Korzystanie z interfejsu Early Ad Break Notification API
Uwaga: ten interfejs API jest nadal w wersji beta. Jeśli chcesz poprosić o dostęp do programu EABN, skontaktuj się ze swoim menedżerem konta.
Interfejs Early Ad Break Notification API (EABN) pozwala powiadomić Google Ad Managera o nadchodzącej przerwie na reklamę wraz z jej metadanymi jeszcze przed jej rozpoczęciem. Prośbę o powiadomienie możesz wysłać na godzinę przed przerwą na reklamę. Z tego przewodnika dowiesz się, jak włączyć i używać interfejsu EABN API, a także przykłady żądań i odpowiedzi.
Uwaga: żądań EABN nie można zmienić, więc po utworzeniu przerwy nie można jej zmienić. Kolejne żądania utworzenia przerw na reklamy dla tego samego zdarzenia będą odrzucane, dopóki przerwa nie pojawi się w pliku manifestu tego zdarzenia.
Wywołania interfejsu EABN API muszą zawierać te informacje:
- Identyfikator odpowiedniej transmisji na żywo, w której tworzona przerwa na reklamę. Może to być jeden z tych identyfikatorów:
- „Klucz pliku” transmisji na żywo.
- „Niestandardowy klucz zasobu” transmisji na żywo, który umożliwia zarządzanie własną przestrzenią kluczy przez podanie własnego ciągu identyfikatora.
- Identyfikator źródła treści oraz identyfikator treści transmisji na żywo.
Uwaga: aby używać tego typu identyfikatora, musisz włączyć tę funkcję. Aby dowiedzieć się więcej, skontaktuj się z menedżerem konta.
- Przewidywany czas trwania następnej przerwy na reklamę. Czas trwania musi być jak najbardziej zbliżony do rzeczywistej długości przerwy na reklamę.
Oprócz tych wymaganych pól możesz też wysyłać parametry kierowania niestandardowego, nazwę szablonu bloku reklamowego lub dane SCTE35 sygnalizowanie końca (jeśli są dostępne).
Wymagania wstępne
Aby korzystać z interfejsu API EABN, musisz utworzyć konto usługi i dodać je do sieci Google Ad Managera.
Tworzę konto usługi
Aby utworzyć konto usługi do wywoływania interfejsu EABN API, wykonaj te czynności: – Jeśli masz konto Google Cloud, utwórz konto usługi za pomocą modułu uprawnień. Więcej informacji znajdziesz w artykule Tworzenie kont usługi i zarządzanie nimi. – Jeśli nie masz konta Google Cloud, wykonaj te czynności, aby je utworzyć w Konsoli interfejsów API Google:
- Utwórz nowy projekt lub wybierz istniejący.
- Na stronie Credentials (Dane logowania) kliknij Manage service accounts (Zarządzaj kontami usługi).
- Na stronie Konta usługi kliknij UTWÓRZ KONTO USŁUGI.
- Na stronie Utwórz konto usługi wpisz szczegóły konta. Następnie kliknij UTWÓRZ.
Po utworzeniu konta usługi skopiuj jego klucz JSON, który jest używany do uwierzytelniania.
Dodawanie konta usługi do sieci Google Ad Managera
Aby dodać konto usługi do sieci, wykonaj czynności opisane w artykule Dodawanie użytkownika konta usługi w celu uzyskania dostępu do interfejsu API.
Włączam interfejs API
Po utworzeniu konta usługi podaj menedżerowi konta te informacje, by włączyć na nim interfejs API:
- Adres e-mail Twojego konta Google Cloud
- Twoje konto usługi
- Kod sieci w Twojej sieci Google Ad Managera.
Po włączeniu interfejsu API przez menedżera konta wykonaj te czynności:
- W bibliotece interfejsów API Google wyszukaj „Google Ad Manager Video API”.
- Kliknij WŁĄCZ.
Uwaga: jeśli interfejs API nie pojawia się w wynikach wyszukiwania, skontaktuj się z menedżerem konta, aby upewnić się, że na Twoim koncie włączono interfejs DAI API.
Korzystanie z interfejsu API
Możesz wywołać interfejs EABN API za pomocą żądań JSON/REST.
Autoryzacja
Aby wykonywać autoryzowane wywołania interfejsu EABN API, musisz wygenerować dane logowania do konta usługi OAuth2 za pomocą klucza JSON ze swojego konta usługi i zakresu https://www.googleapis.com/auth/video-ads
. Więcej informacji znajdziesz w artykule Używanie protokołu OAuth 2.0 w aplikacjach między serwerami.
Przy każdym wywołaniu interfejsu EABN API musisz podawać uzyskany token autoryzacji jako nagłówek uwierzytelniania.
Wysyłanie wcześniejszego powiadomienia o przerwie na reklamę
Aby wysłać wcześniejsze powiadomienie o przerwie na reklamę, wyślij żądanie POST na jeden z 3 prawidłowych adresów URL EABN w zależności od tego, jak chcesz skonfigurować transmisję na żywo. W sekcjach poniżej wyjaśniamy różnice między adresami URL oraz podajemy przykłady żądań i odpowiedzi.
Adresy URL
Wcześniejsze powiadomienia o przerwie na reklamę mają 3 prawidłowe adresy URL. Możesz użyć wszystkich 3 typów, aby utworzyć przerwę na reklamę (POST
) lub uzyskać listę przypisanych przerw na reklamę (GET
).
Aby użyć klucza pliku transmisji na żywo, użyj:
POST admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks
GET admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks
Aby użyć niestandardowego klucza pliku transmisji na żywo, użyj:
POST admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks
GET admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks
Aby korzystać z Content Source ID i Content ID, użyj:
POST admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks
GET admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks
Wszystkie parametry:
network_code
to kod Twojej sieci Google Ad Managera.asset_key
reprezentuje klucz pliku widoczny na stronie z informacjami o transmisji na żywo.custom_asset_key
to klucz niestandardowego pliku Twojej transmisji na żywo.content_source_id
reprezentuje identyfikator źródła treści w usłudze Google Ad Manager.content_id
reprezentuje identyfikator treści w usłudze Google Ad Manager.
Uwaga: podana para content_source_id
/content_id
musi być powiązana z transmisją na żywo w usłudze Google Ad Manager.
Treść żądania – używana tylko do utworzenia przerwy na reklamę (POST)
Obiekt | ||
---|---|---|
| Wymagane | Czas trwania tej przerwy na reklamę w standardowym formacie Google (xx.xxxs, gdzie xx.xxx to liczba sekund). |
| Opcjonalnie | Pary klucz-wartość, które mają być uwzględniane w żądaniach reklamy w ramach tej przerwy na potrzeby kierowania według kryteriów niestandardowych w AM360, rozdzielone znakiem
oraz dołączają przez
.
|
| Opcjonalnie | Nazwa szablonu bloku reklamowego |
| Opcjonalnie | Dane zakodowane w standardzie Base-64 z sygnału SCTE35. Mogą obejmować
lub
.
|
Przykładowe żądania
Utwórz przerwę na reklamę
POST admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …
{
"expectedDuration": "30s",
"scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
"customParams": "param1=value1¶m2=value2",
"podTemplateName": "podtemplate"
}
Treść odpowiedzi
Treść odpowiedzi zawiera wszystkie parametry wysłane w obiekcie adBreak
, a także dodatkowe pole name
, które zawiera standardowy identyfikator utworzony we wszystkich usługach Google. To pole jest zwracane w tym formacie:
networks/{network_code}/assets/{asset_key}/adBreaks/{ad_break_id}
Przykładowa odpowiedź
HTTP/1.1 200 OK
{
"name": "networks/.../assets/.../adBreaks/1",
"expectedDuration": "30s",
"scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
"customParams": "param1=value1¶m2=value2",
"podTemplateName": "podtemplate"
}
Wyświetl listę przerw na reklamę
GET admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …
Treść odpowiedzi
Treść odpowiedzi zawiera przerwy na reklamę oraz dodatkowe pole breakState
na każdą przerwę na reklamę przypisaną do strumienia. Pole breakState
obsługuje te wartości:
// Ad break decisioning has started.
BREAK_STATE_DECISIONED
// Break has started to be delivered to end users.
BREAK_STATE_COMPLETE
Przykładowa odpowiedź
HTTP/1.1 200 OK
{
"name": "networks/.../assets/.../adBreaks/1",
"expectedDuration": "30s",
"breakState": "BREAK_STATE_COMPLETE"
}