Primeiros passos

Este documento se destina a desenvolvedores que desejam usar a AdSense Management API para receber informações sobre sua conta do Google AdSense. Ele pressupõe que você esteja familiarizado com conceitos de programação da Web e formatos de dados da Web.

Índice

Antes de começar

Obtenha uma conta do Google AdSense

Você precisa de uma conta do Google AdSense com a finalidade de teste. Se você já tiver uma conta de teste, então está tudo pronto. Você poderá visitar a interface do usuário do Google AdSense para configurar, editar ou visualizar os dados de teste.

Familiarize-se com o Google AdSense

Se você não tem familiaridade com os conceitos do Google AdSense, leia as informações introdutórias sobre o Google AdSense e teste a interface do usuário antes de começar a codificar.

Registre seu aplicativo

Para usar a AdSense Management API, é necessário registrar o aplicativo que você está desenvolvendo com o Google:

  1. Vá até o Console de APIs.
  2. Faça login em sua Conta do Google ou crie uma conta.
  3. Crie um novo projeto.
  4. Em seu projeto recém-criado, clique no botão “Ativar” na AdSense Management API.

Para aplicativos OAuth 2.0, siga as etapas adicionais descritas em Registro de seu aplicativo com o Google.

Note: A Conta do Google usada para registro deve ser sua conta de desenvolvedor, ou seja, a conta que você deseja que os usuários de seu aplicativo vejam como o desenvolvedor do aplicativo. Essa conta não precisa estar vinculada a um login do Google AdSense, já que os usuários concederão acesso a suas próprias contas ao usar o aplicativo.

Noções básicas sobre a AdSense Management API

Conceitos básicos

A AdSense Management API foi desenvolvida com base em alguns conceitos básicos do Google AdSense:

  • Clientes de anúncios: os clientes de anúncios representam uma associação entre uma conta do Google AdSense e um produto do Google AdSense, como anúncios de conteúdo ou anúncios da Rede de Pesquisa. Uma conta do Google AdSense pode ter um ou vários clientes de anúncios.
  • Blocos de anúncios: os blocos de anúncios são marcadores de posição para anúncios configurados pelo usuário, que definem algumas propriedades dos anúncios exibidos (como tamanho e forma).
  • Canais: os canais são ferramentas que permitem acompanhar o desempenho de um subconjunto de seus blocos de anúncios. Há dois tipos de canais: critérios de URL e canais personalizados. O primeiro permite que você acompanhe o desempenho de um domínio ou página específica, enquanto o último ajuda a acompanhar o desempenho em grupos de blocos de anúncios específicos selecionados pelo usuário.
  • Relatórios: os relatórios oferecem informações sobre seus ganhos, bem como o que causa impacto nesses ganhos. Eles podem ser gerados em uma conta inteira ou em um subconjunto de blocos de anúncios por meio do uso de canais.

Operações compatíveis

As operações aceitas no momento pela API estão descritas na tabela abaixo.

Operação Descrição Mapeamentos de HTTP REST
listar Lista todos os recursos em um conjunto. GET em um URI de coleta.
receber Recebe um recurso específico. GET em um URI de recurso.
gerar Gere um conjunto de resultados com base em um recurso especificado. Usada apenas para relatórios. GET/POST em um URI de coleta, em que você transmite o recurso como uma definição para a geração.

Todas as operações exigem autenticação.

Estilo de chamada

REST é um estilo de arquitetura de software que fornece uma abordagem conveniente e consistente para a solicitação e modificação de dados.

O termo REST significa “Transferência de estado de representação”. No contexto das APIs do Google, ele se refere ao uso de verbos HTTP para obter e modificar representações de dados armazenados pelo Google.

Em um sistema RESTful, recursos são armazenados em um armazenamento de dados. Um cliente envia uma solicitação para o servidor realizar determinada ação (como criar, obter, atualizar ou excluir um recurso) e o servidor realiza a ação e envia uma resposta, geralmente na forma de uma representação do recurso especificado.

Nas RESTful APIs do Google, o cliente especifica uma ação usando um verbo HTTP, como POST, GET, PUT ou DELETE. Ele especifica um recurso por meio de um URI único globalmente no seguinte formato:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

Como todos os recursos de API possuem URIs acessíveis por HTTP exclusivos, REST permite o cache de dados e é otimizado para funcionar com a infraestrutura distribuída da Web.

Para obter mais informações sobre REST, os documentos de terceiros a seguir podem ser úteis:


REST na AdSense Management API

As operações aceitas mapeiam diretamente para verbos HTTP REST, conforme descrito em Operações da AdSense Management API.

O formato específico para URIs da AdSense Management API é:

https://www.googleapis.com/adsense/v1.2/reference/resourceID?parameters

