Início rápido

Este guia de início rápido ajuda você a fazer sua primeira chamada de API para a API Google Ads.

Principais conceitos

  • Token de desenvolvedor: um token de desenvolvedor é uma string alfanumérica de 22 caracteres que identifica seu app para os servidores da API Google Ads. Ela é necessária para fazer chamadas de API.
  • Nível de acesso à API:o nível de acesso à API do seu token de desenvolvedor controla o número de chamadas de API que você pode fazer por dia e os ambientes em que é possível fazer chamadas de API.
  • Conta de administrador do Google Ads:usada para gerenciar outras contas do Google Ads. Uma conta de administrador do Google Ads pode ser usada para gerenciar contas de cliente ou outras contas de administrador do Google Ads. Você precisa de uma conta de administrador do Google Ads para receber um token de desenvolvedor.
  • Conta de cliente do Google Ads:a conta do Google Ads em que você está fazendo chamadas de API.
  • ID de cliente do cliente:o número de 10 dígitos que identifica uma conta de cliente do Google Ads.
  • OAuth 2.0:o OAuth 2.0 é um protocolo padrão do setor para autorização, usado por todas as APIs do Google. Você precisa de uma conta de serviço e uma chave para gerar credenciais do OAuth 2.0 e fazer chamadas de API.
  • Projeto do Google Cloud:um projeto do Google Cloud forma a base para criar, ativar e usar todos os serviços do Google, incluindo o gerenciamento de APIs e credenciais da API OAuth 2.0. É possível criar um no Console do Google Cloud.
  • Conta de serviço:um tipo especial de Conta do Google que pertence ao seu aplicativo e não a um usuário individual. Ela é usada para autenticar seu aplicativo na API Google Ads. Você precisa de um projeto do Google Cloud para conseguir uma conta de serviço.
  • Chave da conta de serviço:um arquivo JSON de credenciais do app que contém a chave privada da sua conta de serviço. Ele é usado para gerar credenciais do OAuth 2.0 e autenticar uma conta de serviço ao fazer uma chamada de API da API Google Ads. Você precisa de uma conta de serviço para receber uma chave de conta de serviço.

Pré-requisitos

Para fazer uma chamada da API Google Ads, siga estas etapas.

Receber seu token de desenvolvedor

Se você já se inscreveu para receber um token de desenvolvedor, acesse a Central de API enquanto estiver conectado à sua conta de administrador do Google Ads.

Acessar o hub de API

Se você não tiver um token de desenvolvedor, inscreva-se em um na Central de APIs.

Como se inscrever para receber um token de desenvolvedor

  1. Acesse o Central de APIs no navegador da Web. Faça login na sua conta de administrador do Google Ads, se solicitado. Crie uma conta de administrador do Google Ads se você ainda não tiver uma.
  2. Preencha o formulário de acesso à API e aceite os Termos e Condições.
    • Confira se as informações estão corretas e se o URL do site da empresa está funcionando. Se o site não estiver ativo, o Google poderá não conseguir processar e recusar sua inscrição.
    • Verifique se o e-mail de contato da API fornecido leva a uma caixa de entrada monitorada regularmente. A equipe de compliance da API do Google pode entrar em contato com esse endereço de e-mail durante o processo de revisão para esclarecimentos. Se não for possível entrar em contato com você, o Google poderá não continuar com sua inscrição.
    • Você pode editar o e-mail de contato da API no Central de APIs. Mantenha essas informações atualizadas, mesmo após o processo de inscrição, para que o Google possa enviar avisos importantes sobre o serviço.

Depois de concluir o processo de inscrição, o token de desenvolvedor vai aparecer na Central de API com o status Aprovação pendente. Seu token de desenvolvedor agora tem o nível Acesso à conta de teste.

Configurar seu projeto do Console de APIs do Google

O projeto do Console de APIs do Google é usado para gerenciar APIs do Google e credenciais da API OAuth 2.0. Acesse o Console de APIs do Google para encontrar seus projetos ou criar um.

Abra o Console de APIs do Google

