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ć w powłoce powłoki bash przy użyciu polecenia curl.
Potrzebujesz też tokena programisty, dostępu do konta testowego oraz konta menedżera Google Ads zawierającego co najmniej jedno konto klienta.
Zmienne środowiskowe
Wpisz poniżej dane logowania i identyfikatory do konta, a następnie skopiuj je i wklej w terminalu, aby skonfigurować zmienne środowiskowe używane w kolejnych przykładach. Przewodnik Autoryzacja zawiera instrukcje generowania tokena dostępu OAuth 2.0.
API_VERSION="16"
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ą już istniejących budżetów lub kampanii. Jeśli masz identyfikatory istniejących obiektów, których chcesz użyć w tych przykładach, wpisz je poniżej.
BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID
W przeciwnym razie dwie opcje Mutates – Tworzenie przykładów tworzą nowy budżet i kampanię.
Wyszukiwarka
Przewodnik Query Cookbook zawiera wiele przykładów raportów, które odpowiadają niektórym domyślnym ekranom Google Ads i działają z tymi samymi zmiennymi środowiskowymi, co ten przewodnik. Nasze interaktywne narzędzie do tworzenia zapytań to doskonałe narzędzie do interaktywnego tworzenia niestandardowych zapytań.
Z podziałem na strony
Metoda search
używa podziału na strony z regulowanym parametrem pageSize
określonym obok elementu 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 '{ "pageSize": 10, "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' " }'
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'
transmisje
Metoda searchStream
przesyła strumieniowo wszystkie wyniki w jedną odpowiedź, 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' " }'
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
Przez wypełnienie tablicy operations
w jednej treści żądania JSON można wysłać wiele operacji mutacji (create
, update
lub remove
).
Tworzenie
Ten przykład tworzy 2 budżety kampanii wspólnych 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 wykorzystywany jest BUDGET_ID
istniejącego budżetu kampanii. Możesz skopiować dane wyjściowe z poprzedniego kroku i je wkleić.
BUDGET_ID=BUDGET_ID
Zasoby odwołujące się do innych zasobów używają nazwy zasobu. Kampania utworzona poniżej odwołuje się do elementu campaignBudget
w postaci nazwy zasobu podanej w postaci ciągu znakó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 wykorzystamy istniejącą kampanię – możesz kopiować i wklejać wyniki uzyskane w poprzednim kroku.
CAMPAIGN_ID=CAMPAIGN_ID
Wszystkie aktualizacje wymagają pola updateMask
– rozdzielanej przecinkami listy atrybutów JSON, które powinny znaleźć się w żądaniu, które powinny zostać zastosowane jako aktualizacja. Atrybuty wymienione w updateMask
, ale nieobecne w treści żądania, są wyczyszczone w obiekcie. Atrybuty, których nie ma w żądaniu updateMask
, ale występują 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 ich nazwę zasobu jako operację 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}' } ], }"
Częściowe niepowodzenia
Jeśli w pojedynczym żądaniu znajduje się wiele operacji, opcjonalnie określ właściwość partialFailure
. Jeśli ustawiona jest wartość true
, wykonywane są udane operacje, a nieprawidłowe operacje zwracają błędy. Jeśli jest ustawiona wartość false
, wszystkie operacje w żądaniu powiodły się tylko wtedy, gdy są prawidłowe.
W kolejnym przykładzie wykorzystano istniejącą kampanię. Możesz go skopiować i wkleić z danych wyjściowych z przykładowego przykładu tworzenia.
CAMPAIGN_ID=CAMPAIGN_ID
To żądanie zawiera 2 operacje. Najpierw podejmuje próbę zmiany strategii ustalania stawek w podanej kampanii, a następnie próbuje usunąć kampanię z nieprawidłowym identyfikatorem. Druga operacja kończy się błędem (identyfikator kampanii jest nieprawidłowy), a element partialFailure
ma wartość false
, więc pierwsza też kończy się niepowodzeniem, a strategia ustalania stawek w obecnej kampanii nie jest aktualizowana.
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 pogrupowane
Metoda googleAds:mutate
umożliwia wysyłanie grup operacji z wieloma typami zasobów. Możesz wysyłać wiele operacji różnego typu, aby połączyć w łańcuch sekwencję operacji, które należy wykonać jako grupę.
Zbiór operacji zakończy się powodzeniem, jeśli żadna operacja nie powiedzie się lub wszystkie zakończą się niepowodzeniem w przypadku niepowodzenia którejkolwiek z operacji.
Ten przykład pokazuje, jak utworzyć budżet kampanii, kampanię, grupę reklam i reklamę jako jeden zestaw działań. Każda następna operacja zależy od poprzedniej. Jeśli któraś z nich się nie powiedzie, 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, używając metody createCustomerClient
. Pamiętaj, że adres URL wymaga identyfikatora konta menedżera, a nie identyfikatora konta klienta. Do konta menedżera tworzone jest 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' } }"
Wyświetlanie listy kont z dostępem
Użyj prostego żądania GET
do metody listAccessibleCustomers
, aby uzyskać listę kont Google Ads dostępnych za pomocą danego tokena dostępu OAuth 2.0. W tym żądaniu nie należy używać żadnych identyfikatorów kont menedżera ani kont klientów.
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, takie jak obraz, są kodowane jako ciąg znaków z użyciem standardowego kodowania base64 z dopełnieniem. Akceptowane jest standardowe lub bezpieczne w adresie URL kodowanie base64 z dopełnieniem lub bez niego.
W tym przykładzie koduje 1-pikselowy plik GIF, aby zachować zwięzłość. W praktyce ładunki data
są znacznie większe.
Użyj narzędzia wiersza poleceń base64
(część podstawowych narzędzi GNU) do kodowania 1-pikselowego obrazu GIF.
base64 1pixel.gif
Wartość zakodowana w base64 jest określana w żądaniu do interfejsu API jako atrybut data
.
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' } } } ] }"