Seu primeiro aplicativo: pré-requisitos

Antes de começar a codificar seu primeiro aplicativo cliente, há algumas coisas que você precisa fazer, se ainda não tiver feito.

Criar uma Conta do Google e receber permissões do Search Ads 360

Para usar a API Search Ads 360, você precisa de uma Conta do Google e das permissões adequadas concedidas a essa conta pelo Search Ads 360:

  1. Se você ainda não tem uma Conta do Google, crie uma.

  2. Peça a um administrador de agência do Search Ads 360 para criar um usuário do Search Ads 360 para sua Conta do Google.

    Para fazer o download de relatórios, você precisa de permissão de visualização dos anunciantes com quem vai trabalhar.

    Para adicionar ou editar conversões, você precisa ter permissão de edição para os anunciantes com que vai trabalhar. Em uma configuração compartilhada do Floodlight, é necessário ter permissão de edição para cada anunciante filho em que você quer fazer o upload de conversões. Não é preciso acessar o anunciante pai nem os anunciantes filhos de que você não está fazendo upload de conversões. Se você usa IDs de clique para atribuir conversões a visitas, verifique se tem acesso para editar ao anunciante que gerou o ID de clique. Se você especificar um ID de clique de um anunciante que não tem acesso para editar, a solicitação não vai ser bem-sucedida.

    O administrador da agência pode configurar sua conta como um usuário do anunciante com acesso a anunciantes específicos ou configurar sua conta com um nível mais alto de acesso, como Usuário da agência, com acesso a todos os anunciantes da agência.

Ativar o serviço de conversão da API

Se você quiser fazer o upload de dados sobre conversões, um usuário do Search Ads 360 com privilégios de gerente de agência precisará fazer login na interface do Search Ads 360 e ativar o serviço de conversão da API. Consulte a Central de Ajuda do Search Ads 360 para ver instruções.

Criar um projeto do Console de APIs do Google e credenciais OAuth para seu cliente

  1. Inicie a ferramenta de configuração do Console de APIs do Google.
    A ferramenta de configuração orienta você na criação de um projeto (ou no uso de um projeto existente), na ativação da API Search Ads 360 e na criação de credenciais OAuth 2.0.
  2. Na página Registrar seu aplicativo, selecione um projeto atual ou clique em Criar um projeto. Em seguida, clique em Continuar.
  3. Depois que o Google API Console ativar a API Search Ads 360, clique no botão Acessar credenciais.
  4. Na página Criar credenciais, insira as seguintes informações:
    • Qual API você está usando?: Search Ads 360 API
    • Quais dados você vai acessar? Dados do usuário
  5. Clique no botão Próxima.

    Agora, a ferramenta de configuração ajuda a criar um ID do cliente do OAuth 2.0.

  6. Siga as etapas restantes na ferramenta de configuração.

Instalar sa360Api.py

O Search Ads 360 oferece um script de utilitário para facilitar o processo de configuração da autorização. Você também pode usar esse script para enviar e receber dados no formato JSON, se quiser tentar enviar e receber dados antes de projetar e escrever um aplicativo completo. É possível copiar muitos dos exemplos JSON neste site de documentação e inseri-los diretamente no script.

Para instalar o script:

  1. Instale o Python 2.7.
    O script não funciona com o Python 3.x.
  2. Instale o cURL.
  3. Faça o download do arquivo sa360Api.zip.
  4. Extraia sa360Api.py de sa360Api.zip.
  5. Torne sa360Api.py executável.

Aprender os fundamentos da REST

Há duas maneiras de chamar a API:

Se você não quiser usar as bibliotecas de cliente, precisará entender os fundamentos da REST.

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

O termo REST é a abreviação de "Representational State Transfer (Transferência de Estado Representacional)". 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, uma ação é especificada no cliente usando um verbo HTTP como POST, GET, PUT ou DELETE. Um recurso é definido por meio de um URI global exclusivo no seguinte formato:

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 Search Ads 360

As operações da API Search Ads 360 são mapeadas diretamente para os verbos HTTP REST.

O formato específico dos URIs da API Search Ads 360 é:

https://www.googleapis.com/doubleclicksearch/v2/resourcePath?parameters

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

Conhecer os fundamentos do JSON

Se usar REST, você precisará usar o formato JSON para os corpos das solicitações. É possível especificar que as respostas sejam no formato JSON ou CSV.

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