Exemplos

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.

Importante :nesses exemplos, presumimos que você esteja acessando uma conta de cliente (CUSTOMER_ID) por um usuário com acesso administrativo a uma conta de administrador (MANAGER_CUSTOMER_ID) que gerencia diretamente a conta de cliente. Se você estiver acessando uma conta de cliente individual diretamente, omita o cabeçalho login-customer-id ou defina-o com o mesmo valor que CUSTOMER_ID. Alguns exemplos, como Criar contas, exigem uma conta de administrador.

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