Comece ativando a API Google Ads no seu projeto:

Ativar a API Google Ads

Em seguida, você precisa de uma conta de serviço e uma chave de conta de serviço para fazer chamadas de API. Se você já estiver usando outra API do Google e tiver criado uma conta de serviço e uma chave do OAuth 2.0, pule esta etapa e reutilize as credenciais atuais.

Como criar uma conta de serviço e uma chave

  1. No console do Google Cloud, acesse Menu > IAM e administrador > Contas de serviço.

    Acessar a página "Contas de serviço"

  2. Selecione sua conta de serviço.
  3. Clique em Chaves > Adicionar chave > Criar nova chave.
  4. Selecione JSON e clique em Criar.

    Seu novo par de chave pública/privada é gerado e transferido por download para sua máquina como um novo arquivo. Salve o arquivo JSON baixado como credentials.json no seu diretório de trabalho. Esse arquivo é a única cópia dessa chave.

  5. Clique em Fechar.

Comece identificando a conta do Google Ads em que você está fazendo chamadas de API. O tipo de conta para que você pode fazer chamadas de API depende do nível de acesso à API do seu token de desenvolvedor. Verifique seu nível de acesso à API no Central de APIs.

Acesso básico e padrão

Você pode fazer chamadas para sua conta de produção do Google Ads. No entanto, você pode criar uma conta de teste do Google Ads seguindo as instruções na guia Acesso à conta de teste, se necessário.

Testar o acesso à conta

Seu token de desenvolvedor não pode ser usado para fazer chamadas de API em uma conta de produção do Google Ads. Só é possível fazer chamadas de API em contas de teste do Google Ads.

Como criar uma conta de teste do Google Ads

As instruções a seguir criam uma conta de administrador de teste do Google Ads e uma conta de anunciante de teste do Google Ads abaixo dela.

  1. Clique no botão azul para criar uma conta de administrador de teste do Google Ads. Se necessário, faça login com uma Conta do Google que não esteja vinculada à sua conta de administrador de produção do Google Ads. Se você não tiver uma, use o botão Criar conta nessa página para criar uma Conta do Google.

    Criar uma conta de administrador de teste do Google Ads

  2. Na sua conta de administrador de teste do Google Ads, crie uma conta de cliente de teste do Google Ads: clique em Contas > > Criar nova conta e preencha o formulário. Todas as contas do Google Ads criadas na sua conta de administrador de teste do Google Ads são automaticamente contas de teste do Google Ads.
  3. Se quiser, crie algumas campanhas na conta de cliente de teste do Google Ads na página do Google Ads.

Para fazer uma chamada de API a um cliente do Google Ads, você precisa conceder acesso e as permissões adequadas à sua conta de serviço na conta de cliente do Google Ads. Para fazer isso, você precisa ter acesso de administrador à conta do cliente.

Como conceder à conta de serviço acesso à sua conta do Google Ads

  1. Comece fazendo login na sua conta do Google Ads como administrador.
  2. Acesse Administrador > Acesso e segurança.
  3. Clique no botão na guia Usuários.
  4. Digite o endereço de e-mail da conta de serviço na caixa de entrada E-mail. Selecione o nível de acesso à conta adequado e clique no botão Adicionar conta. O nível de acesso "E-mail" não é compatível com contas de serviço.
  5. A conta de serviço recebe acesso.
  6. [Opcional] Por padrão, não é possível conceder acesso de administrador a uma conta de serviço. Se as chamadas de API exigirem acesso de administrador, faça upgrade do acesso da seguinte maneira.
    1. Clique na seta suspensa ao lado do nível de acesso da conta de serviço na coluna Nível de acesso.
    2. Selecione Administrador na lista suspensa.

Baixar ferramentas e bibliotecas de cliente

Você pode baixar uma biblioteca de cliente ou um cliente HTTP, dependendo de como quer fazer as chamadas de API.

Usar uma biblioteca de cliente

Faça o download e instale uma biblioteca de cliente de sua escolha.

Usar cliente HTTP (REST)

curl

