Caution: You are viewing documentation for the API's REST interface. Most of our official client libraries use gRPC. See the REST Introduction for details.

Exemplos

Este guia contém exemplos de como chamar os endpoints REST diretamente, sem o uso de uma biblioteca de cliente.

Prerequisites

Todos os exemplos abaixo precisam ser facilmente copiados e colados em um shell bash usando o comando curl.

Também será necessário um token de desenvolvedor (acesso à conta de teste é suficiente) 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 abaixo e, em seguida, copie e cole no seu terminal para configurar as variáveis de ambiente usadas nos exemplos a seguir.

API_VERSION="11"
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 existentes para usar com esses exemplos, insira-os abaixo.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

Caso contrário, os dois exemplos de "Transformações - Cria" criarão um novo orçamento e uma nova campanha.

Paginado

O método search usa paginação, com um parâmetro pageSize ajustável 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 '{
"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 e, 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'

Mutações

Várias operações mutáveis (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 existente. É possível copiar e colar da 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 abaixo se refere a uma 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

Atualizar atributos de objetos existentes usando operações update. O próximo exemplo usa uma campanha existente. É possível copiar e colar da saída da etapa anterior.

CAMPAIGN_ID=CAMPAIGN_ID

Todas as atualizações exigem um campo updateMask, que é uma lista separada por vírgulas dos atributos JSON que precisam estar na solicitação e precisam ser aplicados como uma atualização. Os atributos listados no updateMask, mas não presentes no corpo da solicitação, são limpados 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 simplesmente especificando o nome de 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 estiverem em uma única solicitação, você tem a opção de especificar 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 todas forem válidas.

O próximo exemplo usa uma campanha existente. É possível copiar e colar a saída do exemplo 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 resulta em um erro (o ID da campanha é inválido) e, como partialFailure é definido como false, a primeira operação também falha e, portanto, a estratégia de lances atual da campanha 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 diferentes tipos para encadear uma sequência de operações a serem realizadas como um grupo. O conjunto de operações terá êxito se nenhuma operação falhar ou se todas as operações falharão.

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

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': {
          'expandedTextAd': {
            'headlinePart1': 'An example headline1',
            'headlinePart2': 'An example headline2',
            'description': 'An example description'
          },
          '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 de conta de cliente. Uma nova conta de cliente será 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 veja uma lista de contas do Google Ads que podem ser acessadas com o token de acesso OAuth 2.0 fornecido. Nenhuma ID da conta de administrador ou cliente será usada 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 paddings. A codificação base64 padrão ou segura para URL com/sem paddings é aceita.

Use o utilitário de linha de comando base64 (parte dos utilitários do GNU Core) 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'
      }
    }
  }
]
}"