Struktura wywołań interfejsu API

Ten przewodnik opisuje wspólną strukturę wszystkich wywołań interfejsu API.

Jeśli do interakcji z interfejsem API używasz biblioteki klienta, nie musisz się martwić szczegółami żądania. Jednak znajomość ich podstawowych właściwości może być przydatna podczas testowania i debugowania.

Interfejs Google Ads API to interfejs gRPC API z powiązaniami REST. Oznacza to, że istnieją 2 sposoby wywoływania interfejsu API.

  1. [Preferowana] Utwórz treść żądania jako bufor protokołu, prześlij go do serwera za pomocą HTTP/2, zdeserializuj odpowiedź do bufora protokołu i zinterpretuj wyniki. Większość naszej dokumentacji opisuje korzystanie z gRPC.

  2. [Opcjonalnie] utwórz treść żądania jako obiekt JSON, wyślij ją na serwer za pomocą protokołu HTTP 1.1, zdeserializuj odpowiedź jako obiekt JSON i zinterpretuj wyniki. Więcej informacji o używaniu 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 interfejsu REST.

Identyfikatory złożone

Jeśli identyfikator obiektu nie jest niepowtarzalny globalnie, tworzony jest identyfikator złożony tego obiektu, który jest tworzony przez dodanie identyfikatora nadrzędnego i trójkąta (~).

Na przykład identyfikator reklamy w grupie reklam nie jest niepowtarzalny globalnie, więc dodajemy do niego identyfikator obiektu nadrzędnego (grupy reklam), aby utworzyć niepowtarzalny identyfikator złożony:

  • AdGroupId z 123 + ~ + AdGroupAdId z 45678 = złożony identyfikator grupy reklam 123~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 reklamodawcy 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. Po upływie tego czasu odśwież token dostępu, aby uzyskać 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/v19/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 podasz 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 takim 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 usługi, która jest używana w innych wywołaniach interfejsu API.

Zewnętrzny dostawca analityki aplikacji wywołuje interfejs API w ten sposób:

  • linked-customer-id: konto analityki aplikacji zewnętrznej, które przesyła dane (konto B).
  • customer-id: konto Google Ads, na które są przesyłane dane (konto A).
  • Nagłówki login-customer-id i Authorization: kombinacja wartości służąca do identyfikacji użytkownika, który ma dostęp do konta B.

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.

Wstecz
Metadane zasobu