Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Esempi

Questa guida contiene esempi di chiamate dirette agli endpoint REST, senza l'utilizzo di una libreria client.

Per esempi di codice più dettagliati, consulta il repository GitHub degli esempi di codice REST .

Per visualizzare i corpi delle richieste e delle risposte per ogni metodo API, consulta la documentazione di riferimento per gli endpoint di servizi specifici.

Ad esempio, la pagina di riferimento per GoogleAdsService.Search mostra i corpi delle richieste e delle risposte per il Search metodo.

Prerequisiti

Tutti gli esempi mostrati qui sono pensati per essere copiati e incollati in una bash shell utilizzando il comando curl.

Avrai anche bisogno di un token sviluppatore, accesso all'account di test è sufficiente e un account amministratore Google Ads contenente almeno un account cliente.

Variabili di ambiente

Inserisci le credenziali e gli ID dell'account come mostrato, quindi copia e incolla nel terminale per configurare le variabili di ambiente utilizzate negli esempi successivi. La guida all'autorizzazione fornisce istruzioni per generare un token di accesso OAuth 2.0.

API_VERSION="25"
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 seguenti 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_ID

In caso contrario, i due esempi di Mutates - Creates 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 interattivo è 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 alla 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'

Streaming

Il metodo searchStream trasmette in streaming tutti i risultati 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

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'

Mutates

È possibile inviare più operazioni di mutazione (create, update o remove) in un unico corpo della richiesta JSON compilando l'array operations.

Creates

Questo esempio crea due budget di campagna condivisi 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 di un budget della campagna esistente; puoi copiare e incollare l'output del passaggio precedente.

BUDGET_ID=BUDGET_ID

Le 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 tramite il 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_ID

Tutti gli aggiornamenti richiedono un campo updateMask, un elenco separato da virgole degli attributi JSON che devono essere presenti nella richiesta e che devono essere applicati 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 loro 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 hanno esito positivo se e solo se sono tutte valide.

L'esempio successivo utilizza una campagna esistente; puoi copiare e incollare l'output dell'esempio Creates example.

CAMPAIGN_ID=CAMPAIGN_ID

La seguente richiesta contiene due operazioni. La prima tenta di modificare la strategia di offerta della campagna fornita, mentre la seconda 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 va a buon fine 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 che devono essere eseguite come gruppo. Il set di operazioni ha esito positivo se nessuna operazione non va a buon fine o tutte non vanno a buon fine se una singola operazione non va a buon fine.

Questo esempio mostra la creazione di un budget della campagna, una campagna, un gruppo di annunci e un annuncio come un unico set di azioni. Ogni operazione successiva dipende dalla 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.

Crea account

Crea nuovi account utilizzando il metodo createCustomerClient. Tieni presente che l'URL richiede l'ID di un account amministratore anziché l'ID di un 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'
}
}"

Elenca gli 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}" \

Carica asset binari

Il metodo assets:mutate viene utilizzato per caricare e gestire gli asset. I dati binari, come un'immagine, vengono codificati come stringa utilizzando la codifica base64 standard con padding. Sono accettate la codifica base64 standard o sicura per URL con o senza padding.

Questo esempio codifica una GIF di 1 pixel per mantenere l'esempio conciso. In pratica, i payload data sono molto più grandi.

Utilizza l'utilità a riga di comando base64 (parte delle utilità di base GNU) per codificare un'immagine GIF di 1 pixel.

base64 1pixel.gif

Il valore codificato in 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'
      }
    }
  }
]
}"

Esempi Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Prerequisiti

Variabili di ambiente

ID oggetto facoltativi aggiuntivi

Cerca

Impaginato

curl

GAQL

Streaming

curl

GAQL

Mutates

Creates

Aggiornamenti

Rimuovi

Errori parziali

Operazioni raggruppate

Gestione account

Crea account

Elenca gli account accessibili

Carica asset binari

Esempi