Faça o download e instale o curl, a ferramenta de linha de comando para transferir dados por um URL.

Google Cloud CLI

Siga as instruções para instalar a CLI gcloud.

As instruções do restante deste guia foram verificadas para funcionar com a seguinte versão da ferramenta gcloud e podem não funcionar com versões anteriores devido a diferenças no comportamento do aplicativo ou nas opções de linha de comando.

:~$ gcloud version
Google Cloud SDK 492.0.0
alpha 2024.09.06
beta 2024.09.06
bq 2.1.8
bundled-python3-unix 3.11.9
core 2024.09.06
enterprise-certificate-proxy 0.3.2
gcloud-crc32c 1.0.0
gsutil 5.30

Fazer uma chamada de API

Selecione o cliente de sua preferência para instruções sobre como fazer uma chamada de API:

Java

Os artefatos da biblioteca de cliente são publicados no repositório Maven central. Adicione a biblioteca de cliente como uma dependência ao seu projeto da seguinte maneira:

A dependência do Maven é:

<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>google-ads</artifactId>
  <version>40.0.0</version>
</dependency>

A dependência do Gradle é:

implementation 'com.google.api-ads:google-ads:40.0.0'

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Crie um objeto GoogleAdsClient da seguinte forma:

GoogleAdsClient googleAdsClient = null;
try {
  googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
} catch (FileNotFoundException fnfe) {
  System.err.printf(
      "Failed to load GoogleAdsClient configuration from file. Exception: %s%n",
      fnfe);
  System.exit(1);
} catch (IOException ioe) {
  System.err.printf("Failed to create GoogleAdsClient. Exception: %s%n", ioe);
  System.exit(1);
}

Em seguida, execute um relatório de campanha usando o método GoogleAdsService.SearchStream para recuperar as campanhas na sua conta. Este guia não aborda os detalhes da criação de relatórios.

private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
  try (GoogleAdsServiceClient googleAdsServiceClient =
      googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
    String query = "SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id";
    // Constructs the SearchGoogleAdsStreamRequest.
    SearchGoogleAdsStreamRequest request =
        SearchGoogleAdsStreamRequest.newBuilder()
            .setCustomerId(Long.toString(customerId))
            .setQuery(query)
            .build();

    // Creates and issues a search Google Ads stream request that will retrieve all campaigns.
    ServerStream<SearchGoogleAdsStreamResponse> stream =
        googleAdsServiceClient.searchStreamCallable().call(request);

    // Iterates through and prints all of the results in the stream response.
    for (SearchGoogleAdsStreamResponse response : stream) {
      for (GoogleAdsRow googleAdsRow : response.getResultsList()) {
        System.out.printf(
            "Campaign with ID %d and name '%s' was found.%n",
            googleAdsRow.getCampaign().getId(), googleAdsRow.getCampaign().getName());
      }
    }
  }
}
GetCampaigns.java

C#

Os pacotes de biblioteca de cliente são publicados no repositório Nuget.org. Comece adicionando uma referência do NuGet ao pacote Google.Ads.GoogleAds.

dotnet add package Google.Ads.GoogleAds --version 18.1.0

Crie um objeto GoogleAdsConfig com as configurações relevantes e use-o para criar um objeto GoogleAdsClient.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    DeveloperToken = "******",
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "PATH_TO_CREDENTIALS_JSON",
    LoginCustomerId = ******
};
GoogleAdsClient client = new GoogleAdsClient(config);

Em seguida, execute um relatório de campanha usando o método GoogleAdsService.SearchStream para recuperar as campanhas na sua conta. Este guia não aborda os detalhes da criação de relatórios.

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V21.GoogleAdsService);

    // Create a query that will retrieve all campaigns.
    string query = @"SELECT
                    campaign.id,
                    campaign.name,
                    campaign.network_settings.target_content_network
                FROM campaign
                ORDER BY campaign.id";

    try
    {
        // Issue a search request.
        googleAdsService.SearchStream(customerId.ToString(), query,
            delegate (SearchGoogleAdsStreamResponse resp)
            {
                foreach (GoogleAdsRow googleAdsRow in resp.Results)
                {
                    Console.WriteLine("Campaign with ID {0} and name '{1}' was found.",
                        googleAdsRow.Campaign.Id, googleAdsRow.Campaign.Name);
                }
            }
        );
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}
GetCampaigns.cs

