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ć o szczegóły tego żądania. Może się jednak przydać przy testowaniu i debugowaniu.

Google Ads API to gRPC API z powiązaniami REST. Oznacza to dwa sposoby wywoływania interfejsu API.

  1. [Preferowany] Utwórz treść żądania jako bufor protokołu, wyślij go do serwera za pomocą protokołu HTTP/2, zminimalizuj odpowiedź do bufora protokołu i zinterpretuj wyniki. W większości dokumentów opisujemy użycie gRPC.

  2. [Opcjonalnie] Utwórz treść żądania jako obiekt JSON, wyślij go na serwer za pomocą protokołu HTTP 1.1, usuń odpowiedź jako obiekt JSON i zinterpretuj wyniki. Więcej informacji o używaniu REST znajdziesz w przewodniku interfejsu REST.

Nazwy zasobów

Większość obiektów w interfejsie API jest identyfikowana na podstawie ciągów nazw zasobów. Te ciągi znaków służą też jako adresy URL w interfejsie REST. Ich nazwy znajdziesz w interfejsie zasobu REST.

Identyfikatory złożone

Jeśli identyfikator obiektu nie jest globalnie unikalny, zostanie on utworzony na podstawie identyfikatora nadrzędnego i tyldy (~).

Na przykład identyfikator reklamy w grupie reklam nie jest unikalny globalnie, dlatego dołączamy do niej identyfikator obiektu nadrzędnego (grupy reklam), aby utworzyć unikalny identyfikator złożony:

  • AdGroupId z 123 + ~ + AdGroupAdId z 45678 = identyfikator grupy reklam złożonych z 123~45678.

Nagłówki żądania

Oto nagłówki HTTP (lub metadane grpc) towarzyszące treści w żądaniu:

Autoryzacja

Dołącz token dostępu OAuth2 w formie Authorization: Bearer YOUR_ACCESS_TOKEN, który identyfikuje konto menedżera działające w imieniu klienta lub bezpośredni reklamodawca zarządzający własnym kontem. Instrukcje pobierania tokena dostępu znajdziesz w przewodniku OAuth2. Token dostępu jest ważny przez godzinę od jego pozyskania; gdy wygaśnie, odśwież token dostępu, aby uzyskać nowy. Pamiętaj, że nasze biblioteki klienta automatycznie odświeżają wygasłe tokeny.

token programisty

Token programisty to 22-znakowy ciąg, który jednoznacznie identyfikuje programistę interfejsu API Google Ads. Przykładowy ciąg tokenów programisty to ABcdeFGH93KL-NOPQ_STUv. Token programisty powinien być podany w postaci developer-token : ABcdeFGH93KL-NOPQ_STUv.

login-identyfikator-klienta

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

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

Ustawienie login-customer-id odpowiada wybraniu konta w interfejsie Google Ads po zalogowaniu się lub kliknięciu zdjęcia profilowego w prawym górnym rogu. Jeśli nie dodasz tego nagłówka, domyślnie będzie to działający klient.

powiązany-identyfikator-klienta

Tego nagłówka używają tylko zewnętrzni dostawcy analityki aplikacji podczas przesyłania konwersji na połączone konto Google Ads.

Przeanalizujmy scenariusz, w którym użytkownicy na koncie A zapewniają dostęp z uprawnieniami do odczytu i edycji do swoich elementów w zakresie konta B za pomocą ThirdPartyAppAnalyticsLink. Po połączeniu użytkownik konta B może wywoływać interfejs API z poziomu konta A, zgodnie z uprawnieniami przyznanymi przez połączenie. W takim przypadku uprawnienia do wywoływania interfejsu API na koncie A są określane przez link zewnętrzny do konta B, a nie przez konto menedżera używane 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 do 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: połączenie wartości identyfikujących użytkowników, którzy mają dostęp do konta B.

Nagłówki odpowiedzi

Te nagłówki (lub grpc final-metadata) są zwracane z treścią odpowiedzi. Zalecamy zapisywanie tych wartości na potrzeby debugowania.

identyfikator żądania

request-id to ciąg znaków, który jednoznacznie identyfikuje to żądanie.