Realizar sua primeira chamada de API

Neste guia, ensinaremos você a realizar sua primeira chamada de API, explicando etapa por etapa. Assim, você poderá aproveitar todas as vantagens da Google AdWords API.

O vídeo utiliza Java e Eclipse, mas você pode usar sua linguagem e biblioteca cliente preferidas. Os conceitos são semelhantes, e as instruções para todas as linguagens compatíveis estão descritas abaixo.

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

Depois de configurar o arquivo de configuração, você estará pronto para realizar chamadas com base na API.

Abordaremos seis etapas principais:

  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. Realizar sua primeira chamada de API.

Todas as etapas estão descritas nas seções abaixo.

Solicitar um token de desenvolvedor

Com um token de desenvolvedor do Google, seu aplicativo pode se conectar à Google AdWords API. Para solicitar um token de desenvolvedor, siga as etapas no Guia de inscrição (caso você ainda não tenha feito isso). Após se inscrever, você receberá um token de desenvolvedores com aprovação pendente.

Seu token de desenvolvedor pendente precisa ser aprovado para poder 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 você criou acima. Enquanto você está conectado ao Google AdWords usando sua conta de administrador de teste, todas as contas de cliente criadas se tornam contas de teste automaticamente.
  3. Crie algumas campanhas de teste na conta de cliente de teste, na interface da Web do Google AdWords.
  4. Anote o ID do cliente para a nova conta de cliente de teste e salve-o (você o adicionará ao seu arquivo de configuração mais tarde). O ID do cliente é exibido abaixo.

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

Adquirir uma biblioteca cliente

As bibliotecas cliente lidam com todas as chamadas de API de back-end para você e expõem objetos otimizados para trabalhar, 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 conforme desejado. Se esse não for o caso, nós ajudaremos você a configurar as bibliotecas cliente.

Clique na guia abaixo relacionada à 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 a seção "Primeiros passos" do arquivo README da biblioteca cliente PHP para fazer o download e instalar a biblioteca 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

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

Para permitir que seu aplicativo acesse a API, você precisa de um código 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 Credenciais do Google Developers Console.
  2. Na lista suspensa do projeto, escolha Criar um novo projeto, insira um nome para o projeto 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 tempo limitado, um token de atualização é usado para renovar automaticamente o acesso ao OAuth2.

Clique na guia relacionada à 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 o 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ê seguir as etapas, seu arquivo ads.properties terá tudo que é necessário para realizar chamadas de API de teste, além de 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ê seguir as etapas, seu arquivo app.config terá tudo que é necessário para realizar chamadas de API de teste, além de 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ê seguir as etapas, seu arquivo de configuração googleleads.yaml terá tudo que é necessário para realizar chamadas de API de teste, além de 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ê seguir as etapas, seu arquivo de configuração auth.ini terá tudo que é necessário para realizar chamadas de API de teste, além de conter valores semelhantes ao exemplo abaixo:
[...]
developerToken = 123axxxxxxxxxxxxxxxxxx
userAgent = Company_Name
clientCustomerId = 123-456-7890
client_id = xxxxxxxxxx.apps.googleusercontent.com
client_secret = zZxxxxxTxxxxxxxxxxx
refresh_token = 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ê seguir as etapas, seu arquivo de configuração adwords.properties terá tudo que é necessário para realizar chamadas de API de teste, além de 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ê seguir as etapas, seu arquivo de configuração adwords_api.yml terá tudo que é necessário para realizar chamadas de API de teste, além de 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
[...]

Realizar sua primeira chamada de API

Agora que seu arquivo de configuração e ambiente estão configurados, é hora de realizar 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 IDE, 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 realizar sua primeira chamada de API.

Nesta seção, revisaremos e explicaremos os componentes de configuração do aplicativo que usamos para realizar uma chamada com base na Google AdWords API.

Contas de teste x 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, pois elas não afetam seus anúncios ativos nem cobram sua conta. 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 da conta de teste lembra que você está usando uma conta de teste.

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 nós estamos usando uma biblioteca cliente, não entraremos em detalhes de back-end sobre como as chamadas de API são realizadas. Mas se você deseja saber mais sobre o SOAP, o OAuth2 e outros recursos que fazem essas chamadas funcionarem, consulte Estrutura da chamada de API.

Mesmo quando você usa as bibliotecas cliente, sempre há alguns componentes necessários. Embora já tenham sido configurados acima, agora iremos revisá-los e explicá-los um pouco mais.

Token de desenvolvedor

O token de desenvolvedor identifica seu aplicativo para a Google AdWords API. Somente os tokens aprovados podem se conectar à API para contas de produção do Google AdWords. Os tokens pendentes podem se conectar apenas às contas de teste. Depois que seu token é aprovado, você pode usar o mesmo token para as solicitações com base em todas as suas contas do Google AdWords, mesmo que elas não estejam vinculadas à conta de administrador associada ao token de desenvolvedor.

Consulte Como gerenciar contas para ver mais detalhes.

Código e chave secreta do cliente do OAuth2

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

Consulte Autenticação do OAuth2 para ver mais detalhes.

Tokens de atualização e acesso do OAuth2

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

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

Os tokens de acesso do OAuth2 expiram após um tempo limitado. Por esse motivo, as bibliotecas cliente usam o token de atualização do OAuth2 para tornar a gerar automaticamente o token de acesso do OAuth2.

Você criou o token de atualização nas etapas acima por meio de um utilitário na biblioteca 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 do cliente

O ID do cliente é o número da conta de cliente do Google AdWords que você deseja gerenciar por meio da API, que geralmente assume o formato 123-456-7890.

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

Consulte Casos de uso e amostras de código para ver mais informações.

Próximas etapas

Agora, você conhece todos os componentes necessários para o seu primeiro aplicativo de API. No próximo guia, Casos de uso e amostras de código, analisaremos como as bibliotecas cliente e as amostras de código ajudam você a usar a automação e a geração de relatórios personalizadas.

Enviar comentários sobre…

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