Questa guida contiene esempi di chiamate dirette degli endpoint REST, senza l'utilizzo di una libreria client.
Prerequisiti
Tutti gli esempi riportati di seguito devono essere copiati e incollati in una shell bash utilizzando il comando curl.
Sono inoltre necessari un token sviluppatore, l'accesso all'account di prova e un account amministratore Google Ads contenente almeno un account cliente.
Variabili di ambiente
Inserisci le credenziali e gli ID dell'account di seguito, quindi copia e incolla nel terminale per configurare le variabili di ambiente utilizzate negli esempi successivi. La guida sull'autorizzazione fornisce le istruzioni per generare un token di accesso 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"
ID oggetto aggiuntivi facoltativi
Alcuni degli esempi riportati di seguito funzionano con budget o campagne preesistenti. Se disponi di ID di oggetti esistenti da utilizzare con questi esempi, inseriscili di seguito.
BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID
In caso contrario, i due esempi di Mutate - Crea 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. Anche il nostro strumento interattivo di creazione di query è un'ottima risorsa per la creazione interattiva di query personalizzate.
Impaginato
Il metodo search
utilizza l'impaginazione, con un parametro pageSize
regolabile 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 '{ "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 (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'
Flussi di dati
Il metodo searchStream
trasmette tutti i risultati in streaming in un'unica risposta, pertanto il campo pageSize
non è supportato.
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 (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
singolo corpo della richiesta JSON compilando l'array operations
.
Crea
In questo esempio vengono creati due budget di campagna condivisi in una singola 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 valore BUDGET_ID
di un budget di campagna esistente; puoi
copiare e incollare dall'output del passaggio precedente.
BUDGET_ID=BUDGET_ID
Le risorse che fanno riferimento ad altre risorse lo fanno in base al nome della risorsa. La campagna creata di seguito
fa riferimento a un campaignBudget
dal 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 dall'output del passaggio precedente.
CAMPAIGN_ID=CAMPAIGN_ID
Tutti gli aggiornamenti richiedono un campo updateMask
, un elenco separato da virgole degli attributi JSON che devono essere presenti nella richiesta e che deve essere applicato come aggiornamento. Gli attributi elencati in updateMask
ma non presenti nel corpo della richiesta
vengono cancellati in 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 nome della 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
Se in una singola richiesta sono presenti più operazioni, puoi specificare facoltativamente partialFailure
. Se true
, vengono eseguite operazioni riuscite e quelle
non valide restituiscono errori. Se false
, tutte le operazioni nella richiesta hanno esito positivo solo se sono tutte valide.
L'esempio successivo utilizza una campagna esistente; puoi copiare e incollare dall'output dell'esempio Creates.
CAMPAIGN_ID=CAMPAIGN_ID
La richiesta seguente contiene due operazioni. Il primo tentativo di modificare la strategia di offerta della campagna fornita e il successivo prova a 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 ha esito negativo 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 tipo diverso per
concatenare una sequenza di operazioni da eseguire come gruppo.
Il set di operazioni ha esito positivo se nessuna operazione fallisce o tutte le operazioni non vanno a buon fine se una singola operazione ha esito negativo.
Questo esempio mostra come creare contemporaneamente il budget di una campagna, una campagna, un gruppo di annunci e un annuncio come singolo insieme di azioni. Ogni operazione successiva dipende da quella precedente. Se una operazione non funziona, l'intero gruppo di operazioni ha esito negativo.
I numeri interi negativi (-1
, -2
, -3
) vengono utilizzati come segnaposto nei nomi delle risorse e vengono riempiti in modo dinamico durante il 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 dell'account
Creazione di 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
sotto l'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 deve essere utilizzato alcun ID 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}" \
Caricamento di 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 spaziatura interna. È accettata la codifica Base64 standard o sicura per URL, con o senza spaziatura interna.
Questo esempio codifica una GIF da 1 pixel per mantenere il campione conciso. In pratica, i payload di data
sono molto più grandi.
Utilizza l'utilità a riga di comando base64
(parte delle utilità principali di GNU) per codificare un'immagine GIF da 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' } } } ] }"