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 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:

1. Utwórz treść żądania jako bufor protokołu.

2. Prześlij je na serwer za pomocą protokołu HTTP/2.

3. Odpowiedź należy zdeserializować do bufora protokołu.

4. Zinterpretuj wyniki.

Większość naszej dokumentacji opisuje używanie gRPC.

Opcjonalnie:

1. Utwórz treść żądania jako obiekt JSON.

2. Prześlij je na serwer za pomocą protokołu HTTP 1.1.

3. Odpowiedź należy zdeserializować jako obiekt JSON.

4. Zinterpretuj wyniki.

Więcej informacji o korzystaniu z interfejsu REST znajdziesz w przewodniku Interfejs REST.

Uwaga: w tym przewodniku opisano nagłówki struktury i transportu wspólne dla protokołów gRPC i 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.

Ważne: aby poznać wszystkie obsługiwane zasoby i ich reprezentację ścieżki (resource_name), zapoznaj się z dokumentacją zasobów. W przypadku innych usług używa się tego samego formatu.

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 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 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.

Kluczowe pojęcie: klient operacyjny to identyfikator klienta w pliku danych żądania. Na przykład klient operacyjny w tym żądaniu CampaignBudgetService to:1234567890:

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.

Uwaga: możesz pobrać listę kont, do których bezpośrednio możesz uzyskać dostęp za pomocą danych logowania OAuth, wysyłając żądanie CustomerService.ListAccessibleCustomers. W przypadku tego typu żądania parametr login-customer-id nie jest wymagany i nie ma wpływu na zwracaną listę klientów.

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 (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.