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

Interfejs 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. Wyślij 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. 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.

Uwaga: ten przewodnik opisuje strukturę i nagłówki transportowe wspólne dla protokołów gRPC i REST.

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. Strukturę nazw zasobów znajdziesz w sekcji Nazwy zasobów interfejsu 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 przypadku innych usług.

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 identyfikator reklamy w grupie reklam nie jest unikalny w skali globalnej, 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 żądania:

Autoryzacja

Musisz podać token dostępu OAuth2 w formacie 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 dewelopera korzystającego z interfejsu Google Ads API. Przykładowy ciąg znaków tokena programisty to ABcdeFGH93KL-NOPQ_STUv. Token programisty powinien być podany w formacie developer-token : ABcdeFGH93KL-NOPQ_STUv.

login-customer-id

Jest to identyfikator klienta autoryzowanego do używania 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.

Kluczowe pojęcie: Klient obsługujący to identyfikator klienta w ładunku żądania. Na przykład klientem operacyjnym w tym żądaniu CampaignBudgetService jest 1234567890:

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 uwzględnisz tego nagłówka, domyślnie zostanie użyta wartość operating customer.

Uwaga: listę kont, które są bezpośrednio dostępne przy użyciu Twoich danych logowania protokołu OAuth, możesz pobrać, wysyłając żądanie CustomerService.ListAccessibleCustomers. Parametr login-customer-id nie jest wymagany w przypadku tego typu żądania 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 analityki aplikacji innej firmy lub partneró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 link do produktu.

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. dostawca analityki aplikacji innej firmy lub dostawca 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 partnera, wykonuje wywołania interfejsu API, aby działać na jednostkach na koncie reklamodawcy (np. przesyłać konwersje lub zarządzać listami użytkowników). Połączone konto może być kontem reklamodawcy lub jego kontem menedżera.

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 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 zależy od połączenia usługi na połączonym koncie z partnerem.

Istnieją 2 scenariusze łączenia:

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

Przykład 1. Link bezpośredni

Jeśli reklamodawca 1111111111 ma bezpośrednie połączenie 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. Link do konta menedżera

Jeśli reklamodawcą 1111111111 zarządza konto menedżera 3333333333, konto menedżera 3333333333 jest połączone 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 grpc trailing-metadata) 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.