Struktura wywołania interfejsu API

Ten przewodnik opisuje ogó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 pewna wiedza na temat struktury wywołania interfejsu API może się przydać podczas testowania i debugowania.

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

Preferowany:

  1. Utwórz treść żądania jako bufor protokołu.
  2. Wyślij ją na serwer za pomocą protokołu HTTP/2.
  3. Zdeserializuj odpowiedź do bufora protokołu.
  4. Zinterpretuj wyniki.

Większość naszej dokumentacji opisuje korzystanie z gRPC.

Opcjonalny:

  1. Utwórz treść żądania jako obiekt JSON.
  2. Wyślij ją na serwer za pomocą protokołu HTTP 1.1.
  3. Zdeserializuj odpowiedź jako obiekt JSON.
  4. 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 za pomocą ciągów nazw zasobów. Te ciągi służą też jako adresy URL podczas korzystania z interfejsu REST. Ich strukturę znajdziesz w sekcji Nazwy zasobów interfejsu REST .

Identyfikatory złożone

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

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

  • AdGroupId z 123 + ~ + AdGroupAdId z 45678 = złożony identyfikator reklamy w grupie reklam 123~45678.

Nagłówki żądania

Są to nagłówki HTTP (lub metadane gRPC), które towarzyszą treści w żądaniu:

Autoryzacja

Musisz dołączyć token dostępu OAuth 2.0 w postaci Authorization: Bearer YOUR_ACCESS_TOKEN, który identyfikuje konto menedżera działające w imieniu klienta lub reklamodawcę zarządzającego bezpośrednio własnym kontem. Instrukcje dotyczące 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ż go, aby pobrać nowy. Pamiętaj, że nasze biblioteki klienta automatycznie odświeżają wygasłe tokeny.

Jeśli napotkasz błędy autoryzacji, upewnij się, że używasz prawidłowych danych logowania i masz wystarczające uprawnienia. Błąd USER_PERMISSION_DENIED oznacza, że uwierzytelniony użytkownik może nie mieć dostępu do konta klienta określonego w żądaniu. Szczegółowe informacje o zarządzaniu uprawnieniami znajdziesz w artykule Poziomy dostępu do Google Ads.

login-customer-id

Jest to identyfikator klienta autoryzowanego do użycia w żądaniu, bez łączników (-). Jeśli masz dostęp do konta klienta za pomocą konta menedżera, ten nagłówek jest wymagany i musi być ustawiony na identyfikator klienta konta menedżera. Jeśli podczas uwierzytelniania za pomocą konta menedżera nie uwzględnisz nagłówka login-customer-id, spowoduje to błąd AuthorizationError.USER_PERMISSION_DENIED. Więcej informacji o tym typie błędu znajdziesz w sekcji Typowe błędy. Szczegółowe wyjaśnienie sposobu rozwiązywania problemów z dostępem do konta znajdziesz w przewodniku po modelu dostępu OAuth access model.

https://googleads.googleapis.com/v25/customers/CUSTOMER_ID/campaignBudgets:mutate

Ustawienie login-customer-id jest równoznaczne z wybraniem konta w interfejsie Google Ads po zalogowaniu się lub kliknięciu zdjęcia profilowego w prawym górnym rogu. Jeśli nie uwzględnisz tego nagłówka, domyślnie zostanie użyty klient operacyjny.

linked-customer-id

Ten nagłówek jest wymagany i używany przez partnerów (np. dostawców danych lub dostawców usług analitycznych aplikacji innych firm) podczas działania na połączonym koncie Google Ads. Ten nagłówek musi określać identyfikator klienta konta Google Ads, które ma link do usługi.

Rozważmy sytuację, w której partner musi wykonywać wywołania interfejsu API na koncie Google Ads na podstawie linku do usługi.

  • Reklamodawca: konto Google Ads zarządzane lub aktualizowane przez wywołanie interfejsu API. Identyfikator konta reklamodawcy jest określony w żądaniu. W REST jest to parametr ścieżki customerId (np. customers/1111111111/...), a w gRPC jest to pole customer_id w żądaniu.
  • Partner: konto partnera (np. dostawcy danych lub dostawcy usług analitycznych aplikacji innych firm ).
  • Połączone konto: konto Google Ads, które ma ustanowiony link do usługi z partnerem, co daje partnerowi dostęp do reklamodawcy.

Użytkownik, który ma dostęp do konta Partner , wykonuje wywołania interfejsu API, aby działać na encjach na koncie Reklamodawca (np. przesyłać konwersje lub zarządzać listami użytkowników). Połączone konto może być samym kontem Reklamodawca lub kontem menedżera konta Reklamodawca.

Nagłówki żądania muszą być ustawione w ten sposób:

  • Authorization: token dostępu OAuth 2.0 dla użytkownika, który ma dostęp do partnera.
  • login-customer-id: identyfikator klienta partnera. Uwierzytelniony użytkownik musi mieć dostęp do tego konta.
  • linked-customer-id: identyfikator klienta połączonego konta. Ten nagłówek sygnalizuje, że autoryzacja tego żądania opiera się na linku do usługi połączonego konta z partnerem.

Dostępne są 2 scenariusze łączenia:

  • Jeśli konto Reklamodawca ma bezpośredni link do usługi z kontem Partner, połączone konto to Reklamodawca, a linked-customer-id musi być ustawiony na identyfikator klienta konta Reklamodawca.
  • Jeśli konto Reklamodawca jest zarządzane przez konto menedżera, które ma link do usługi z kontem Partner , połączone konto jest kontem menedżera, a linked-customer-id musi być ustawiony na identyfikator klienta menedżera.

Przykład 1. Link bezpośredni

Jeśli konto reklamodawcy 1111111111 ma bezpośredni link do usługi z kontem partnera 2222222222, a wywołanie interfejsu API jest kierowane na customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

Przykład 2. Link menedżera

Jeśli konto reklamodawcy 1111111111 jest zarządzane przez konto menedżera 3333333333, konto menedżera 3333333333 ma link do usługi z kontem partnera 2222222222, a wywołanie interfejsu API jest kierowane na customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

Nagłówki odpowiedzi

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

request-id

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

Wstecz
Metadane zasobu