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

  • 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.
  • Nível de acesso à API:o nível de acesso à API do seu projeto na nuvem do Google Cloud controla o número de chamadas de API que você pode fazer por dia e os ambientes em que é possível fazer essas chamadas. O nível de acesso à API do seu projeto está listado na página de visão geral da API Google Ads.
  • Conta de administrador do Google Ads:usada para gerenciar outras contas do Google Ads, que podem ser uma coleção de contas de cliente do Google Ads ou outras contas de administrador do Google Ads.
  • Conta de cliente do Google Ads:a conta do Google Ads usada para veicular anúncios que você quer segmentar com chamadas de API.
  • ID de cliente do cliente:o número de 10 dígitos que identifica uma conta de cliente do Google Ads. Se você copiou esse ID da interface do Google Ads, remova os hífens.
  • 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 chave para gerar credenciais do OAuth 2.0 e fazer chamadas de API.
  • Conta de serviço:um tipo especial de Conta do Google que pertence ao seu aplicativo, e não a um usuário individual. Ele é usado para autenticar seu aplicativo na API Google Ads. Você precisa de um projeto na nuvem 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 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.

Configurar seu projeto do Console de APIs do Google para acesso à API Google Ads

O projeto do Google Cloud é usado para gerenciar APIs do Google e credenciais da API OAuth 2.0. Para encontrar ou criar projetos do Google Cloud, acesse o console do Google Cloud.

Comece ativando a API Google Ads no seu projeto:

Ativar a API Google Ads

Em seguida, acesse a página de visão geral da API Google Ads. A página mostra seu nível de acesso atual à API. Se o nível de acesso à API atual for Teste, expanda a seção Fazer upgrade do nível de acesso. Siga as instruções para solicitar o nível de acesso Explorer.

Depois que você concluir a inscrição, o Google vai analisar e fazer upgrade automático para o Explorer na maioria dos casos. Se você não tiver acesso de administrador, não se preocupe. Este guia vai fornecer as instruções adequadas ao configurar sua conta de cliente do Google Ads.

Criar uma conta de serviço

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 projeto na nuvem do Google Cloud. Confira a página de visão geral da API Google Ads para saber seu nível de acesso à API.

Níveis de acesso Explorer, Basic e Standard

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

Testar o acesso

Seu projeto do Google Cloud 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.

  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 gerente de produção do Google Ads. Se não tiver, 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 está disponível para 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.

CLI do Google Cloud

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>46.0.0</version>
</dependency>

A dependência do Gradle é:

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

Também recomendamos usar a lista de materiais (BOM) da API Google Ads (link em inglês) para gerenciar versões de dependência. Consulte o guia de BOM para instruções.

Crie um arquivo ~/ads.properties com o seguinte conteúdo.

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
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.

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());
      }
    }
  }
}

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 26.1.0

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

GoogleAdsConfig config = new GoogleAdsConfig()
{
    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.V25.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;
    }
}

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:33.6.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]
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.

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
        );
    }
}

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==31.2.0

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

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 gerenciador ao registrador de eventos da biblioteca informando onde mostrar os logs. O comando a seguir instrui 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.

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.'
            )

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', '~> 43.0.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.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.

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

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
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.

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::V25::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;
}

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.

curl -i -X POST https://googleads.googleapis.com/v25/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"
}

Se você encontrar erros ao fazer sua primeira chamada, consulte Como lidar com erros da API para orientações sobre solução de problemas.

Anterior
Introdução
Avançar
Processar erros