onde resourceID é o identificador de um cliente de anúncios, bloco de anúncios, critérios de url, canal personalizado ou conjunto de relatórios, e parameters são os parâmetros a serem aplicados à consulta.

O formato das extensões de caminho resourceID permite identificar o recurso em operação no momento, por exemplo:

https://www.googleapis.com/adsense/v1.2/adclients
https://www.googleapis.com/adsense/v1.2/adclients/adClientId
https://www.googleapis.com/adsense/v1.2/adclients/adClientId/adunits
https://www.googleapis.com/adsense/v1.2/adclients/adClientId/adunits/adUnitId
https://www.googleapis.com/adsense/v1.2/adclients/adClientId/urlchannels
...

O conjunto completo de URIs usados para cada operação suportada na API é resumido no documento Referência da AdSense Management API .

Veja alguns exemplos de como isso funciona na AdSense Management API.

Listar clientes de anúncios:

GET https://www.googleapis.com/adsense/v1.2/adclients/

Listar blocos de anúncios no cliente de anúncios ca-pub-1234567890123456:

GET https://www.googleapis.com/adsense/v1.2/adClients/ca-pub-1234567890123456/adunits

Formato de dados

JSON (Notação de Objetos JavaScript) é um formato de dados comum e independente do idioma, que fornece uma representação de texto simples de estruturas de dados arbitrários. Para mais informações, acesse json.org.

Como realizar solicitações

Como autorizar solicitações

É necessário que toda a solicitação que seu aplicativo envia para a AdSense Management API inclua um token de autorização. O token também identifica seu aplicativo para o Google.

Sobre protocolos de autorização

Recomendamos usar o OAuth 2.0 para autorizar solicitações.

Se seu aplicativo tiver determinados requisitos de autorização incomuns, como login ao mesmo tempo que a solicitação de acesso aos dados (híbrido) ou delegação de autoridade (2LO) em todo o domínio, você não poderá usar os tokens do OAuth 2.0 no momento. Nesses casos, é necessário que você use os tokens do OAuth 1.0 e uma chave da API. Você pode encontrar sua chave da API do aplicativo no console das APIs do Google, na seção "Acesso simples à API" do painel de acesso à API.

Solicitações de autorização com o OAuth 2.0

Todas as solicitações para AdSense Management API deverão ser autorizadas por um usuário autenticado.

Os detalhes do processo de autorização, ou "fluxo", para o OAuth 2.0 variam um pouco dependendo do tipo de aplicativo que você está criando. Os processos gerais a seguir se aplicam a todos os tipos de aplicativo:

  1. Ao criar seu aplicativo, você o registra no Google. Em seguida, o Google fornece informações que serão usadas posteriormente, como um ID de cliente e um segredo de cliente.
  2. Ative a AdSense Management API no painel de serviços do Console das APIs do Google. Se ele não estiver listado no Console, ignore esta etapa.
  3. Quando seu aplicativo precisar de acesso aos dados do usuário, ele solicitará ao Google um determinado escopo do acesso.
  4. O Google exibirá uma caixa de diálogo do OAuth para o usuário, perguntando se ele autoriza que seu aplicativo solicite alguns dados.
  5. Se o usuário aprovar, o Google concederá a seu aplicativo um token de acesso de curto prazo.
  6. Seu aplicativo solicita dados do usuário, anexando o token de acesso à solicitação.
  7. Se o Google determinar que sua solicitação e o token são válidos, ele retornará os dados solicitados.

Alguns fluxos incluem etapas adicionais, como usar tokens de atualização para adquirir novos tokens de acesso. Para informações detalhadas sobre fluxos de vários tipos de aplicativo, veja a documentação do OAuth 2.0 do Google.

Veja as informações de escopo do OAuth 2.0 para a AdSense Management API:

Escopo Significado
https://www.googleapis.com/auth/adsense Acesso de leitura/gravação de dados do Google AdSense.
https://www.googleapis.com/auth/adsense.readonly Acesso somente de leitura de dados do Google AdSense.

Para solicitar acesso usando o OAuth 2.0, seu aplicativo precisará de informações do escopo, bem como informações fornecidas pelo Google durante o registro do aplicativo (como o ID e/ou o segredo do cliente).

Dica: as bibliotecas cliente das APIs do Google podem tratar parte do processo de autorização para você. Elas estão disponíveis para uma série de linguagens de programação. Acesse a página Bibliotecas e exemplos para mais detalhes.

Como realizar uma solicitação

A etapa final é fazer a solicitação de API. Se você não estiver usando uma biblioteca cliente, acesse a documentação de referência.

Se você estiver usando as bibliotecas cliente, esta tarefa é muito mais fácil. Acesse Exemplos e bibliotecas para um guia completo de como fazer sua primeira solicitação com a biblioteca cliente do Java, Python, PHP ou JavaScript.

Enviar comentários sobre…

AdSense Management API
AdSense Management API