PHP

Os pacotes da biblioteca de cliente são publicados no repositório Packagist. Mude para o diretório raiz do projeto e execute o comando a seguir para instalar a biblioteca e todas as dependências dela no diretório vendor/ do diretório raiz do projeto.

composer require googleads/google-ads-php:31.0.0

Faça uma cópia do arquivo google_ads_php.ini do repositório do GitHub e modifique-o para incluir suas credenciais.

[GOOGLE_ADS]
developerToken = "INSERT_DEVELOPER_TOKEN_HERE"
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

[OAUTH2]
jsonKeyFilePath = "INSERT_ABSOLUTE_PATH_TO_OAUTH2_JSON_KEY_FILE_HERE"
scopes = "https://www.googleapis.com/auth/adwords"

Crie uma instância do objeto GoogleAdsClient.

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

Em seguida, execute um relatório de campanha usando o método GoogleAdsService.SearchStream para recuperar as campanhas na sua conta. Este guia não aborda os detalhes da criação de relatórios.

public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId)
{
    $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
    // Creates a query that retrieves all campaigns.
    $query = 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id';
    // Issues a search stream request.
    /** @var GoogleAdsServerStreamDecorator $stream */
    $stream = $googleAdsServiceClient->searchStream(
        SearchGoogleAdsStreamRequest::build($customerId, $query)
    );

    // Iterates over all rows in all messages and prints the requested field values for
    // the campaign in each row.
    foreach ($stream->iterateAllElements() as $googleAdsRow) {
        /** @var GoogleAdsRow $googleAdsRow */
        printf(
            "Campaign with ID %d and name '%s' was found.%s",
            $googleAdsRow->getCampaign()->getId(),
            $googleAdsRow->getCampaign()->getName(),
            PHP_EOL
        );
    }
}
GetCampaigns.php

Python

A biblioteca de cliente é distribuída no PyPI e pode ser instalada usando o comando pip da seguinte maneira:

python -m pip install google-ads==21.3.0

Faça uma cópia do arquivo google-ads.yaml do repositório do GitHub e modifique-o para incluir suas credenciais.

developer_token: INSERT_DEVELOPER_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
json_key_file_path: JSON_KEY_FILE_PATH_HERE

Crie uma instância GoogleAdsClient chamando o método GoogleAdsClient.load_from_storage. Transmita o caminho para seu google-ads.yaml como uma string para o método ao chamá-lo:

from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")

Adicione um manipulador ao logger da biblioteca informando onde imprimir os registros. O seguinte comando vai instruir o logger da biblioteca a imprimir no console (stdout).

import logging
import sys

logger = logging.getLogger('google.ads.googleads.client')
logger.addHandler(logging.StreamHandler(sys.stdout))

Em seguida, execute um relatório de campanha usando o método GoogleAdsService.SearchStream para recuperar as campanhas na sua conta. Este guia não aborda os detalhes da criação de relatórios.

