Este guia contém exemplos de como chamar diretamente os endpoints REST, sem o uso de uma biblioteca de cliente.
Pré-requisitos
Todas as amostras abaixo podem ser copiadas e coladas em um shell bash usando o comando curl.
Você também precisa de um token de desenvolvedor, acesso à conta de teste e uma conta de administrador do Google Ads com pelo menos uma conta de cliente.
Variáveis de ambiente
Insira as credenciais e os IDs da conta abaixo. Em seguida, copie e cole no terminal para configurar as variáveis de ambiente usadas nos exemplos subsequentes. O guia Autorização fornece instruções para gerar um token de acesso do 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"
IDs de objetos opcionais adicionais
Alguns dos exemplos a seguir funcionam em orçamentos ou campanhas preexistentes. Se você tiver IDs de objetos existentes para usar com esses exemplos, insira-os abaixo.
BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID
Caso contrário, os dois Mudanças - Criar exemplos criam um novo orçamento e uma nova campanha.
Pesquisar
O Manual de consulta contém muitos exemplos de relatórios que correspondem a algumas telas padrão do Google Ads e funcionam com as mesmas variáveis de ambiente usadas neste guia. Nossa ferramenta de criação de consultas interativas também é um ótimo recurso para criar consultas personalizadas de maneira interativa.
Paginado
O método search
usa paginação, com um parâmetro pageSize
ajustável especificado junto com 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
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 é compatível.
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
Várias operações de modificaçã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 um BUDGET_ID
de um orçamento de campanha atual. Você pode copiar e colar do resultado da etapa anterior.
BUDGET_ID=BUDGET_ID
Os recursos que se referem a outros recursos fazem isso pelo
nome do recurso. A campanha criada abaixo se refere a um 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 os atributos de objetos atuais usando operações update
. O próximo exemplo usa uma campanha atual. Você pode copiar e colar a partir da saída 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 e que precisam ser aplicados 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
Os objetos são removidos especificando 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, você tem a opção de especificar
partialFailure
. Se for true
, as operações bem-sucedidas serão executadas e
as operações inválidas retornarão erros. Se for false
, todas as operações na solicitação
terão sucesso se, e somente se, todas forem válidas.
O próximo exemplo usa uma campanha atual. É possível copiar e colar do exemplo Creates de saída.
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 ID inválido. Como a segunda operação resulta em um erro (o ID da campanha é inválido) e como partialFailure
está definido como false
, a primeira operação também falha e a estratégia de lances da campanha existente 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
oferece suporte ao 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 falharão se alguma operação falhar.
Este exemplo demonstra a criação de um orçamento de campanha, uma campanha, um grupo de anúncios e um anúncio como um único conjunto de ações. Cada operação sucessiva depende da anterior. Se uma delas falhar, todo o grupo de operações vai falhar.
Números inteiros negativos (-1
, -2
, -3
) são usados como marcadores de posição nos nomes
de recursos e são preenchidos dinamicamente no ambiente de 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 exige um ID de conta de administrador em vez de um ID de 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
e receba uma lista de contas do Google Ads que podem ser acessadas com o token de acesso do OAuth 2.0 fornecido. Nenhum ID de conta de administrador ou cliente deve ser usado nesta 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
Recursos. Os dados binários, como uma imagem, são codificados como
uma string usando a codificação base64 padrão com padding. A codificação base64 padrão ou segura para URL, com ou sem padding, é aceita.
Este exemplo codifica um GIF de 1 pixel para manter a amostra concisa. Na prática, os payloads de data
são muito maiores.
Use o utilitário de linha de comando base64
, 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' } } } ] }"