Struktura wywołań interfejsu API

W tym przewodniku opisujemy wspólną strukturę wszystkich wywołań interfejsu API.

Jeśli do interakcji z interfejsem API używasz biblioteki klienta, nie musisz się martwić o szczegóły żądania. Wiedza o nich może być jednak przydatna podczas testowania i debugowania.

Interfejs Google Ads API to gRPC API z powiązaniami REST. Oznacza to, że dostępne są 2 sposoby wywoływania interfejsu API.

1. [Preferowane] Utwórz treść żądania jako bufor protokołu, wyślij ją na serwer za pomocą HTTP/2, deserializuj odpowiedź do bufora protokołu i zinterpretuj wyniki. Większość dokumentacji opisuje korzystanie z gRPC.

2. [Opcjonalnie] Utwórz treść żądania w postaci obiektu JSON, wyślij ją na serwer za pomocą protokołu HTTP 1.1, przeprowadź deserializację odpowiedzi jako obiekt JSON i zinterpretuj wyniki. Więcej informacji o korzystaniu z REST znajdziesz w przewodniku po interfejsie REST.

Uwaga: w tym przewodniku opisano nagłówki struktury i transportu wspólne dla protokołów gRPC i REST.

Nazwy zasobów

Większość obiektów w interfejsie API jest identyfikowana przez ciągi nazw zasobów. W interfejsie REST ciągi te służą też jako adresy URL. Sprawdź nazwy zasobów interfejsu REST, aby poznać ich strukturę.

Ważne: w dokumentacji zasobów znajdziesz informacje o wszystkich obsługiwanych zasobach i ich reprezentacji (resource_name). Ten sam format jest stosowany w innych usługach.

Identyfikatory złożone

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

Na przykład identyfikator reklamy grupy reklam nie jest unikalny globalnie, więc dodajemy do niego identyfikator jego obiektu nadrzędnego (grupy reklam), aby utworzyć taki identyfikator złożony:

• AdGroupId z 123 + ~ + AdGroupAdId z 45678 = identyfikator reklamy zbiorczej grupy reklam 123~45678.

Nagłówki żądania

Oto nagłówki HTTP (lub metadane grpc) towarzyszące treści żądania:

Upoważnienie

Musisz podać token dostępu OAuth2 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 swoim kontem. Instrukcje pobierania tokena dostępu znajdziesz w przewodniku po OAuth2. Token dostępu jest ważny przez godzinę od jego pozyskania. Po wygaśnięciu odśwież go, aby pobrać nowy. Pamiętaj, że nasze biblioteki klienta automatycznie odświeżają tokeny, które wygasły.

token-dewelopera

Token programisty to 22-znakowy ciąg, który jednoznacznie identyfikuje dewelopera interfejsu Google Ads API. Przykładowy ciąg tokena programisty to ABcdeFGH93KL-NOPQ_STUv. Token programisty musi mieć postać developer-token : ABcdeFGH93KL-NOPQ_STUv.

login-customer-id

Jest to identyfikator klienta autoryzowanego klienta, którego można użyć 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 tego konta menedżera.

Kluczowy termin: klient operacyjny to identyfikator klienta w ładunku żądania. Na przykład klient operacyjny w tym żądaniu CampaignBudgetService to 1234567890:

https://googleads.googleapis.com/v17/customers/1234567890/campaignBudgets:mutate

Ustawienie login-customer-id jest równoważne z wybraniem konta w interfejsie Google Ads po zalogowaniu się lub kliknięciu zdjęcia profilowego w prawym górnym rogu. Jeśli nie podasz tego nagłówka, domyślnie zostanie wybrany klient operacyjny.

Uwaga: listę kont, do których można uzyskać dostęp bezpośrednio przy użyciu danych logowania OAuth, możesz pobrać, wysyłając żądanie CustomerService.ListAccessibleCustomers. W przypadku tego typu żądania login-customer-id nie jest wymagany i nie ma wpływu na zwracaną listę klientów.

połączony-identyfikator-klienta

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

Weź pod uwagę scenariusz, w którym użytkownicy konta A przyznają uprawnienia do odczytu i edycji elementów na koncie B za pomocą ThirdPartyAppAnalyticsLink. Po połączeniu użytkownik konta B będzie mógł wykonywać wywołania interfejsu API na koncie A zgodnie z uprawnieniami przyznanymi w ramach linku. W tym przypadku uprawnienia do wywoływania interfejsu API na koncie A są określane przez połączenie konta firmy zewnętrznej z kontem B, a nie przez relację konta menedżera, która jest używana w innych wywołaniach interfejsu API.

Zewnętrzny dostawca analityki aplikacji wywołuje interfejs API w ten sposób:

• linked-customer-id: zewnętrzne konto analityki aplikacji, które przesyła dane (konto B).
• customer-id: konto Google Ads, na które przesyłane są dane (konto A).
• Nagłówek login-customer-id i Authorization: kombinacja wartości identyfikujących użytkownika, który ma dostęp do konta B.

Nagłówki odpowiedzi

Poniższe nagłówki (lub grpc końcowe-metadata) są zwracane wraz z treścią odpowiedzi. Zalecamy rejestrowanie tych wartości do celów debugowania.

request-id

request-id to ciąg znaków jednoznacznie identyfikujący to żądanie.