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.

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

Preferowany sposób:

1. Utwórz treść żądania jako bufor protokołu.
2. Wyślij ją do serwera 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 sposób:

1. Utwórz treść żądania jako obiekt JSON.
2. Wyślij ją do serwera 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.

Uwaga: ten przewodnik opisuje strukturę i nagłówki transportu wspólne dla protokołów gRPC i 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 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 .

Ważne: zapoznaj się z dokumentacją zasobów, aby poznać wszystkie obsługiwane zasoby i ich reprezentację ścieżki (resource_name). Ten sam format jest używany w innych usługach.

Identyfikatory złożone

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

Na przykład element AdGroupAd ma wzorzec nazwy zasobu customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id}. Ponieważ jego 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 o wartości 123 + ~ + AdId o wartości 45678 = złożony identyfikator reklamy w grupie reklam o wartości 123~45678.

Uwaga: udostępnianie AdId w wielu grupach reklam jest zabronione. Utworzenie nowego elementu AdGroupAd, który odwołuje się do istniejącego elementu AdId w innej grupie reklam, kończy się niepowodzeniem z powodu błędu AdGroupAdError.AD_SHARING_NOT_ALLOWED.

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

Ważne pojęcie: **klient operacyjny** to identyfikator klienta w ładunku żądania. Na przykład klientem operacyjnym w tym CampaignBudgetService żądaniu jest 1234567890:

https://googleads.googleapis.com/v26/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 operacyjny.

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

linked-customer-id

Ten nagłówek jest wymagany i używany przez partnerów (np. dostawców danych lub 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, którym zarządza lub które aktualizuje 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. dostawca danych lub 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 konta 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 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 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 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 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. Podaj tę wartość, gdy kontaktujesz się z zespołem pomocy, aby pomóc w rozwiązywaniu problemów z nieudanymi lub nieoczekiwanymi żądaniami interfejsu API.