Questa guida contiene esempi di chiamata diretta degli endpoint REST, senza l'utilizzo di una libreria client.
Prerequisiti
Tutti gli esempi mostrati qui sono pensati per essere copiati e incollati in una shell bash utilizzando il comando curl.
Ti serve anche un token sviluppatore, l'accesso all'account di test va bene e un account amministratore Google Ads contenente almeno un account cliente.
Variabili di ambiente
Inserisci le credenziali e gli ID account come mostrato, poi copiali e incollali nel terminale per configurare le variabili di ambiente utilizzate negli esempi successivi. La guida Autorizzazione fornisce istruzioni per generare un token di accesso OAuth 2.0.
API_VERSION="21"
DEVELOPER_TOKEN="DEVELOPER_TOKEN"
OAUTH2_ACCESS_TOKEN="OAUTH_ACCESS_TOKEN"
MANAGER_CUSTOMER_ID="MANAGER_CUSTOMER_ID"
CUSTOMER_ID="CUSTOMER_ID"ID oggetto facoltativi aggiuntivi
Alcuni degli esempi riportati di seguito funzionano con budget o campagne preesistenti. Se hai ID di oggetti esistenti da utilizzare con questi esempi, inseriscili come mostrato.
BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_IDIn caso contrario, i due Mutates - Creates examples creano un nuovo budget e una nuova campagna.
Cerca
La guida Query Cookbook contiene molti esempi di report che corrispondono ad alcune delle schermate predefinite di Google Ads e funzionano con le stesse variabili di ambiente utilizzate in questa guida. Il nostro strumento di creazione di query interattive è anche un'ottima risorsa per creare query personalizzate in modo interattivo.
Impaginato
Il metodo search utilizza la paginazione, con una dimensione della pagina fissa di 10.000 elementi e
un page_token specificato insieme a 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}" }'
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'
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'
Modifica
È possibile inviare più operazioni di modifica (create, update o remove) in un unico corpo della richiesta JSON compilando l'array operations.
Crea
Questo esempio crea due budget condivisi per le campagne in un'unica richiesta.
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, } } ] }"
L'esempio successivo utilizza un BUDGET_ID del budget di una campagna esistente. Puoi
copiare e incollare l'output del passaggio precedente.
BUDGET_ID=BUDGET_IDLe risorse che fanno riferimento ad altre risorse lo fanno tramite il
nome della risorsa. La campagna creata nell'esempio
seguente fa riferimento a un campaignBudget in base al nome della risorsa
con valore stringa.
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': {} } } ] }"
Aggiornamenti
Aggiorna gli attributi degli oggetti esistenti utilizzando le operazioni update. L'esempio
successivo utilizza una campagna esistente; puoi copiare e incollare l'output del passaggio
precedente.
CAMPAIGN_ID=CAMPAIGN_IDTutti gli aggiornamenti richiedono un campo updateMask, un elenco separato da virgole
degli attributi JSON che devono essere inclusi nella richiesta e che devono essere applicati come
aggiornamento. Gli attributi elencati in updateMask ma non presenti nel corpo della richiesta
vengono cancellati da un oggetto. Gli attributi non elencati in updateMask, ma
presenti nel corpo della richiesta, vengono ignorati.
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' } ], }"
Rimuovi
Gli oggetti vengono rimossi specificando il relativo nome risorsa come operazione 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}' } ], }"
Errori parziali
Quando in una singola richiesta sono presenti più operazioni, specifica facoltativamente
partialFailure. Se true, le operazioni riuscite vengono eseguite e
le operazioni non valide restituiscono errori. Se false, tutte le operazioni nella richiesta
vanno a buon fine se e solo se sono tutte valide.
L'esempio successivo utilizza una campagna esistente. Puoi copiare e incollare l'output dell'esempio Creates.
CAMPAIGN_ID=CAMPAIGN_IDLa seguente richiesta contiene due operazioni. Il primo tentativo di modificare la strategia di offerta della campagna fornita, mentre il successivo tenta di rimuovere una campagna con un ID non valido. Poiché la seconda operazione genera un errore (l'ID campagna non è valido) e poiché partialFailure è impostato su false, anche la prima operazione non riesce e la strategia di offerta della campagna esistente non viene aggiornata.
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' } ] }"
Operazioni raggruppate
Il metodo googleAds:mutate supporta l'invio di gruppi di operazioni con
più tipi di risorse. Puoi inviare molte operazioni di tipi diversi per
concatenare una sequenza di operazioni da eseguire come gruppo.
Il set di operazioni ha esito positivo se nessuna operazione ha esito negativo o tutte hanno esito negativo se una singola operazione ha esito negativo.
Questo esempio mostra la creazione di un budget della campagna, una campagna, un gruppo di annunci e un annuncio insieme come un unico insieme di azioni. Ogni operazione successiva dipende da quella precedente. Se una non va a buon fine, l'intero gruppo di operazioni non va a buon fine.
I numeri interi negativi (-1, -2, -3) vengono utilizzati come segnaposto nei nomi delle risorse e vengono compilati dinamicamente in fase di runtime con i risultati della sequenza di operazioni.
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'] } } } } ] }"
Gestione account
Puoi creare account, elencare gli account accessibili e caricare asset binari.
Creare account
Crea nuovi account utilizzando il metodo createCustomerClient. Tieni presente che l'URL
richiede un ID account amministratore anziché un ID account cliente. Viene creato un nuovo account cliente nell'account amministratore.
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' } }"
Elenco degli account accessibili
Utilizza una semplice richiesta GET al metodo listAccessibleCustomers per ottenere un elenco
di account Google Ads accessibili con il token di accesso OAuth 2.0 specificato. In questa richiesta non devono essere utilizzati ID di account amministratore o cliente.
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}" \
Caricare asset binari
Il metodo assets:mutate viene utilizzato per caricare e gestire gli
asset. I dati binari, ad esempio un'immagine, vengono codificati come stringa utilizzando la codifica Base64 standard con padding. Sono accettate la codifica Base64 standard o sicura per gli URL con o senza padding.
Questo esempio codifica una GIF di 1 pixel per mantenere il campione conciso. In pratica, i payload
data sono molto più grandi.
Utilizza l'utilità a riga di comando base64 (parte di
GNU core utilities)
per codificare un'immagine GIF di 1 pixel.
base64 1pixel.gif
Il valore con codifica Base64 viene specificato come attributo data in una richiesta 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' } } } ] }"