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