Esempi

Questa guida contiene esempi di chiamata diretta agli endpoint REST, senza l'uso di una libreria client.

Prerequisiti

Tutti gli esempi riportati di seguito devono essere copiati e incollati in una bash shell utilizzando il comando curl.

Occorre anche un token sviluppatore, test l'accesso all'account è normale e Account amministratore Google Ads contenente almeno un account cliente.

Importante: in questi esempi, supponiamo che tu stia accedendo a un account cliente (CUSTOMER_ID) da un utente con accesso amministrativo a un account amministratore (MANAGER_CUSTOMER_ID) che gestisce direttamente l'account cliente. Se Invece di accedere direttamente a un account cliente individuale, ometti il login-customer-id o impostala sullo stesso valore di CUSTOMER_ID. Nota che alcuni esempi, come la creazione di account, richiedono una Account amministratore.

Variabili di ambiente

Inserisci le credenziali e gli ID dell'account di seguito, quindi copiali e incollali per configurare le variabili di ambiente usate negli esempi successivi. La guida all'autorizzazione fornisce le istruzioni per generare un Token di accesso 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"

Altri ID oggetto facoltativi

Alcuni dei seguenti esempi funzionano su campagne o budget preesistenti. Se dispongono 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 - creazione di contenuti creano un nuovo budget. e la campagna.

Cerca

La guida Suggerimenti per le query contiene molti report esempi che corrispondono ad alcune schermate predefinite di Google Ads e funzionano con le stesse variabili di ambiente utilizzate in questa guida. La nostra query interattiva di Google Cloud è è un'ottima risorsa anche per creare query personalizzate in modo interattivo.

Impaginato

Il metodo search utilizza l'impaginazione, con una dimensione di 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'

Streaming

Il metodo searchStream trasmette tutti i risultati in modalità flusso in un'unica risposta; pertanto, il 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'

Modifiche

È possibile inviare più operazioni di mutazione (create, update o remove) in un corpo della singola richiesta JSON mediante la compilazione dell'array operations.

Crea

Questo esempio crea due budget della 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 seguente utilizza una percentuale pari a BUDGET_ID di un budget della campagna esistente; puoi copia e incolla dall'output del passaggio precedente.

BUDGET_ID=BUDGET_ID

Le risorse che fanno riferimento ad altre risorse lo fanno nome risorsa. La campagna creata di seguito si riferisce a campaignBudget mediante 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. Il prossimo esempio utilizza una campagna esistente; puoi copiare e incollare dall'elenco dell'output dello step.

CAMPAIGN_ID=CAMPAIGN_ID

Tutti gli aggiornamenti richiedono un campo updateMask, un elenco separato da virgole di quali attributi JSON includere nella richiesta, che devono essere applicati come aggiornamento. Attributi elencati in updateMask ma non presenti nella richiesta vengono cancellati da un oggetto. 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

Quando in una singola richiesta sono presenti più operazioni, puoi specificare facoltativamente partialFailure. Se true, vengono eseguite correttamente le operazioni le operazioni non valide restituiscono errori. Se false, tutte le operazioni nella richiesta avranno esito positivo solo se sono tutte valide.

L'esempio successivo utilizza una campagna esistente. puoi copiare e incollare Crea un output di esempio.

CAMPAIGN_ID=CAMPAIGN_ID

La seguente richiesta contiene due operazioni. Il primo tentativo di modificare strategia di offerta della campagna fornita e quella successiva prova a rimuovere campagna con un ID non valido. Poiché la seconda operazione genera un errore (il l'ID campagna non è valido) e poiché partialFailure è impostato su false, il valore non va a buon fine anche la prima operazione e la strategia di offerta della campagna esistente non aggiornato.

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 diversi tipi una sequenza di operazioni da eseguire in gruppo. Il set di operazioni ha esito positivo se nessuna operazione non va a buon fine o se non sono riuscite tutte una singola operazione non va a buon fine.

Questo esempio mostra come creare un budget, una campagna, un gruppo di annunci e come un unico insieme di azioni. Ogni operazione successiva dipende su quello precedente. Se una non funziona, l'intero gruppo di operazioni ha esito negativo.

Nella risorsa vengono utilizzati numeri interi negativi (-1, -2, -3) come segnaposto e vengono compilati dinamicamente in fase di runtime con i risultati della sequenza delle operazioni quotidiane.

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

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. Un nuovo cliente creato 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. Nessun gestore o ID account 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 degli asset binari

Il metodo assets:mutate viene utilizzato per il caricamento e la gestione Asset. I dati binari, ad esempio un'immagine, sono codificati come una stringa che utilizza la codifica base64 standard con spaziatura interna. Standard o È accettata la codifica Base64 sicura per URL con o senza spaziatura interna.

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

Usa l'utilità a riga di comando base64 (parte di utilità principali 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'
      }
    }
  }
]
}"