Plano de fundo

Antes de começar

  1. Peça ao representante da conta para configurar as permissões adequadas para as contas que seu aplicativo vai acessar.
  2. Se você não estiver familiarizado com os conceitos do Authorized Buyers, acesse a Central de Ajuda e faça testes com a interface do usuário. Se for preciso que o aplicativo faça lances em tempo real, leia a documentação do protocolo RTB.
  3. Visite o Console de APIs para configurar um novo projeto. Faça login na sua Conta do Google de desenvolvedor ou crie uma conta. Em seguida, você será solicitado a criar um projeto e aceitar alguns Termos de Serviço.

Contas principais e secundárias

Se você trabalha com uma estrutura de contas que contém contas mãe e filha, pode trabalhar de maneira mais eficaz ao entender como elas interagem. Confira a seguir um breve resumo:

Contas filhas

Um usuário com credenciais que concedem acesso a uma conta filha só pode visualizar e modificar os recursos associados à conta dele. Contas filhas não podem conferir nem modificar recursos que pertencem a outras contas mãe ou filha.

Contas de familiar responsável

Um usuário com credenciais que concedem acesso a uma conta pai pode ver e modificar recursos da conta pai, além de todas as contas filhas associadas. Para operações que listam todos os recursos, o usuário receberá uma resposta com os dados da conta e de todas as contas filhas. Para outros tipos de solicitações que segmentam recursos para vagas secundárias, uma conta mãe precisa especificar um parâmetro de caminho accountId para a conta filha, e não para a própria accountId.

Modelo de dados da API REST

Um recurso é uma entidade individual de dados com um identificador exclusivo. O recurso "Accounts" representa uma entrada da conta do Authorized Buyers e é a classe de dados raiz da API Ad Exchange Buyer. Os métodos da API operam em recursos de contas individuais e em coleções de recursos de contas.

Um recurso de contas inclui: um ID de conta, informações usadas na correspondência de cookie, locais do bidder, o URL para onde as solicitações de lance são enviadas e uma solicitação para especificar o máximo de consultas por segundo a serem enviadas pelo Ad Exchange.

Além do recurso de contas e da coleção, a API Ad Exchange Buyer define as seguintes estruturas de dados:

Local do bidder

Os locais do bidder são estruturas retornadas com recursos de contas para fornecer o URL ao qual o Ad Exchange deve enviar solicitações de lance e o número máximo de consultas por segundo que o Ad Exchange deve enviar. Confira um exemplo de local do bidder, expresso em JSON:

"bidderLocation": [
    {
      "url": "http://bid.url.com/bidder",
      "maximumQps": 1500
    }
  ],

Itens

Os itens fornecem uma lista de contas. Veja um exemplo de itens, expresso em JSON:

{
  "kind": "adexchangebuyer#accountsList",
  "items": [
    accounts Resource
  ]
}

Operações compatíveis

Você pode invocar três métodos diferentes em coleções e recursos na API Ad Exchange Buyer, conforme descrito na tabela a seguir. Todas as operações requerem autorização.

Operação Descrição Mapeamentos HTTP REST
list Lista todas as contas que podem ser acessadas pelo usuário autenticado no momento. GET em um URI de coleção.
get Acessa um recurso de contas específico. GET em um URI de recurso.
update Atualiza um recurso de contas específico. PUT em um URI de recurso, em que você transmite dados para o recurso atualizado.

Estilo de chamada

REST é um estilo de arquitetura de software que fornece uma abordagem conveniente e consistente para solicitar e modificar dados.

O termo REST é a sigla de "Representational State Transfer". No contexto das APIs do Google, ele se refere ao uso de verbos HTTP para recuperar e modificar representações de dados armazenados pelo Google.

Em um sistema RESTful, os recursos são mantidos em um armazenamento de dados. Um cliente envia uma solicitação para que uma ação específica seja executada no servidor, como a criação, recuperação, atualização ou exclusão de um recurso. Essa ação é executada e uma resposta é enviada, geralmente no formato de uma representação do recurso especificado.

Nas APIs RESTful do Google, o cliente especifica uma ação usando um verbo HTTP, como POST, GETPUT ou DELETE. Ele especifica um recurso por um URI globalmente exclusivo da seguinte forma:

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

Como todos os recursos da API têm URIs exclusivos acessíveis por HTTP, a REST permite o armazenamento em cache dos dados e é otimizada para funcionar na infraestrutura distribuída da Web.

As definições de método (em inglês) encontradas na documentação dos padrões HTTP 1.1 podem ser úteis. Nelas estão incluídas as especificações GET, POST, PUT e DELETE.

REST na API de comprador do Ad Exchange

As operações aceitas são mapeadas diretamente para verbos HTTP REST, conforme descrito em Operações da API.

O formato específico para URIs de API é:

https://www.googleapis.com/adexchangebuyer/v1.4/resourceID?parameters

em que resourceID é o identificador de um recurso de contas e parameters são os parâmetros a serem aplicados à consulta. Consulte os parâmetros de consulta padrão e a documentação de referência para mais detalhes.

O formato das extensões de caminho resourceID permite identificar o recurso em que você está operando no momento, por exemplo:

https://www.googleapis.com/adexchangebuyer/v1.4/accounts
https://www.googleapis.com/adexchangebuyer/v1.4/accounts/id

O conjunto completo de URIs usados para cada operação compatível na API está resumido na documentação de referência.

Veja um exemplo de como isso funciona na API de comprador do Ad Exchange.

Consulte a lista de contas do usuário autenticado:

GET https://www.googleapis.com/adexchangebuyer/v1.4/accounts

Formato de dados

JSON

JSON (JavaScript Object Notation) é um formato de dados comum e independente de linguagem que oferece uma representação de texto simples das estruturas de dados arbitrárias. Para mais informações, acesse json.org (em inglês).