def main(client: GoogleAdsClient, customer_id: str) -> None:
    ga_service: GoogleAdsServiceClient = client.get_service("GoogleAdsService")

    query: str = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id"""

    # Issues a search request using streaming.
    stream: Iterator[SearchGoogleAdsStreamResponse] = ga_service.search_stream(
        customer_id=customer_id, query=query
    )

    for batch in stream:
        rows: List[GoogleAdsRow] = batch.results
        for row in rows:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f'"{row.campaign.name}" was found.'
            )
get_campaigns.py

Ruby

As gems do Ruby para a biblioteca de cliente são publicadas no site de hospedagem de gems do Rubygems. A maneira recomendada de instalar é usando o bundler. Adicione uma linha ao Gemfile:

gem 'google-ads-googleads', '~> 35.2.0'

Depois, execute:

bundle install

Faça uma cópia do arquivo google_ads_config.rb do repositório do GitHub e modifique-o para incluir suas credenciais.

Google::Ads::GoogleAds::Config.new do |c|
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
  c.keyfile = 'JSON_KEY_FILE_PATH'
end

Crie uma instância GoogleAdsClient transmitindo o caminho para onde você mantém esse arquivo.

client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')

Em seguida, execute um relatório de campanha usando o método GoogleAdsService.SearchStream para recuperar as campanhas na sua conta. Este guia não aborda os detalhes da criação de relatórios.

def get_campaigns(customer_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  responses = client.service.google_ads.search_stream(
    customer_id: customer_id,
    query: 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id',
  )

  responses.each do |response|
    response.results.each do |row|
      puts "Campaign with ID #{row.campaign.id} and name '#{row.campaign.name}' was found."
    end
  end
end
get_campaigns.rb

Perl

A biblioteca é distribuída no CPAN (link em inglês). Comece clonando o repositório google-ads-perl no diretório de sua escolha.

git clone https://github.com/googleads/google-ads-perl.git

Mude para o diretório google-ads-perl e execute o seguinte comando no prompt de comando para instalar todas as dependências necessárias para usar a biblioteca.

cd google-ads-perl
cpan install Module::Build
perl Build.PL
perl Build installdeps

Faça uma cópia do arquivo googleads.properties do repositório do GitHub e modifique-o para incluir suas credenciais.

jsonKeyFilePath=JSON_KEY_FILE_PATH
developerToken=INSERT_DEVELOPER_TOKEN_HERE
loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Crie uma instância Client transmitindo o caminho para onde você mantém esse arquivo.

my $properties_file = "/path/to/googleads.properties";

my $api_client = Google::Ads::GoogleAds::Client->new({
  properties_file => $properties_file
});

Em seguida, execute um relatório de campanha usando o método GoogleAdsService.SearchStream para recuperar as campanhas na sua conta. Este guia não aborda os detalhes da criação de relatórios.

sub get_campaigns {
  my ($api_client, $customer_id) = @_;

  # Create a search Google Ads stream request that will retrieve all campaigns.
  my $search_stream_request =
    Google::Ads::GoogleAds::V21::Services::GoogleAdsService::SearchGoogleAdsStreamRequest
    ->new({
      customerId => $customer_id,
      query      =>
        "SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id"
    });

  # Get the GoogleAdsService.
  my $google_ads_service = $api_client->GoogleAdsService();

  my $search_stream_handler =
    Google::Ads::GoogleAds::Utils::SearchStreamHandler->new({
      service => $google_ads_service,
      request => $search_stream_request
    });

  # Issue a search request and process the stream response to print the requested
  # field values for the campaign in each row.
  $search_stream_handler->process_contents(
    sub {
      my $google_ads_row = shift;
      printf "Campaign with ID %d and name '%s' was found.\n",
        $google_ads_row->{campaign}{id}, $google_ads_row->{campaign}{name};
    });

  return 1;
}
get_campaigns.pl

curl

Comece definindo a conta de serviço como as credenciais ativas na CLI da gcloud.

gcloud auth login --cred-file=PATH_TO_CREDENTIALS_JSON

Em seguida, busque um token de acesso do OAuth 2.0 para a API Google Ads.

gcloud auth \
  print-access-token \
  --scopes='https://www.googleapis.com/auth/adwords'

Em seguida, execute um relatório de campanha usando o método GoogleAdsService.SearchStream para recuperar as campanhas na sua conta. Este guia não aborda os detalhes da criação de relatórios.

curl -i -X POST https://googleads.googleapis.com/v21/customers/CUSTOMER_ID/googleAds:searchStream \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ACCESS_TOKEN" \
   -H "developer-token: DEVELOPER_TOKEN" \
   -H "login-customer-id: LOGIN_CUSTOMER_ID" \
   --data-binary "@query.json"

O conteúdo de query.json é o seguinte:

{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}
Anterior
Introdução
Avançar
Erros comuns