Ten przewodnik opisuje wspólną strukturę wszystkich wywołań interfejsu API.
Jeśli do interakcji z interfejsem API używasz biblioteki klienta, nie musisz znać szczegółów żądania. Jednak przydatna może być podstawowa wiedza o strukturze wywołań interfejsu API podczas testowania i debugowania.
Interfejs Google Ads API to interfejs gRPC API z połączeniami REST. Oznacza to, że istnieją 2 sposoby wywoływania interfejsu API.
Preferowane:
Utwórz treść żądania jako bufor protokołu.
Prześlij je na serwer za pomocą protokołu HTTP/2.
Odpowiedź należy zdeserializować do bufora protokołu.
Zinterpretuj wyniki.
Większość naszej dokumentacji opisuje używanie gRPC.
Opcjonalnie:
Utwórz treść żądania jako obiekt JSON.
Prześlij je na serwer za pomocą protokołu HTTP 1.1.
Odpowiedź należy zdeserializować jako obiekt JSON.
Zinterpretuj wyniki.
Więcej informacji o korzystaniu z interfejsu REST znajdziesz w przewodniku Interfejs REST.
Nazwy zasobów
Większość obiektów w interfejsie API jest identyfikowana na podstawie ciągów znaków nazwy zasobu. Te ciągi znaków służą też jako adresy URL podczas korzystania z interfejsu REST. Strukturę nazw zasobów w interfejsie REST znajdziesz w dokumentacji.
Identyfikatory złożone
Jeśli identyfikator obiektu nie jest niepowtarzalny globalnie, identyfikator złożony tego obiektu jest tworzony przez dodanie do identyfikatora nadrzędnego znaku tyldy (~).
Na przykład identyfikator reklamy w grupie reklam nie jest identyfikatorem unikalnym na całym świecie, dlatego przed nim dołączamy identyfikator obiektu nadrzędnego (grupy reklam), aby utworzyć unikalny identyfikator złożony:
AdGroupId
z123
+~
+AdGroupAdId
z45678
= złożony identyfikator grupy reklam123~45678
.
Nagłówki żądania
Oto nagłówki HTTP (lub metadane rpc), które towarzyszą treści w żądaniu:
Autoryzacja
Musisz podać token dostępu OAuth2 w formie Authorization: Bearer YOUR_ACCESS_TOKEN
, który identyfikuje konto menedżera działające w imieniu klienta lub reklamodawcę bezpośrednio zarządzającego swoim kontem. Instrukcje pobierania tokena dostępu znajdziesz w przewodniku OAuth2. Token dostępu jest ważny przez godzinę od momentu jego uzyskania. Gdy wygaśnie, odśwież token dostępu, aby pobrać nowy. Pamiętaj, że nasze biblioteki klienta automatycznie odświeżają wygasłe tokeny.
developer-token
Token programisty to ciąg znaków o długości 22 znaków, który jednoznacznie identyfikuje dewelopera interfejsu Google Ads API. Przykładowy ciąg znaków tokenu programisty to ABcdeFGH93KL-NOPQ_STUv
. Token dewelopera powinien mieć format developer-token : ABcdeFGH93KL-NOPQ_STUv
.
login-customer-id
To identyfikator klienta autoryzowanego klienta do użycia w żądaniu, bez myślników (-
). Jeśli dostęp do konta klienta masz przez konto menedżera, ten nagłówek jest wymagany i musi być ustawiony na identyfikator klienta konta menedżera.
https://googleads.googleapis.com/v20/customers/1234567890/campaignBudgets:mutate
Ustawienie wartości login-customer-id
jest równoznaczne z wybraniem konta w interfejsie Google Ads po zalogowaniu się lub kliknięciem zdjęcia profilowego w prawym górnym rogu. Jeśli nie dodasz tego nagłówka, domyślnie zostanie użyty klient operacyjny.
linked-customer-id
Ten nagłówek jest używany tylko przez [zewnętrznych dostawców analityki aplikacji podczas przesyłania konwersji na połączone konto Google Ads.
Rozważmy sytuację, w której użytkownicy na koncie A
udzielają dostępu do odczytu i edycji swoich elementów na koncie B
za pomocą interfejsu ThirdPartyAppAnalyticsLink
.
Po połączeniu kont użytkownik na koncie B
może wykonywać wywołania interfejsu API na koncie A
, z zastrzeżeniem uprawnień uzyskanych dzięki połączeniu. W tym przypadku uprawnienia do wywołania interfejsu API na koncie A
są określane przez połączenie zewnętrzne z kontem B
, a nie przez relację między kontem menedżera a kontem, która jest używana w innych wywołaniach interfejsu API.
Zewnętrzny dostawca analityki aplikacji wykonuje wywołanie interfejsu API w ten sposób:
linked-customer-id
: konto analityki aplikacji zewnętrznej, które przesyła dane (kontoB
).customer-id
: konto Google Ads, na które są przesyłane dane (kontoA
).- Nagłówki
login-customer-id
iAuthorization
: kombinacja wartości służąca do identyfikacji użytkownika, który ma dostęp do kontaB
.
Nagłówki odpowiedzi
Wraz z treścią odpowiedzi zwracane są te nagłówki (lub grpc trailing-metadata). Zalecamy rejestrowanie tych wartości na potrzeby debugowania.
request-id
request-id
to ciąg znaków jednoznacznie identyfikujący to żądanie.