O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Exemplos

Este guia contém exemplos de chamadas diretas para os endpoints REST, sem o uso de uma biblioteca de cliente.

Para exemplos de código mais detalhados, consulte o repositório de exemplos de código REST do GitHub.

Para conferir os corpos de solicitação e resposta de cada método de API, consulte a documentação de referência dos endpoints de serviço específicos.

Por exemplo, a página de referência para GoogleAdsService.Search mostra os corpos de solicitação e resposta do Search método.

Pré-requisitos

Todos os exemplos mostrados aqui devem ser copiados e colados em um bash shell 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 que contenha pelo menos uma conta de cliente.

Variáveis de ambiente

Insira as credenciais e os IDs da conta conforme mostrado e copie e cole no terminal para configurar as variáveis de ambiente usadas nos exemplos subsequentes. O guia de autorização fornece instruções para gerar um token de acesso 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"

Outros IDs de objeto opcionais

Alguns dos exemplos a seguir funcionam em orçamentos ou campanhas pré-existentes. Se você tiver IDs de objetos atuais para usar com esses exemplos, insira-os conforme mostrado.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

Caso contrário, os dois exemplos de mutações – criações criam um novo orçamento e uma campanha.

Pesquisar

O guia Receitas de consultas contém muitos exemplos 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 interativa de criação de consultas também é um ótimo recurso para criar consultas personalizadas de forma interativa.

Paginado

O método search usa a paginação, com um tamanho de página fixo de 10.000 itens e um page_token especificado junto com 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

O método searchStream transmite todos os resultados em uma única resposta. Portanto, o campo pageSize está indisponí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'

Mutações

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 um BUDGET_ID de um orçamento de campanha atual. Você pode copiar e colar a saída da etapa anterior.

BUDGET_ID=BUDGET_ID

Os recursos que se referem a outros recursos fazem isso por nome do recurso. A campanha criada no exemplo a seguir se refere a um campaignBudget pelo nome do 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 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 devem estar na solicitação, que precisam ser aplicados como uma atualização. Os atributos listados no updateMask, mas não presentes no corpo da solicitação, são limpos 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, especifique partialFailure opcionalmente. Se 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 somente se forem válidas.

O próximo exemplo usa uma campanha atual. Você pode copiar e colar a saída do exemplo Cria example.

CAMPAIGN_ID=CAMPAIGN_ID

A solicitação a seguir contém duas operações. A primeira tenta mudar 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 resulta em 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 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 como um grupo. O conjunto de operações será bem-sucedido se nenhuma operação falhar ou todas falharem se alguma operação falhar.

Este exemplo demonstra a criação de um orçamento da campanha, campanha, grupo de anúncios e anúncio como um único conjunto de ações. Cada operação sucessiva depende da anterior. Se uma falhar, todo o grupo de operações falhará.

Números inteiros negativos (-1, -2, -3) são usados como marcadores nos nomes de recursos e são preenchidos dinamicamente no tempo 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

É possível criar contas, listar contas acessíveis e fazer upload de recursos binários.

Criar 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'
}
}"

Listar contas acessíveis

Use uma solicitação GET simples para o método listAccessibleCustomers para receber uma lista de contas do Google Ads acessíveis com o token de acesso OAuth 2.0 fornecido. Nenhum ID de conta de administrador ou de cliente precisa 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}" \

Fazer 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 preenchimento. A codificação base64 padrão ou segura para URL com ou sem preenchimento é aceita.

Este exemplo codifica um GIF de 1 pixel para manter o exemplo conciso. 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'
      }
    }
  }
]
}"

Erros comuns

Avançar

Testar

Exemplos Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Pré-requisitos

Variáveis de ambiente

Outros IDs de objeto opcionais

Pesquisar

Paginado

curl

GAQL

Streaming

curl

GAQL

Mutações

Gera

Atualizações

Remover

Falhas parciais

Operações agrupadas

Gerenciamento da conta

Criar contas

Listar contas acessíveis

Fazer upload de recursos binários

Exemplos