Struktura wywołań interfejsu API

Ten przewodnik opisuje typową strukturę wszystkich wywołań interfejsu API.

Jeśli do interakcji z interfejsem API używasz biblioteki klienta, nie musisz się martwić o szczegóły żądania. Informacje o nich mogą być przydatne podczas testowania i debugowania.

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

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

  2. [Opcjonalnie] Utwórz treść żądania jako obiekt JSON, wyślij ją na serwer za pomocą protokołu HTTP 1.1, odfiltruj odpowiedź jako obiekt JSON i zinterpretuj wyniki. Więcej informacji o korzystaniu z 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. Te ciągi służą też jako adresy URL w interfejsie REST. Poznaj nazwy zasobów interfejsu REST w swojej strukturze.

Identyfikatory wieloskładnikowe

Jeśli identyfikator obiektu nie jest globalnie unikalny, złożony identyfikator jest konstruowany na podstawie identyfikatora nadrzędnego i tyldy (~).

Na przykład identyfikator reklamy z grupy reklam nie jest globalnie unikalny, dlatego dołączamy do niego 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 grpc metadane), które towarzyszą treści w żądaniu:

Upoważnienie

Musisz uwzględnić 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ę, który bezpośrednio zarządza 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 biblioteki klienta automatycznie odświeżają wygasłe tokeny.

token programisty

Token programisty to 22-znakowy ciąg jednoznacznie identyfikujący dewelopera interfejsu Google Ads API. Przykładowy ciąg tokena programisty: ABcdeFGH93KL-NOPQ_STUv. Token programisty powinien być podany w formacie developer-token : ABcdeFGH93KL-NOPQ_STUv.

login-identyfikator-klienta

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

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

Skonfigurowanie ustawienia login-customer-id jest równoważne 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 używany działający klient.

połączony identyfikator klienta

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

Rozważ scenariusz, w którym użytkownicy na koncie A zapewniają dostęp do swoich jednostek z uprawnieniami do odczytu i edycji do konta B przy użyciu ThirdPartyAppAnalyticsLink. Po połączeniu użytkownik konta B może wywoływać interfejs API na koncie A, zgodnie z uprawnieniami podanymi w połączeniu. W takim przypadku uprawnienia do wywoływania interfejsu API na koncie A są określane przez link innej firmy do konta B, a nie na konto menedżera, które jest 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 są przesyłane dane (konto A).
  • Nagłówek login-customer-id i Authorization: połączenie wartości identyfikujących użytkownika, który ma dostęp do konta B.

Nagłówki odpowiedzi

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

request-id,

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