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 podczas testowania i debugowania może się przydać znajomość struktury wywołań 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.

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.

Identyfikatory złożone

Jeśli identyfikator obiektu nie jest unikalny w skali globalnej, tworzony jest identyfikator złożony tego obiektu, który powstaje 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 formacieAuthorization: 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 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 w Google Ads.

developer-token

Token programisty to 22-znakowy ciąg znaków, który jednoznacznie identyfikuje dewelopera interfejsu Google Ads API. Przykładowy ciąg znaków tokena programisty to: ABcdeFGH93KL-NOPQ_STUv. Token dewelopera 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.

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

linked-customer-id

Ten nagłówek jest używany tylko przez zewnętrznych dostawców analityki aplikacji podczas przesyłania konwersji na połączone konto Google Ads.

Rozważmy sytuację, w której użytkownicy konta A przyznają dostęp do odczytu i edycji jego elementów kontu B za pomocą ThirdPartyAppAnalyticsLink. Po połączeniu użytkownik konta B może wywoływać interfejs API na koncie A, z zastrzeżeniem uprawnień przyznanych przez połączenie. W tym przypadku uprawnienia do wywoływania interfejsu API na koncie A są określane przez połączenie konta B z usługą innej firmy, a nie przez relację z kontem menedżera, która jest używana w innych wywołaniach interfejsu API.

Zewnętrzny dostawca analityki aplikacji wykonuje wywołanie interfejsu API w ten sposób:

• linked-customer-id: konto analityki aplikacji przez firmy zewnętrzne, które przesyła dane (konto B).
• customer-id: konto Google Ads, na które przesyłane są dane (kontoA).
• Nagłówki login-customer-id i Authorization: kombinacja wartości, która identyfikuje użytkownika mającego dostęp do konta B.

Nagłówki odpowiedzi

Wraz z treścią odpowiedzi zwracane są te nagłówki (lub grpc trailing-metadata): Zalecamy rejestrowanie tych wartości na potrzeby debugowania.

request-id

request-id to ciąg znaków, który jednoznacznie identyfikuje to żądanie.