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.
[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.
[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.
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ę.
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
z123
+~
+AdGroupAdId
z45678
= identyfikator reklamy zbiorczej grupy reklam123~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.
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.
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 (kontoB
).customer-id
: konto Google Ads, na które przesyłane są dane (kontoA
).- Nagłówek
login-customer-id
iAuthorization
: kombinacja wartości identyfikujących użytkownika, który ma dostęp do kontaB
.
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.