Guia de integração da API Google Ads

Este guia detalha o processo completo de integração, autenticação e como fazer sua primeira chamada para a API Google Ads.

1. Pré-requisitos e hierarquia de contas

Antes de interagir com a API Google Ads, você precisa entender a hierarquia de contas e ter a estrutura correta de conta de nível superior.

  • Conta de administrador (MCC) : uma conta de administrador do Google Ads (antiga Minha central de clientes) é uma conta principal usada para visualizar e gerenciar várias contas de clientes. Você precisa ter uma conta de administrador para solicitar um token de desenvolvedor da API Google Ads.
  • Conta de cliente:a conta padrão em que as campanhas, os grupos de anúncios e os anúncios são criados e o faturamento é configurado.

Ação necessária:se você não tiver uma conta de administrador, crie uma em Contas de administrador do Google Ads.

2. Receber um token de desenvolvedor

O token de desenvolvedor identifica seu aplicativo de maneira exclusiva para a API Google Ads e controla seu nível de acesso ao volume de chamadas.

Etapas para participar

  1. Faça login na sua conta de administrador do Google Ads.
  2. Acesse Ferramentas e configurações > Configuração > Central de APIs (ou Admin > Central de APIs).
  3. Preencha o formulário de detalhes do desenvolvedor e concorde com os Termos de Serviço da API.
  4. Envie sua inscrição.

Níveis de acesso

  • Aprovação pendente:os tokens recém-criados recebem imediatamente o status "Pendente". Você pode usar um token pendente para se conectar a contas de teste imediatamente, mas ele não funciona com contas de produção.
  • Acesso básico:permite até 15.000 operações de API por dia após a aprovação.
  • Acesso padrão:operações de API diárias ilimitadas para aplicativos que atendem aos Recursos mínimos obrigatórios (RMF, na sigla em inglês).

3. Configurar contas de teste

O desenvolvimento e os testes em contas de produção correm o risco de gerar gastos com publicidade e modificações de campanha indesejados. É altamente recomendável realizar todo o desenvolvimento ativo em contas de teste.

Criar uma conta de administrador de teste

  1. Acesse a página de criação de conta de administrador de teste do Google Ads.
  2. Faça login com uma Conta do Google que ainda não esteja vinculada à sua conta de administrador de produção do Google Ads.
  3. Insira um nome descritivo para a conta (por exemplo, MyCompany Test MCC).
  4. Selecione o uso principal como Gerenciar contas de outras pessoas.
  5. Escolha o país de faturamento, o fuso horário e a moeda. Clique em Salvar e continuar.

Criar uma conta de cliente de teste

Depois que a conta de administrador de teste for criada, você precisará criar pelo menos uma conta de cliente secundária para veicular campanhas de teste.

  1. Faça login na conta de administrador de teste recém-criada.
  2. No menu de navegação à esquerda, clique em Contas e selecione Configurações da subconta (ou Performance).
  3. Clique no botão azul + (mais) e selecione Criar nova conta.
  4. Selecione Conta do Google Ads.
  5. Insira um nome de conta (por exemplo, Test Client Account A).
  6. Selecione um fuso horário e uma moeda e clique em Salvar e continuar.
  7. Anote o ID do cliente de 10 dígitos (por exemplo, 1234567890 sem hifens) dessa nova conta de cliente.

Regras importantes para contas de teste

  • Uso do token de desenvolvedor:não solicite um token de desenvolvedor na sua conta de administrador de teste. Sempre use o token de desenvolvedor pendente ou aprovado da sua conta de administrador de produção.
  • Faturamento:as contas de teste não veiculam anúncios reais. Portanto, não é necessário inserir informações de faturamento reais.

4. Configuração do projeto do Google Cloud

Todas as solicitações de API precisam ser autenticadas usando um projeto na nuvem do Google Cloud com a API Google Ads ativada.

Etapas para ativar a API

  1. Acesse o Console do Google Cloud.
  2. Crie um projeto ou selecione um já existente.
  3. Acesse APIs e serviços > Biblioteca.
  4. Pesquise API Google Ads e clique em Ativar.

Preços e faturamento

  • Sem taxas de API:a criação de um projeto do Google Cloud, a ativação da API Google Ads e a geração de credenciais do OAuth 2.0 são 100% sem custo financeiro. O Google não cobra taxas para chamar ou usar a API Google Ads.
  • Outros recursos do Cloud:você só vai incorrer em taxas do Google Cloud se usar ativamente outros serviços faturáveis do Google Cloud (como Compute Engine, Cloud Run ou BigQuery) além dos limites da camada sem custo financeiro para hospedar seu aplicativo ou armazenar dados de anúncios.

5. Configuração de autenticação do OAuth 2.0

A API Google Ads usa o OAuth 2.0 para autenticar e autorizar solicitações.

Etapas para o fluxo de aplicativos para computador

  1. No seu projeto na nuvem do Google Cloud, acesse APIs e serviços > Tela de permissão OAuth e configure a tela de permissão. Adicione seu endereço de e-mail à seção Usuários de teste enquanto o app estiver no status "Em teste" para evitar erros de acesso durante a autorização.
  2. Acesse APIs e serviços > Credenciais.
  3. Clique em Criar credenciais > ID do cliente OAuth.
  4. Selecione o tipo de aplicativo como App para computador.
  5. Clique em Criar e faça o download do arquivo de credenciais do OAuth como client_secret.json (ou copie o Client ID e a Client Secret).

Gerar um token de atualização

Depois de ter o ID e a chave secreta do cliente, você precisa gerar um token de atualização. É possível fazer isso usando o OAuth 2.0 Playground do Google ou um script de biblioteca de cliente.

