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 podstawowe szczegóły prośby. Pamiętaj jednak: Wiedza o nich może być przydatna podczas testowania i debugowania.

Interfejs Google Ads API to gRPC API, który obejmuje Powiązania 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 go do serwera za pomocą HTTP/2 – deserializacja odpowiedzi na protokół i zinterpretować wyniki. Większość dokumentacji opisuje używanie gRPC.

  2. [Opcjonalnie] Utwórz treść żądania jako JSON wyślij go na serwer przy użyciu protokołu HTTP 1.1, deserializacji odpowiedzi jako obiektu JSON i zinterpretowania wyników; Więcej informacji: przewodnika po interfejsie REST, w którym znajdziesz więcej informacji o korzystaniu REST.

.

Nazwy zasobów

Większość obiektów w interfejsie API jest identyfikowana przez ciągi nazw zasobów. Te ciągi znaków służą też jako adresy URL w interfejsie REST. Zobacz listę REST nazwy zasobów interfejsu do jego struktury.

Identyfikatory złożone

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

Na przykład identyfikator reklamy w grupie reklam nie jest unikalny globalnie, więc dodajemy na początku jego identyfikator identyfikatora obiektu nadrzędnego (grupy reklam), aby utworzyć unikalny identyfikator złożony:

  • AdGroupId z 123 + ~ + AdGroupAdId z 45678 = reklama wieloskładnikowa identyfikator grupy reklam 123~45678.

Nagłówki żądania

To są nagłówki HTTP (lub grpc) metadanych) w treści żądania:

Autoryzacja

Musisz umieścić token dostępu OAuth2 w formacie Authorization: Bearer YOUR_ACCESS_TOKEN, który identyfikuje konto menedżera działające bezpośrednio w imieniu klienta lub reklamodawcy zarządzania własnym kontem. Jak pobrać token dostępu znajdziesz w przewodniku po OAuth2. An token dostępu jest ważny przez godzinę po jego pozyskaniu; kiedy to wygaśnie, odśwież token dostępu, 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, który jednoznacznie identyfikuje Programistą interfejsu Google Ads API. Przykładowy ciąg tokena programisty to ABcdeFGH93KL-NOPQ_STUv Token programisty powinien znajdować się w sekcji format developer-token : ABcdeFGH93KL-NOPQ_STUv.

login-customer-id

jest to identyfikator klienta upoważnionego do użycia w żądaniu; bez łączników (-). Jeśli masz dostęp do konta klienta przez konta menedżera, ten nagłówek jest wymagany i należy ustawić w nim identyfikator klienta konto menedżera.

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

Ustawienie login-customer-id jest równoważne z wybraniem konta na Interfejs Google Ads po zalogowaniu się lub kliknięciu zdjęcia profilowego u góry po prawej. Jeśli nie podasz tego nagłówka, domyślnie będzie używany parametr operacyjny .

linked-customer-id

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

Weź pod uwagę scenariusz, w którym użytkownicy konta A przyznają uprawnienia do odczytu i edycji do swoich podmiotów na konto 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 linku. W tym przypadku wywołanie interfejsu API uprawnienia do konta A są określane przez połączenie zewnętrzne z kontem B, a nie w relacji konta menedżera używanej w innych wywołaniach interfejsu API.

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

  • linked-customer-id: konto analityki aplikacji firmy zewnętrznej, 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 do Zidentyfikuj użytkownika, który ma dostęp do konta B.

Nagłówki odpowiedzi

Następujące nagłówki (lub końcowe metadane grpc). są zwracane z treścią odpowiedzi. Zalecamy zapisywanie do celów debugowania.

identyfikator-żądania

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

Wstecz
Metadane zasobu