Struktura wywołania 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 o strukturze wywołań interfejsu API może się przydać podczas testowania i debugowania.

Interfejs Google Ads API to interfejs gRPC API z powiązaniami REST. Oznacza to, że wywołania interfejsu API można wykonywać na 2 sposoby.

Preferowane:

  1. Utwórz treść żądania jako bufor protokołu.
  2. wysłać go 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.

Opcjonalnie:

  1. Utwórz treść żądania jako obiekt JSON.
  2. wysłać go na serwer przy użyciu protokołu HTTP 1.1.
  3. Zdeserializuj odpowiedź jako obiekt JSON.
  4. Zinterpretuj wyniki.

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

Identyfikatory zasobów

Obiekty w interfejsie Google Ads API są adresowane za pomocą uporządkowanych nazw zasobów i identyfikatorów złożonych.

Nazwy zasobów

Większość obiektów w interfejsie API jest identyfikowana za pomocą 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 znajdziesz w sekcji Nazwy zasobów w interfejsie REST.

Identyfikatory złożone

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

Na przykład AdGroupAd ma wzorzec nazwy zasobu customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id}. Ponieważ identyfikator złożony łączy identyfikator nadrzędnej grupy reklam (ad_group.id) i identyfikator reklamy (ad_group_ad.ad.id), dodajemy identyfikator grupy reklam przed identyfikatorem reklamy:

  • AdGroupId z 123 + ~ + AdId z 45678 = identyfikator reklamy w zbiorczej grupie reklam 123~45678.

Nagłówki żądania

Oto nagłówki HTTP (lub metadane gRPC), które towarzyszą treści żądania:

Autoryzacja

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

Jeśli wystąpią błędy autoryzacji, upewnij się, że używasz prawidłowych danych logowania i masz wystarczające uprawnienia. Błąd USER_PERMISSION_DENIED wskazuje, że uwierzytelniony użytkownik może nie mieć dostępu do konta klienta określonego w żądaniu. Jeśli Twój projekt Google Cloud jest zatwierdzony tylko do dostępu Test i wyślesz żądanie kierowane na konto produkcyjne, interfejs API zwróci błąd AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION w wersji 25 i nowszych (lub AuthorizationError.ACTION_NOT_PERMITTED w wersji 24 i starszych). Szczegółowe informacje o zarządzaniu uprawnieniami znajdziesz w artykule Poziomy dostępu w Google Ads.

login-customer-id

Jest to identyfikator klienta upoważnionego do użycia w żądaniu, bez łączników (-). Jeśli masz dostęp do konta klienta przez konto menedżera, ten nagłówek jest wymagany i musi być ustawiony na identyfikator klienta konta menedżera. Jeśli podczas uwierzytelniania przez konto menedżera nie podasz nagłówka login-customer-id, wystąpi błąd AuthorizationError.USER_PERMISSION_DENIED. Więcej informacji o tym typie błędu znajdziesz w sekcji Typowe błędy. Szczegółowe informacje o tym, jak rozwiązywany jest dostęp do konta, znajdziesz w przewodniku po modelu dostępu OAuth.

https://googleads.googleapis.com/v26/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 zostanie użyty klient operacyjny.

linked-customer-id

Ten nagłówek jest wymagany i używany przez partnerów (np. dostawców analityki aplikacji innej firmy lub dostawców danych) podczas wykonywania działań na połączonym koncie Google Ads. Ten nagłówek musi zawierać 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 usługi.

  • Advertiser (Reklamodawca): konto Google Ads, które jest zarządzane lub aktualizowane przez wywołanie interfejsu API. Identyfikator konta reklamodawcy jest podany w żądaniu. W REST jest to parametr ścieżki customerId (na przykład customers/1111111111/...), a w gRPC jest to pole customer_id w żądaniu.
  • Partner: konto partnera (np. dostawcy analityki aplikacji innej firmy lub dostawcy danych).
  • Połączone konto: konto Google Ads, które ma ustanowione połączenie 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 wykonywać działania na elementach na koncie Advertiser (np. przesyłać konwersje lub zarządzać listami użytkowników). Połączone konto może być kontem reklamodawcy lub kontem menedżera konta reklamodawcy.

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 konta Partner. 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 zależy od połączenia usługi połączonego konta z partnerem.

Istnieją 2 scenariusze łączenia:

  • Jeśli konto reklamodawcy ma bezpośrednie połączenie z kontem partnera, połączonym kontem jest konto reklamodawcy, a parametr linked-customer-id musi być ustawiony na identyfikator klienta konta reklamodawcy.
  • Jeśli konto reklamodawcy jest zarządzane przez konto menedżera, które ma połączenie usługi z kontem partnera, połączonym kontem jest konto menedżera, a parametr linked-customer-id musi być ustawiony na identyfikator klienta konta menedżera.

Przykład 1. Link bezpośredni

Jeśli konto reklamodawcy 1111111111 jest bezpośrednio połączone 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. Połączenie z kontem menedżera

Jeśli konto reklamodawcy 1111111111 jest zarządzane przez konto menedżera 3333333333, konto menedżera 3333333333 jest połączone 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

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

request-id

request-id to ciąg znaków, który jednoznacznie identyfikuje to żądanie. Podaj tę wartość, gdy kontaktujesz się z zespołem pomocy, aby rozwiązać problem z nieudanymi lub nieoczekiwanymi żądaniami do interfejsu API.

Wstecz
Metadane zasobu