Fazer sua primeira chamada de API

Neste guia, mostraremos como fazer sua primeira chamada de API, explicando etapa por etapa. Assim, você poderá aproveitar todos os benefícios da Google AdWords API.

O vídeo usa Java e Eclipse, mas você pode usar a biblioteca de linguagem e de cliente que preferir. Os conceitos são semelhantes, e fornecemos instruções abaixo para todas as linguagens compatíveis.

Visão geral do processo

Para configurar o acesso à API, você precisa adquirir algumas credenciais de autenticação necessárias, criar algumas contas de teste e adicionar os detalhes da autenticação e da conta a um arquivo de configuração da sua biblioteca de cliente.

Você poderá fazer chamadas de API assim que o arquivo de configuração tiver sido configurado. Veja a seguir as etapas desse processo:

  1. Solicitar um token de desenvolvedor.
  2. Criar contas de teste.
  3. Adquirir uma biblioteca cliente.
  4. Configurar a autenticação por meio do OAuth2.
  5. Adquirir um token de atualização do OAuth2 e configurar seu cliente.
  6. Fazer sua primeira chamada de API.

Solicitar um token de desenvolvedor

Um token de desenvolvedor do Google permite que seu aplicativo se conecte à Google AdWords API. Conclua as etapas descritas no guia de inscrição para receber um token de desenvolvedor, caso ainda não tenha feito isso. Após se inscrever, você receberá um token de desenvolvedor com aprovação pendente.

Seu token de desenvolvedor pendente precisa ser aprovado para ser usado com as contas de produção do Google AdWords.

Criar contas de teste

Siga as etapas abaixo para criar uma conta de administrador de teste, uma conta de cliente de teste e algumas campanhas para preencher a conta de cliente de teste.

  1. Acesse a página de contas de administrador do Google AdWords e crie uma conta de administrador de teste.
  2. Use a interface da Web do Google AdWords para criar uma conta de cliente de teste na conta de administrador de teste que criou. Enquanto você estiver conectado ao Google AdWords usando sua conta de administrador de teste, todas as contas de cliente se tornarão contas de teste automaticamente.
  3. Crie algumas campanhas fictícias na conta de cliente de teste na IU do Google AdWords.
  4. Anote o ID de cliente para a nova conta de cliente de teste e salve-o. Você o adicionará ao seu arquivo de configuração depois.

Use o token de desenvolvedor da sua conta de administrador de produção ao fazer solicitações na conta de administrador de teste. Mesmo que o token ainda não tenha sido aprovado, ele continuará funcionando em contas de teste, incluindo naquelas que você acabou de criar.

Adquirir uma biblioteca de cliente

As bibliotecas de cliente lidam com todas as chamadas de API de back-end e mostram quais objetos otimizados podem ser usados, incluindo amostras de código para praticamente todas as tarefas de API comuns.

Se você é um desenvolvedor experiente, provavelmente já tem seu ambiente de desenvolvimento. Se esse não for o caso, ajudaremos você a configurar as bibliotecas de cliente.

Clique abaixo na guia da linguagem que você está usando e siga as instruções.

Java

  1. Consulte a seção "Primeiros passos" do arquivo README da biblioteca cliente Java no GitHub para fazer o download e instalar a biblioteca cliente da Google AdWords API para Java.
  2. Volte a esta página antes de seguir as etapas do OAuth2. Na etapa abaixo, configuraremos as credenciais do OAuth2.

.NET

  1. Consulte a seção "Primeiros passos" do arquivo README da biblioteca cliente .NET para fazer o download e instalar a biblioteca cliente da Google AdWords API para CSharp ou Visual Basic.
  2. Volte a esta página antes de seguir as etapas do OAuth2. Na etapa abaixo, configuraremos as credenciais do OAuth2.

Python

  1. Consulte a seção "Primeiros passos" do arquivo README da biblioteca cliente Python para fazer o download e instalar a biblioteca cliente da Google AdWords API para Python.
  2. Volte a esta página antes de seguir as etapas do OAuth2. Na etapa abaixo, configuraremos as credenciais do OAuth2.

PHP

  1. Consulte os Primeiros passos para saber como fazer o download e instalar a biblioteca de cliente da Google AdWords API para PHP.
  2. Volte a esta página antes de seguir as etapas do OAuth2. Na etapa abaixo, configuraremos as credenciais do OAuth2.