Método A: usar o OAuth 2.0 Playground do Google

  1. Acesse o OAuth 2.0 Playground do Google.
  2. Clique no ícone de engrenagem (configuração do OAuth 2.0) no canto superior direito.
  3. Marque a caixa de seleção Use your own OAuth credentials.
  4. Insira o Client ID e a Client Secret do OAuth2 e clique em Fechar.
  5. Na Etapa 1 (Selecionar e autorizar APIs) à esquerda, insira o escopo da API Google Ads no campo "Input your own scopes": https://www.googleapis.com/auth/adwords
  6. Clique em Authorize APIs. Quando solicitado, faça login na Conta do Google que tem acesso à sua conta de administrador do Google Ads (ou conta de teste).
  7. Clique em Continuar na tela de permissão.
  8. Na Etapa 2 (Trocar código de autorização por tokens), clique no botão azul Trocar código de autorização por tokens.
  9. Seu Refresh token e Access token serão exibidos no painel de resposta. Copie e salve o Refresh token.

Método B: usar o script da biblioteca de cliente (exemplo em Python)

A biblioteca de cliente oficial do Python oferece um script auxiliar integrado para gerar credenciais. Como alternativa, você pode fazer o download do client_secret.json no console do Google Cloud e executar o seguinte script Python independente:

  1. Instale a biblioteca OAuth necessária:
pip install google-auth-oauthlib
  1. Crie um script chamado generate_refresh_token.py no mesmo diretório que client_secret.json e execute-o:
from google_auth_oauthlib.flow import InstalledAppFlow

CLIENT_SECRETS_FILE = "client_secret.json"
SCOPES = ["https://www.googleapis.com/auth/adwords"]

def main():
    flow = InstalledAppFlow.from_client_secrets_file(
        CLIENT_SECRETS_FILE, SCOPES
    )
    credentials = flow.run_local_server(port=0)
    
    print("\nAuthorization Successful!\n")
    print(f"Refresh Token: {credentials.refresh_token}")

if __name__ == "__main__":
    main()

6. Configuração da biblioteca de cliente e das credenciais

O Google oferece bibliotecas de cliente oficialmente compatíveis que processam a autenticação, a serialização e a comunicação com os endpoints gRPC.

Idiomas compatíveis

  • Python:pip install google-ads
  • Java:disponível pelo Maven ou Gradle
  • PHP:composer require googleads/google-ads-php
  • .NET:Install-Package Google.Ads.GoogleAds
  • Ruby:gem install google-ads-googleads
  • Perl:cpanm Google::Ads::GoogleAds::Client

Arquivo de configuração (google-ads.yaml)

Crie um arquivo de configuração que contenha suas credenciais. Por padrão, o método de inicialização da biblioteca de cliente (por exemplo, GoogleAdsClient.load_from_storage()) vai pesquisar automaticamente google-ads.yaml em dois locais:

  1. O diretório de trabalho atual em que o script é executado.
  2. O diretório inicial do usuário (~ no Linux/macOS ou %HOMEPATH% no Windows).

Se você armazenar o arquivo em um local personalizado, poderá transmitir explicitamente o caminho para o método de inicialização (por exemplo, load_from_storage("path/to/google-ads.yaml")).

developer_token: "INSERT_YOUR_DEVELOPER_TOKEN_HERE"
client_id: "INSERT_YOUR_OAUTH2_CLIENT_ID_HERE"
client_secret: "INSERT_YOUR_OAUTH2_CLIENT_SECRET_HERE"
refresh_token: "INSERT_YOUR_OAUTH2_REFRESH_TOKEN_HERE"
login_customer_id: "INSERT_YOUR_MANAGER_ACCOUNT_ID_HERE"

7. Fazer sua primeira chamada de API

Para verificar a configuração de integração, execute um script de início rápido para buscar campanhas atuais na sua conta de teste.

Exemplo de script Python (quickstart.py)

import sys
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

def main(client, customer_id):
    ga_service = client.get_service("GoogleAdsService")
    query = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id
    """
    
    # Issues a search request
    stream = ga_service.search_stream(customer_id=customer_id, query=query)
    for batch in stream:
        for row in batch.results:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f"'{row.campaign.name}' was found."
            )

if __name__ == "__main__":
    # Initialize client from google-ads.yaml
    # By default, load_from_storage() searches for 'google-ads.yaml' in the
    # current working directory or the user's home directory (~). You can
    # also pass an explicit path: load_from_storage("path/to/google-ads.yaml")
    try:
        googleads_client = GoogleAdsClient.load_from_storage()
        # Replace with your test client account ID (without hyphens) from
        # Section 3, NOT your manager account ID (which belongs in
        # google-ads.yaml).
        test_customer_id = "1234567890" 
        main(googleads_client, test_customer_id)
    except GoogleAdsException as ex:
        print(
            f"Request failed with status {ex.error.code().name} and "
            f"includes the following errors:"
        )
        for error in ex.failure.errors:
            print(f"\tError with message '{error.message}'.")
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        sys.exit(1)

8. Práticas recomendadas e recursos

  • Registro:ative o registro detalhado na biblioteca de cliente para capturar IDs de solicitação e resposta (request-id), que são essenciais ao solicitar suporte do Google.
  • Tratamento de erros:implemente um tratamento de erros robusto para GoogleAdsException, gerenciando especificamente os limites de taxa (RESOURCE_TEMPORARILY_EXHAUSTED).
  • Documentação oficial: Documentação para desenvolvedores da API Google Ads
  • Bibliotecas de cliente e exemplos de código: Repositórios do Google Ads no GitHub
Anterior
Introdução
Avançar
Início rápido