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 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 w interfejsie REST.

resource_name

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 jego 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 podać token dostępu OAuth2 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 po 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.

developer-token

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

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 podasz login-customer-id, spowoduje to błąd AuthorizationError.USER_PERMISSION_DENIED. Więcej informacji o tym typie błędu znajdziesz w artykule 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.

https://googleads.googleapis.com/v24/customers/1234567890/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 podasz 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 danych 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 połączenie z usługą.

Rozważmy sytuację, w której partner musi wykonywać wywołania interfejsu API na koncie Google Ads na podstawie połączenia z usługą.

  • 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 danych analitycznych aplikacji innych firm ).
  • Połączone konto: konto Google Ads, które ma nawiązane połączenie z usługą z partnerem, co daje partnerowi dostęp do reklamodawcy.

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

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

  • Authorization: token OAuth2 użytkownika, który ma dostęp do partnera.
  • developer-token: token programisty aplikacji interfejsu API, zwykle powiązany z partnerem.
  • 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 połączeniu z usługą połączonego konta z partnerem.

Możliwe są 2 scenariusze łączenia:

  • Jeśli reklamodawca ma bezpośrednie połączenie z usługą z partnerem, połączone konto jest reklamodawcą, a linked-customer-id musi być ustawiony na identyfikator klienta reklamodawcy.
  • Jeśli reklamodawca jest zarządzany przez konto menedżera, które ma połączenie z usługą z partnerem, połączone konto jest kontem menedżera, a linked-customer-id musi być ustawiony na identyfikator klienta menedżera.

Przykład 1. Połączenie bezpośrednie

Jeśli reklamodawca 1111111111 ma bezpośrednie połączenie z usługą z partnerem 2222222222, a wywołanie interfejsu API jest kierowane na customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

Przykład 2. Połączenie z menedżerem

Jeśli reklamodawca 1111111111 jest zarządzany przez menedżera 3333333333, menedżer 3333333333 ma połączenie z usługą z partnerem 2222222222, a wywołanie interfejsu API jest kierowane na customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_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, który jednoznacznie identyfikuje to żądanie.

Wstecz
Metadane zasobu