Perl

  1. Consulte a seção "Primeiros passos" do arquivo README da biblioteca cliente Perl para fazer o download e instalar a biblioteca cliente da Google AdWords API para Perl.
  2. Volte a esta página antes de seguir as etapas do OAuth2. Na etapa abaixo, configuraremos as credenciais do OAuth2.

Ruby

  1. Consulte a seção "Primeiros passos" do arquivo README da biblioteca cliente Ruby para fazer o download e instalar a biblioteca cliente da Google AdWords API para Ruby.
  2. Volte a esta página antes de seguir as etapas do OAuth2. Na etapa abaixo, configuraremos as credenciais do OAuth2.

Configurar a autenticação do OAuth2

O aplicativo precisa acessar os dados do usuário e se comunicar com seus outros serviços do Google. Com a autenticação por meio do OAuth2, seu aplicativo pode funcionar em nome da sua conta.

Para permitir que o aplicativo acesse a API, você precisa de um ID e uma chave secreta do cliente do OAuth2.

  1. Faça login com as credenciais da sua conta de administrador e abra a página de credenciais do Console de APIs do Google.
  2. Na lista suspensa do projeto, escolha Criar um novo projeto, insira um nome para ele e clique em Criar.
  3. Selecione Criar credenciais e escolha Código do cliente do OAuth.
  4. Talvez você precise definir um nome de produto na tela de consentimento. Se esse for o caso, clique em Configurar tela de consentimento, insira as informações solicitadas e clique em Salvar para retornar à tela Credenciais.
  5. Em Tipo de aplicativo, escolha Outro para esse tutorial. Insira um nome no espaço disponível.
  6. Clique em Criar. O código e a chave secreta do cliente do OAuth2 são exibidos. Copie e salve esses itens. Você os adicionará ao seu arquivo de configuração na próxima etapa.

Adquirir um token de atualização do OAuth2 e configurar seu cliente

Como o acesso ao OAuth2 expira após um período, um token de atualização é usado para renovar esse acesso automaticamente.

Clique na guia da linguagem de programação que você está usando e siga as instruções para gerar um token de atualização do OAuth2 e configurar o arquivo de configuração para seu cliente.

Java

  1. Siga estas instruções no GitHub para adquirir um token de atualização do OAuth2 e configurar a biblioteca cliente.
  2. Ao concluir, volte a esta página. Depois que você concluir essas etapas, seu arquivo ads.properties terá o necessário para fazer chamadas de API de teste e conterá valores semelhantes ao exemplo abaixo:
[...]
api.adwords.developerToken=123axxxxxxxxxxxxxxxxxx
api.adwords.clientId=xxxxxxxxxx.apps.googleusercontent.com
api.adwords.clientSecret=zZxxxxxTxxxxxxxxxxx
api.adwords.clientCustomerId=123-456-7890
api.adwords.refreshToken=1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
api.adwords.userAgent=Company_Name
[...]

.NET

  1. Siga estas instruções no GitHub para adquirir um token de atualização do OAuth2 e configurar a biblioteca cliente.
  2. Ao concluir, volte a esta página. Depois que você concluir essas etapas, o arquivo de configuração do seu aplicativo terá o necessário para fazer chamadas de API de teste e conterá valores semelhantes ao exemplo abaixo:
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="AdWordsApi"
        type="System.Configuration.DictionarySectionHandler"/>
  </configSections>
  <AdWordsApi>
    <!-- Settings specific to AdWords API.-->
    <add key="UserAgent" value="My AdWords API application"/>
    <add key="DeveloperToken" value="xxxxxxxxxxxxxxxxxxxxxx"/>
    <add key="ClientCustomerId" value="123-456-7890"/>

    <!-- OAuth2 configuration -->
    <add key="AuthorizationMethod" value="OAuth2" />
    <add key="OAuth2ClientId" value="xxxxxxxxxx.apps.googleusercontent.com" />
    <add key="OAuth2ClientSecret" value="zZxxxxxTxxxxxxxxxxx" />
    <add key="OAuth2Mode" value="APPLICATION" />
    <add key="OAuth2RefreshToken" value="1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxx" />
  </AdWordsApi>
