Este guia contém exemplos de como chamar os endpoints REST diretamente, sem o uso de uma biblioteca de cliente.
Pré-requisitos
Todas as amostras abaixo devem ser copiadas e coladas em um shell bash usando o comando curl.
Você também precisa de um token de desenvolvedor, um acesso à conta de teste e uma conta de administrador do Google Ads que tenha pelo menos uma conta de cliente.
Variáveis de ambiente
Insira os IDs e as credenciais da conta abaixo e, em seguida, copie e cole no seu terminal para configurar as variáveis de ambiente usadas nos exemplos a seguir. O guia de Autorização fornece instruções para gerar um token de acesso do 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"
Outros IDs de objetos opcionais
Alguns dos exemplos a seguir funcionam em orçamentos ou campanhas preexistentes. Se você tiver IDs de objetos para usar com esses exemplos, insira-os abaixo.
BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID
Caso contrário, os dois Mutates - Creates examples vão criar um novo orçamento e uma nova campanha.
Pesquisar
O Manual de consulta contém muitas amostras de relatórios que correspondem a algumas das telas padrão do Google Ads e funcionam com as mesmas variáveis de ambiente usadas neste guia. Nossa ferramenta criadora de consultas interativa também é um ótimo recurso para criar consultas personalizadas de maneira interativa.
Paginado
O método search
usa paginação, com um tamanho de página fixo de 10.000 itens e
um page_token
especificado ao lado de 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
O método searchStream
transmite todos os resultados em uma única resposta, portanto, o
campo pageSize
não tem suporte.
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'
Mudanças
Várias operações de mutação (create
, update
ou remove
) podem ser enviadas em um único corpo de solicitação JSON preenchendo a matriz operations
.
Gera
Este exemplo cria dois orçamentos de campanha compartilhados em uma única solicitação.
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, } } ] }"
O próximo exemplo usa o BUDGET_ID
de um orçamento de campanha atual. É possível copiar e colar o resultado da etapa anterior.
BUDGET_ID=BUDGET_ID
Os recursos que se referem a outros fazem isso pelo
nome do recurso. A campanha criada abaixo se refere a uma campaignBudget
pelo nome de recurso com valor de string.
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': {} } } ] }"
Atualizações
Atualize atributos de objetos existentes usando operações update
. O próximo exemplo usa uma campanha atual. É possível copiar e colar o resultado da etapa anterior.
CAMPAIGN_ID=CAMPAIGN_ID
Todas as atualizações exigem um campo updateMask
, uma lista separada por vírgulas de quais atributos JSON precisam estar na solicitação, que precisa ser aplicado como uma atualização. Os atributos listados no updateMask
, mas ausentes no corpo da solicitação,
são apagados em um objeto. Os atributos não listados no updateMask
, mas presentes
no corpo da solicitação, são ignorados.
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' } ], }"
Remover
Para remover objetos, especifique o nome do recurso como uma operação 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}' } ], }"
Falhas parciais
Quando várias operações estão em uma única solicitação, como opção, especifique
partialFailure
. Se for true
, as operações bem-sucedidas serão realizadas e
as inválidas retornarão erros. Se false
, todas as operações na solicitação
serão bem-sucedidas se e somente se forem válidas.
O próximo exemplo usa uma campanha atual. É possível copiar e colar da saída de exemplo de Cria.
CAMPAIGN_ID=CAMPAIGN_ID
A solicitação a seguir contém duas operações. A primeira tenta alterar a estratégia de lances da campanha fornecida, e a próxima tenta remover uma campanha com um ID inválido. Como a segunda operação gera um erro (o ID da campanha é inválido) e partialFailure
está definido como false
, a primeira operação também falha, e a estratégia de lances da campanha atual não é atualizada.
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' } ] }"
Operações agrupadas
O método googleAds:mutate
é compatível com o envio de grupos de operações com
vários tipos de recursos. É possível enviar muitas operações de tipos diferentes para
encadear uma sequência de operações que precisam ser realizadas em grupo.
O conjunto de operações será bem-sucedido se nenhuma operação falhar ou todas falharem se apenas uma delas falhar.
Este exemplo demonstra a criação de um orçamento de campanha, uma campanha, um grupo de anúncios e um anúncio juntos como um único conjunto de ações. Cada operação sucessiva depende da anterior. Se uma delas falhar, o grupo de operações vai falhar.
Os números inteiros negativos (-1
, -2
, -3
) são usados como marcadores nos nomes dos
recursos e são preenchidos dinamicamente no momento da execução com os resultados da sequência
de operações.
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'] } } } } ] }"
Gerenciamento da conta
Criação de contas
Crie novas contas usando o método createCustomerClient
. O URL requer um ID da conta de administrador em vez de um ID da conta de cliente. Uma nova conta de cliente é criada na conta de administrador.
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' } }"
Como listar contas acessíveis
Use uma solicitação GET
simples para o método listAccessibleCustomers
para ver uma lista de contas do Google Ads acessíveis com o token de acesso do OAuth 2.0 fornecido. Nenhum ID de conta de administrador ou de cliente deve ser usado nessa solicitação.
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}" \
Upload de recursos binários
O método assets:mutate
é usado para fazer upload e gerenciar
Assets. Os dados binários, como uma imagem, são codificados como
uma string usando a codificação base64 padrão com padding. É aceita a codificação base64 padrão ou segura para URL com ou sem padding.
Este exemplo codifica um GIF de 1 pixel para manter a amostra concisa. Na prática, os
payloads data
são muito maiores.
Use o utilitário de linha de comando base64
, que faz parte dos
utilitários principais do GNU,
para codificar uma imagem GIF de 1 pixel.
base64 1pixel.gif
O valor codificado em base64 é especificado como o atributo data
em uma solicitação de 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' } } } ] }"