Ten przewodnik zawiera przykłady bezpośredniego wywoływania punktów końcowych REST bez użycia biblioteki klienta.
Wymagania wstępne
Wszystkie poniższe przykłady należy skopiować i wkleić do powłoki bash za pomocą polecenia curl.
Potrzebujesz też tokenu programisty, wystarczy dostęp do konta testowego, a także konta menedżera Google Ads, na którym znajduje się co najmniej 1 konto klienta.
Zmienne środowiskowe
Wpisz poniżej dane logowania i identyfikatory kont, a następnie skopiuj je i wklej do terminala, aby skonfigurować zmienne środowiskowe używane w kolejnych przykładach. Przewodnik Autoryzacja zawiera instrukcje generowania tokena dostępu OAuth 2.0.
API_VERSION="17"
DEVELOPER_TOKEN="DEVELOPER_TOKEN"
OAUTH2_ACCESS_TOKEN="OAUTH_ACCESS_TOKEN"
MANAGER_CUSTOMER_ID="MANAGER_CUSTOMER_ID"
CUSTOMER_ID="CUSTOMER_ID"
Dodatkowe opcjonalne identyfikatory obiektów
Niektóre z poniższych przykładów dotyczą istniejących budżetów lub kampanii. Jeśli masz identyfikatory istniejących obiektów, których możesz użyć w tych przykładach, wpisz je poniżej.
BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID
W przeciwnym razie użycie 2 opcji Mutyfikacje – tworzy przykłady utworzy nowy budżet i kampanię.
Wyszukiwarka
Przewodnik Query Cookbook zawiera wiele przykładów raportowania, które odpowiadają niektórym z domyślnych ekranów Google Ads i działają z tymi samymi zmiennymi środowiskowymi, których użyto w tym przewodniku. Nasze interaktywne narzędzie do tworzenia zapytań jest też doskonałym narzędziem do interaktywnego tworzenia zapytań niestandardowych.
Z podziałem na strony
Metoda search
korzysta z podziału na strony ze stałym rozmiarem strony wynoszącym 10 tys. elementów i z atrybutem page_token
określonym obok query
.
cURL
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:search" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data '{ "query": " SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED' ", "page_token":"${PAGE_TOKEN}" }'
Ocena GAQL
SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED'
Strumieniowanie
Metoda searchStream
przesyła strumieniowo wszystkie wyniki w pojedynczej odpowiedzi, dlatego pole pageSize
nie jest obsługiwane.
cURL
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data '{ "query": " SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED' " }'
Ocena GAQL
SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED'
Mutacje
W jednej treści żądania JSON można wysłać wiele operacji mutacji (create
, update
lub remove
), wypełniając tablicę operations
.
Tworzy
W tym przykładzie tworzymy 2 budżety kampanii w jednym żądaniu.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaignBudgets:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'name': 'My Campaign Budget #${RANDOM}', 'amountMicros': 500000, } }, { 'create': { 'name': 'My Campaign Budget #${RANDOM}', 'amountMicros': 500000, } } ] }"
W następnym przykładzie wykorzystywana jest wartość BUDGET_ID
obecnego budżetu kampanii. Możesz skopiować i wkleić dane wyjściowe z poprzedniego kroku.
BUDGET_ID=BUDGET_ID
Zasoby odwołujące się do innych zasobów używają do tego nazwy zasobu. Kampania utworzona poniżej odwołuje się do elementu campaignBudget
za pomocą nazwy zasobu z wartością ciągów.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'status': 'PAUSED', 'advertisingChannelType': 'SEARCH', 'geoTargetTypeSetting': { 'positiveGeoTargetType': 'PRESENCE_OR_INTEREST', 'negativeGeoTargetType': 'PRESENCE_OR_INTEREST' }, 'name': 'My Search campaign #${RANDOM}', 'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/${BUDGET_ID}', 'targetSpend': {} } } ] }"
Aktualizacje
Aktualizuj atrybuty istniejących obiektów za pomocą operacji update
. W następnym przykładzie zastosowano istniejącą kampanię. Możesz skopiować i wkleić dane wyjściowe z poprzedniego kroku.
CAMPAIGN_ID=CAMPAIGN_ID
Wszystkie aktualizacje wymagają pola updateMask
, w postaci oddzielonej przecinkami listy atrybutów JSON, które powinny znaleźć się w żądaniu, które należy zastosować jako aktualizację. Atrybuty wymienione w zasadzie updateMask
, których nie ma w treści żądania, są czyszczone z obiektu. Atrybuty, których nie ma w tabeli updateMask
, ale znajdują się w treści żądania, są ignorowane.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'update': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}', 'name': 'A changed campaign name #${RANDOM}', }, 'updateMask': 'name' } ], }"
Usuń
Obiekty są usuwane, określając nazwę ich zasobu w operacji remove
.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'remove': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}' } ], }"
Niepowodzenia częściowe
Jeśli w jednym żądaniu znajduje się wiele operacji, możesz opcjonalnie określić partialFailure
. Jeśli ustawiona jest wartość true
, wykonywane są udane operacje, a nieprawidłowe operacje zwracają błędy. Jeśli zasada false
, wszystkie operacje w żądaniu zakończą się tylko wtedy, gdy są prawidłowe.
W następnym przykładzie korzystasz z istniejącej kampanii. Możesz skopiować i wkleić dane wyjściowe z przykładu Twórz.
CAMPAIGN_ID=CAMPAIGN_ID
To żądanie zawiera 2 operacje. W pierwszej kolejności próbujemy zmienić strategię ustalania stawek w danej kampanii, a następnie usunąć kampanię z nieprawidłowym identyfikatorem. Ponieważ druga operacja zakończy się błędem (identyfikator kampanii jest nieprawidłowy), a pole partialFailure
ma wartość false
, pierwsza operacja też się nie powiedzie, a strategia ustalania stawek w bieżącej kampanii nie zostanie zaktualizowana.
curl --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'partialFailure': false, 'operations': [ { 'update': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}', 'manualCpc': { 'enhancedCpcEnabled': false } }, 'updateMask': 'manual_cpc.enhanced_cpc_enabled' }, { 'remove': 'customers/${CUSTOMER_ID}/campaigns/INVALID_CAMPAIGN_ID' } ] }"
Operacje zgrupowane
Metoda googleAds:mutate
obsługuje wysyłanie grup operacji z wieloma typami zasobów. Możesz wysłać wiele operacji różnego typu, aby połączyć sekwencję operacji, które powinny zostać wykonane jako grupa.
Zbiór operacji zakończy się niepowodzeniem, jeśli żadna z nich nie powiedzie się, lub gdy wszystkie operacje zakończą się niepowodzeniem.
Ten przykład pokazuje, jak utworzyć budżet kampanii, kampanię, grupę reklam i reklamę jako jeden zestaw działań. Każda kolejna operacja zależy od poprzedniej. Jeśli w jednym przypadku wystąpi błąd, cała grupa operacji zakończy się niepowodzeniem.
Ujemne liczby całkowite (-1
, -2
, -3
) są używane jako symbole zastępcze w nazwach zasobów i są wypełniane dynamicznie w czasie działania wynikami sekwencji operacji.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'mutateOperations': [ { 'campaignBudgetOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/campaignBudgets/-1', 'name': 'My Campaign Budget #${RANDOM}', 'deliveryMethod': 'STANDARD', 'amountMicros': 500000, 'explicitlyShared': false } } }, { 'campaignOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/-2', 'status': 'PAUSED', 'advertisingChannelType': 'SEARCH', 'geoTargetTypeSetting': { 'positiveGeoTargetType': 'PRESENCE_OR_INTEREST', 'negativeGeoTargetType': 'PRESENCE_OR_INTEREST' }, 'name': 'My Search campaign #${RANDOM}', 'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/-1', 'targetSpend': {} } } }, { 'adGroupOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/adGroups/-3', 'campaign': 'customers/${CUSTOMER_ID}/campaigns/-2', 'name': 'My ad group #${RANDOM}', 'status': 'PAUSED', 'type': 'SEARCH_STANDARD' } } }, { 'adGroupAdOperation': { 'create': { 'adGroup': 'customers/${CUSTOMER_ID}/adGroups/-3', 'status': 'PAUSED', 'ad': { 'responsiveSearchAd': { 'headlines': [ { 'pinned_field': 'HEADLINE_1', 'text': 'An example headline' }, { 'text': 'Another example headline' }, { 'text': 'Yet another headline' } ], 'descriptions': [ { 'text': 'An example description' }, { 'text': 'Another example description' } ], 'path1': 'all-inclusive', 'path2': 'deals' }, 'finalUrls': ['https://www.example.com'] } } } } ] }"
Zarządzanie kontem
Tworzenie kont
Utwórz nowe konta za pomocą metody createCustomerClient
. Pamiętaj, że adres URL wymaga identyfikatora konta menedżera zamiast identyfikatora konta klienta. Pod kontem menedżera zostanie utworzone nowe konto klienta.
curl f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${MANAGER_CUSTOMER_ID}:createCustomerClient" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'customerClient': { 'descriptiveName': 'My Client #${RANDOM}', 'currencyCode': 'USD', 'timeZone': 'America/New_York' } }"
Konta dostępne do wyświetlania informacji o produktach
Wyślij do metody listAccessibleCustomers
proste żądanie GET
, aby uzyskać listę kont Google Ads dostępnych przy użyciu danego tokena dostępu OAuth 2.0. W tej prośbie nie należy używać żadnych identyfikatorów konta menedżera ani konta klienta.
curl -f --request GET "https://googleads.googleapis.com/v${API_VERSION}/customers:listAccessibleCustomers" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
Przesyłanie zasobów binarnych
Metoda assets:mutate
służy do przesyłania zasobów i zarządzania nimi. Dane binarne, np. obraz, są kodowane jako ciąg znaków przy użyciu standardowego kodowania base64 z dopełnieniem. Dopuszczalne jest standardowe lub bezpieczne w adresie URL kodowanie base64 z dopełnieniem lub bez niego.
W tym przykładzie koduje się GIF-a o szerokości 1 piksela, by zachować zwięzłość. W praktyce ładunki typu data
są znacznie większe.
Zakoduj obraz GIF-a o rozdzielczości 1 piksela za pomocą narzędzia wiersza poleceń base64
(dostępnego w podstawowych narzędziach GNU).
base64 1pixel.gif
Wartość zakodowana w formacie base64 jest określana jako atrybut data
w żądaniu do interfejsu API.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/assets:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'name': 'My image asset #${RANDOM}', 'type': 'IMAGE', 'imageAsset': { 'data': 'R0lGODlhAQABAAAAACH5BAEAAAAALAAAAAABAAEAAAIA' } } } ] }"