</configuration>

Python

  1. Siga estas instruções no GitHub para adquirir um token de atualização do OAuth2 e configurar a biblioteca cliente.
  2. Ao concluir, volte a esta página. Depois que você concluir essas etapas, seu arquivo de configuração googleads.yaml terá o necessário para fazer chamadas de API de teste e conterá valores semelhantes ao exemplo abaixo:
adwords:
  developer_token: 123axxxxxxxxxxxxxxxxxx
  user_agent: Company_Name
  client_customer_id: 123-456-7890
  client_id: xxxxxxxxxx.apps.googleusercontent.com
  client_secret: zZxxxxxTxxxxxxxxxxx
  refresh_token: 1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
[...]

PHP

  1. Siga estas instruções no GitHub para adquirir um token de atualização do OAuth2 e configurar a biblioteca cliente.
  2. Ao concluir, volte a esta página. Depois que você concluir essas etapas, o arquivo de configuração adsapi_php.ini terá o necessário para fazer chamadas de API de teste e conterá valores semelhantes ao exemplo abaixo:
    developerToken = "123axxxxxxxxxxxxxxxxxx"
    clientCustomerId = "123-456-7890"
    
    userAgent = "Company_Name"
    
    clientId = "xxxxxxxxxx.apps.googleusercontent.com"
    clientSecret = "zZxxxxxTxxxxxxxxxxx"
    refreshToken = "1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx"
    

Perl

  1. Siga estas instruções no GitHub para adquirir um token de atualização do OAuth2 e configurar a biblioteca cliente.
  2. Ao concluir, volte a esta página. Depois que você concluir essas etapas, o arquivo de configuração adwords.properties terá o necessário para fazer chamadas de API de teste e conterá valores semelhantes ao exemplo abaixo:
[...]
userAgent = Company_Name
developerToken=123axxxxxxxxxxxxxxxxxx
clientId=123-456-7890
oAuth2ClientId=xxxxxxxxxx.apps.googleusercontent.com
oAuth2ClientSecret=zZxxxxxTxxxxxxxxxxx
oAuth2RefreshToken=1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
[...]

Ruby

  1. Siga estas instruções no GitHub para adquirir um token de atualização do OAuth2 e configurar a biblioteca cliente.
  2. Ao concluir, volte a esta página. Depois que você concluir essas etapas, seu arquivo de configuração adwords_api.yml terá o necessário para fazer chamadas de API de teste e conterá valores semelhantes ao exemplo abaixo:
[...]
:oauth2_client_id: xxxxxxxxxx.apps.googleusercontent.com
:oauth2_client_secret: zZxxxxxTxxxxxxxxxxx
:refresh_token: 1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
:developer_token: 123axxxxxxxxxxxxxxxxxx
:client_customer_id: 123-456-7890
:user_agent: Company_Name
[...]

Fazer sua primeira chamada de API

Agora que o arquivo de configuração e o ambiente estão configurados, é hora de fazer sua primeira chamada de API:

Java

  1. No seu IDE, abra e execute o GetCampaigns.java.
  2. O console deve imprimir uma lista de campanhas de teste que você adicionou à sua conta de teste acima.

.NET

  1. No seu ambiente de desenvolvimento integrado, abra e execute GetCampaigns.cs ou GetCampaigns.vb.
  2. O console deve imprimir uma lista de campanhas de teste que você adicionou à sua conta de teste acima.

Python

  1. No seu IDE, abra e execute o get_campaigns.py.
  2. O console deve imprimir uma lista de campanhas de teste que você adicionou à sua conta de teste acima.

PHP

  1. No seu IDE, abra e execute o GetCampaigns.php.
  2. O console deve imprimir uma lista de campanhas de teste que você adicionou à sua conta de teste acima.

Perl

  1. No seu IDE, abra e execute o get_campaigns.pl.
  2. O console deve imprimir uma lista de campanhas de teste que você adicionou à sua conta de teste acima.

Ruby

  1. Na linha de comando, execute o get_campaigns.rb digitando:
    ruby get_campaigns.rb
  2. O console deve imprimir uma lista de campanhas de teste que você adicionou à sua conta de teste acima.

Parabéns! Você realizou sua primeira chamada da Google AdWords API.

