Struktura wywołań interfejsu API

W tym przewodniku opisano wspólną strukturę wszystkich wywołań interfejsu API.

Jeśli do interakcji z interfejsem API używasz biblioteki klienta, nie musisz martwić się o szczegóły żądania. Wiedza o nich może się jednak przydać przy testowaniu i debugowaniu.

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

  1. [Preferowane] Utwórz treść żądania jako bufor protokołu, wyślij je na serwer za pomocą protokołu HTTP/2, dokonaj deserializacji odpowiedzi do bufora protokołu i zinterpretuj wyniki. W większości dokumentacji opisujemy korzystanie z gRPC.

  2. [Opcjonalnie] Utwórz treść żądania jako obiekt JSON, wyślij je na serwer za pomocą HTTP 1.1, sprecyzuj odpowiedź jako obiekt JSON i zinterpretuj wyniki. Więcej informacji o korzystaniu z funkcji REST znajdziesz w przewodniku po interfejsie REST.

Nazwy zasobów

Większość obiektów w interfejsie API jest identyfikowana przez ciągi nazw zasobów. Gdy używasz interfejsu REST, ciągi te służą też jako adresy URL. Informacje o ich strukturze znajdziesz w nazwach zasobów interfejsu REST.

Identyfikatory złożone

Jeśli identyfikator obiektu nie jest unikalny globalnie, identyfikator złożony tego obiektu jest tworzony przez dodanie identyfikatora nadrzędnego i tyldy (~).

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

  • AdGroupId z 123 + ~ + AdGroupAdId z 45678 = identyfikator reklamy zbiorczej w grupie reklam 123~45678.

Nagłówki żądania

To nagłówki HTTP (lub metadane grpc), które towarzyszą treści żądania:

Upoważnienie

Musisz podać token dostępu OAuth2 w formacie Authorization: Bearer YOUR_ACCESS_TOKEN, który identyfikuje konto menedżera działające w imieniu klienta lub reklamodawcę bezpośrednio zarządzającego jego kontem. Instrukcje pobierania tokena dostępu znajdziesz w przewodniku po OAuth2. Token dostępu jest ważny przez godzinę od jego pozyskania. Gdy straci ważność, odśwież token, by pobrać nowy. Nasze biblioteki klienta automatycznie odświeżają wygasłe tokeny.

token-dewelopera

Token programisty to 22-znakowy ciąg, który jednoznacznie identyfikuje dewelopera interfejsu Google Ads API. Przykładowy ciąg tokena programisty to ABcdeFGH93KL-NOPQ_STUv. Token programisty powinien mieć postać developer-token : ABcdeFGH93KL-NOPQ_STUv.

login-customer-id

Jest to identyfikator klienta autoryzowanego klienta, którego ma użyć w żądaniu, bez łączników (-). Jeśli masz dostęp do konta klienta przez konto menedżera, ten nagłówek jest wymagany i musi być ustawiony na identyfikator klienta konta menedżera.

https://googleads.googleapis.com/v16/customers/1234567890/campaignBudgets:mutate

Ustawienie login-customer-id jest równoważne z wybraniem konta w interfejsie Google Ads po zalogowaniu się lub kliknięciu zdjęcia profilowego w prawym górnym rogu. Jeśli nie podasz tego nagłówka, domyślnie zostanie wybrany klient działający.

identyfikator-połączonego-klienta

Jest on używany tylko przez zewnętrznych dostawców analityki aplikacji podczas przesyłania konwersji na połączone konto Google Ads.

Przeanalizujmy scenariusz, w którym użytkownicy konta A przyznają uprawnienia do odczytu i edytowania elementów na koncie B za pomocą ThirdPartyAppAnalyticsLink. Po połączeniu użytkownik konta B będzie mógł wywoływać interfejs API na koncie A zgodnie z uprawnieniami uzyskanymi w ramach połączenia. W tym przypadku uprawnienia do wywoływania interfejsu API na koncie A są określane przez połączenie zewnętrzne z kontem B, a nie przez relację z kontem menedżera używaną w innych wywołaniach interfejsu API.

Zewnętrzny dostawca analityki aplikacji wykonuje wywołanie interfejsu API w ten sposób:

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

Nagłówki odpowiedzi

Te nagłówki (lub końcowe metadane grpc) są zwracane z treścią odpowiedzi. Zalecamy rejestrowanie tych wartości na potrzeby debugowania.

request-id

request-id to ciąg znaków jednoznacznie identyfikujący to żądanie.