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. Podczas testowania i debugowania może się jednak przydać pewna wiedza o strukturze wywołania interfejsu API.

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

Preferowane:

1. Utwórz treść żądania jako bufor protokołu.
2. Wysyłaj je 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. Wyślij go na serwer za pomocą 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ą strukturalnych 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 z nazwami zasobów. Te ciągi znaków służą też jako adresy URL podczas korzystania z interfejsu REST. Informacje o ich strukturze znajdziesz w sekcji Nazwy zasobów w dokumentacji interfejsu REST.

Identyfikatory złożone

Jeśli identyfikator obiektu nie jest unikalny globalnie, tworzony jest identyfikator złożony 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) z identyfikatorem reklamy (ad_group_ad.ad.id), dodajemy identyfikator grupy reklam przed identyfikatorem reklamy:

• AdGroupId z 123 + ~ + AdId z 45678 = złożona grupa reklam identyfikator reklamy 123~45678.

Nagłówki żądania

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

Autoryzacja

Musisz podać token dostępu OAuth 2.0 w formie 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 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 podanego w żądaniu. Jeśli Twój projekt w chmurze Google Cloud został zatwierdzony tylko do dostępu Test, a Ty wyślesz żądanie dotyczące konta produkcyjnego, interfejs API zwróci kod AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION w wersji 25 lub nowszej (lub AuthorizationError.ACTION_NOT_PERMITTED w wersji 24 lub starszej). Szczegółowe informacje o zarządzaniu uprawnieniami znajdziesz w artykule Poziomy dostępu w Google Ads.

login-customer-id

Jest to identyfikator klienta uprawnionego do używania go 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 znaku 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 Model dostępu OAuth.

https://googleads.googleapis.com/v25/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 uwzględnisz tego nagłówka, domyślnie zostanie użyty klient obsługujący.

linked-customer-id

Ten nagłówek jest wymagany i używany przez partnerów (np. dostawców analityki aplikacji innej firmy lub partnerów danych) podczas wykonywania działań na połączonym koncie Google Ads. W tym nagłówku musi być podany identyfikator klienta konta Google Ads, które ma połączenie z usługą.

Rozważmy sytuację, w której partner musi wywoływać interfejs API na koncie Google Ads na podstawie linku do produktu.

• Reklamodawca: konto Google Ads, którym zarządza lub które aktualizuje wywołanie interfejsu API. Identyfikator konta reklamodawcy jest podany 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 analityki aplikacji innej firmy lub dostawcy danych).
• Połączone konto: konto Google Ads, które ma utworzone połączenie z usługą partnera, co daje partnerowi dostęp do reklamodawcy.

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

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

• Authorization: token dostępu OAuth 2.0 użytkownika, który ma dostęp do usługi Partner.
• login-customer-id: identyfikator klienta konta 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 usługi na połączonym koncie z partnerem.

Wyróżniamy 2 scenariusze łączenia:

• Jeśli konto Reklamodawcy ma bezpośrednie połączenie z kontem Partnera, Połączone konto to Reklamodawca, a parametr linked-customer-id musi być ustawiony na identyfikator klienta konta Reklamodawcy.
• Jeśli kontem Reklamodawcy zarządza konto menedżera, które ma połączenie z kontem Partnera, to Połączone konto jest kontem menedżera, a wartość parametru linked-customer-id musi być ustawiona na identyfikator klienta konta menedżera.

Przykład 1. Link bezpośredni

Jeśli konto reklamodawcy 1111111111 jest połączone bezpośrednio 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żera3333333333, konto menedżera 3333333333 jest połączone z kontem partnera2222222222, 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 ułatwić rozwiązanie problemów z nieudanymi lub nieoczekiwanymi żądaniami interfejsu API.