Wywołania interfejsu Search Ads 360 Reporting API są zwykle wykonywane za pomocą biblioteki klienta. Więcej informacji znajdziesz w artykule Wyjaśnienie bibliotek klienta. Znajomość struktury szczegółów żądania może być jednak przydatna podczas testowania i debugowania.
Interfejs Search Ads 360 Reporting API to interfejs gRPC API z powiązaniami REST. Oznacza to, że możesz wywoływać interfejs API na 2 sposoby:
- Preferowana metoda
- Użyj biblioteki klienta:
- Utwórz treść żądania jako bufor protokołu.
- Wyślij żądanie do serwera przy użyciu protokołu HTTP/2.
- Deserializuj odpowiedź na bufor protokołu.
- Zinterpretuj wyniki.
- Opcjonalna metoda alternatywna
- Użycie interfejsu REST:
- Utwórz treść żądania jako obiekt JSON.
- Wyślij żądanie do serwera za pomocą protokołu HTTP 1.1.
- Oddeserializuj odpowiedź jako obiekt JSON.
- Zinterpretuj wyniki.
Więcej informacji znajdziesz w artykule na temat interfejsów Google Cloud APIs.
Poniższe sekcje dotyczą zarówno protokołów gRPC, jak i REST.
Nazwy zasobów
Większość obiektów w interfejsie API jest identyfikowana na podstawie ciągów znaków nazwy zasobu. Te ciągi znaków służą też jako adresy URL podczas korzystania z interfejsu REST.
Więcej informacji o obsługiwanych zasobach i ich reprezentacji ścieżki znajdziesz w sekcji Informacje > REST. Ten sam format jest używany 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 w grupie reklam nie jest globalnie unikalny, dlatego do identyfikatora obiektu nadrzędnego (grupy reklam) dołączany jest identyfikator złożony, który tworzy unikalny identyfikator złożony.
Przykład: AdGroupId z 123 + ~ + AdGroupAdId z 45678 = identyfikator reklamy zbiorczej grupy reklam 123~45678.
Nagłówki żądania
Nagłówki HTTP (lub metadane gRPC) w podanych niżej sekcjach powinny być uwzględnione w sekcji treści żądania.
Autoryzacja
W formularzu musisz umieścić token dostępu OAuth2:
Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN]
Token powinien identyfikować konto menedżera działające w imieniu klienta lub reklamodawcy bezpośrednio zarządzającego swoim podrzędnym kontem menedżera lub kontem klienta. Aby dowiedzieć się więcej, zapoznaj się z artykułami Konta menedżera Search Ads 360 i Uwierzytelnianie.
Nagłówek identyfikatora klienta logowania
Nagłówek login-customer-id jest wymagany, gdy używasz konta menedżera do uzyskiwania dostępu do podrzędnego konta menedżera lub konta klienta. Nie jest on wymagany, gdy uzyskujesz dostęp do podrzędnego konta menedżera lub konta klienta bezpośrednio. Chociaż nie jest to ściśle konieczne, zalecamy zawsze podawanie parametru login-customer-id w przypadku uwierzytelnionych użytkowników, którzy mają dostęp do więcej niż 1 konta. Pozwala to uniknąć niejasności i zapobiega niezamierzonemu ustawieniu kontekstu na nieprawidłowe konto.
Prośba powinna zawierać identyfikator klienta autoryzowanego użytkownika bez myślników (-), np.:
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/campaignBudgets
Ustawienie wartości login-customer-id jest równoznaczne z wybraniem konta w interfejsie Search Ads 360 po zalogowaniu się lub kliknięciu zdjęcia profilowego w prawym górnym rogu.
Nagłówki odpowiedzi
Poniższe nagłówki (lub końcowe metadane gRPC) są zwracane wraz z treścią odpowiedzi. Zalecamy rejestrowanie tych wartości do celów debugowania.
Identyfikator żądania
Nagłówek request-id to ciąg znaków jednoznacznie identyfikujący żądanie.