Nós abordamos muitos assuntos nessa seção. Na próxima seção, revisaremos e explicaremos alguns dos componentes de configuração com os quais trabalhamos aqui.

Como analisar os componentes de configuração

Na seção anterior, ajudamos você a fazer sua primeira chamada de API.

Nesta seção, explicaremos os componentes de configuração do aplicativo que serão usados para fazer uma chamada na Google AdWords API.

Contas de teste e de produção

Na seção anterior, você criou uma conta de administrador de teste e uma conta de cliente de teste.

As contas de teste são uma maneira útil de testar a API porque elas não afetam seus anúncios ativos nem são passíveis de cobrança. Essas contas também são ideais para fazer simulações na interface da Web do Google AdWords sem que haja consequências.

Quando você está conectado à interface da Web do Google AdWords, o rótulo vermelho lembra que uma conta de teste está sendo usada.

Como as contas de teste não veiculam anúncios reais, os dados de custo ou impressões geralmente são zerados nos relatórios ou chamadas de API.

Para ver mais informações sobre as contas de teste e produção e saber como configurar uma hierarquia de contas, consulte Como gerenciar contas.

Componentes de configuração

Como estamos usando uma biblioteca de cliente, não falaremos sobre como as chamadas de API são realizadas no back-end. No entanto, se você quiser saber mais sobre o SOAP, o OAuth2 e os outros recursos que fazem essas chamadas funcionarem, consulte Estrutura da chamada de API.

Mesmo quando você usa as bibliotecas de cliente, sempre há alguns componentes necessários. Embora eles já tenham sido configurados acima, falaremos um pouco mais sobre cada um.

Token de desenvolvedor

O token de desenvolvedor identifica seu aplicativo na Google AdWords API. Somente tokens aprovados podem se conectar à API para contas de produção do Google AdWords. Já os pendentes podem se conectar apenas às contas de teste. Depois que seu token for aprovado, você poderá usá-lo em solicitações de todas as suas contas do Google AdWords, mesmo que elas não estejam vinculadas à conta de administrador associada a esse token.

Para recuperar seu token de desenvolvedor, faça login na sua conta de administrador e acesse a página Central de API do AdWords (ícone de ferramenta > CONFIGURAÇÃO > Central de API do AdWords).

Consulte Como gerenciar contas para ver mais detalhes.

ID e chave secreta do cliente do OAuth2

O ID e a chave secreta do cliente mapeiam seu aplicativo cliente para um projeto no Google Developers Console e são usados na autenticação do OAuth2, que permite que o aplicativo funcione em nome da sua conta.

Consulte Autenticação do OAuth2 para mais detalhes.

Tokens de atualização e de acesso do OAuth2

Antes de acessar os dados particulares usando a API, primeiro seu aplicativo precisa adquirir um token de acesso do OAuth2 que conceda acesso à API.

Se você estiver usando as bibliotecas de cliente, o token de acesso do OAuth2 será disponibilizado automaticamente. Caso contrário, acesse o guia Estrutura da chamada de API para ver um exemplo de chamada de API e saber como gerar um token de acesso.

Os tokens de acesso do OAuth2 expiram após um período. Por esse motivo, as bibliotecas de cliente usam o token de atualização do OAuth2 para gerar um novo token de acesso de forma automática.

Você criou o token de atualização nas etapas acima por meio de um utilitário na biblioteca de cliente.

Para ver mais informações sobre como usar o OAuth2 com as APIs do Google, consulte as documentações Autenticação do OAuth2 e Plataforma de identidade do OAuth2.

ID de cliente

O ID de cliente é o número da conta do cliente do Google AdWords que você quer gerenciar por meio da API. Ele normalmente tem o formato 123-456-7890.

Você também tem a opção de remover o ID de cliente do arquivo de configuração e defini-lo de modo programático. Depois que seu token de desenvolvedor for aprovado, será possível usar um ID de cliente de uma conta de produção, em vez de uma conta de teste.

Próximas etapas

Agora você conhece todos os componentes necessários para seu primeiro aplicativo de API. No próximo guia, Estrutura de código, veremos como as bibliotecas de cliente e as amostras de código podem ajudar você a gerar relatórios personalizados e automatizar os processos.

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.