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 się martwić szczegółami żądania. Jednak znajomość ich podstawowych właściwości 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. [Preferowana] Utwórz treść żądania jako bufor protokołu, wyślij go do serwera za pomocą HTTP/2, zdeserializuj odpowiedź do bufora protokołu i zinterpretuj wyniki. Większość dokumentacji opisuje używanie gRPC.

2. [Opcjonalnie] utwórz treść żądania jako obiekt JSON, wyślij ją na serwer za pomocą protokołu HTTP 1.1, zdeserializuj odpowiedź jako obiekt JSON i zinterpretuj wyniki. 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 podczas korzystania z interfejsu 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 złożona 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. Instrukcje pobierania tokena dostępu znajdziesz w przewodniku 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 znaków tokenu programisty to ABcdeFGH93KL-NOPQ_STUv. Token dewelopera powinien mieć 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 rejestrowanie tych wartości na potrzeby debugowania.

request-id

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