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ć znajomość struktury wywołań interfejsu API.

Interfejs Google Ads API to interfejs gRPC API z powiązaniami REST. Oznacza to, że wywołania interfejsu API można wykonywać 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. Deserializacja odpowiedzi 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 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.

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 formie developer-token : ABcdeFGH93KL-NOPQ_STUv.

login-customer-id

Jest to identyfikator klienta autoryzowanego 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.

Kluczowe pojęcie: Klient obsługujący to identyfikator klienta w ładunku żądania. Na przykład klientem obsługującym w tym żądaniuCampaignBudgetService jest1234567890:

https://googleads.googleapis.com/v20/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 dodasz tego nagłówka, domyślnie będzie to klient operacyjny.

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

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, pod warunkiem że ma uprawnienia przyznane przez połączenie. W tym przypadku uprawnienia do wywoływania interfejsu API na koncie A są określane przez połączenie z kontem B utworzone przez inną firmę, 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

W 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.