API de gerenciamento – autorização

Este guia descreve como um aplicativo autoriza solicitações à API de gerenciamento.

Autorização de solicitações

Para poder visualizar as informações das suas contas no website do Google Analytics, os usuários precisam fazer login nas suas respectivas Contas do Google. De maneira semelhante, ao acessar seu aplicativo pela primeira vez, os usuários precisam autorizá-lo a acessar os dados deles.

Todas as solicitações enviadas pelo seu aplicativo à Google Analytics API precisam incluir um token de autorização. O token também identifica seu aplicativo para o Google.

Sobre os protocolos de autorização

O aplicativo deve obrigatoriamente usar o OAuth 2.0 para autorizar solicitações. Não há mais protocolos de autorização compatíveis. Se seu aplicativo usa o login do Google+, alguns aspectos da autorização são preenchidos para você.

Como autorizar solicitações com o OAuth 2.0

Todas as solicitações à Google Analytics API precisam ser autorizadas por um usuário autenticado.

Os detalhes do processo (ou do "fluxo") de autorização do OAuth 2.0 variam um pouco dependendo do tipo de aplicativo que você está criando. O processo geral a seguir se aplica a todos os tipos de aplicativo:

  1. Ao criar seu aplicativo, registre-o usando o console de APIs do Google. Em seguida, o Google fornecerá informações que serão necessárias posteriormente, como um ID e uma chave secreta do cliente.
  2. Ative a Google Analytics API no console de APIs do Google. Se ela não estiver listada no console de APIs, pule essa 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 exibe uma tela de consentimento ao usuário, pedindo autorização para que seu aplicativo solicite alguns dados dele.
  5. Se o usuário aprovar, o Google concederá ao seu aplicativo um token de acesso de curto prazo.
  6. Seu aplicativo solicita os 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 retorna 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 os fluxos de vários tipos de aplicativos, consulte a documentação do OAuth 2.0 do Google.

Veja as informações de escopo do OAuth 2.0 para a Google Analytics API:

Escopo Significado
https://www.googleapis.com/auth/analytics.readonly Acesso somente leitura à Google Analytics API.
https://www.googleapis.com/auth/analytics.edit Edita as entidades de gerenciamento do Google Analytics.
https://www.googleapis.com/auth/analytics.manage.users Visualiza e gerencia permissões de usuário para as contas do Google Analytics.
https://www.googleapis.com/auth/analytics.manage.users.readonly Visualiza as permissões de usuário do Google Analytics.

Para solicitar acesso usando o OAuth 2.0, seu aplicativo precisa de informações do escopo, bem como informações fornecidas pelo Google durante o registro do aplicativo (como o ID de cliente e a chave secreta do cliente).

Dica: As bibliotecas cliente de APIs do Google cuidam de 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 de bibliotecas e exemplos para mais detalhes.

Fluxos comuns do OAuth 2.0

Veja a seguir casos de uso comuns para fluxos específicos do OAuth 2.0:

Servidor da Web

Este fluxo é útil para o acesso automatizado, off-line ou programado aos dados do Google Analytics de um usuário.

Exemplo:

  • Atualização automática de painéis do usuário com os dados mais recentes do Google Analytics.

Lado do cliente

Esse fluxo é ideal para aplicativos quando os usuários interagem diretamente com o aplicativo para acessar seus próprios dados do Google Analytics em um navegador. Ele elimina a necessidade de recursos do lado do servidor, mas torna os relatórios automatizados, off-line ou programados inviáveis.

Exemplo:

Aplicativos instalados

Esse fluxo é destinado a aplicativos distribuídos como um pacote e instalados pelo usuário. Para concluir o fluxo de autenticação, é necessário que o aplicativo ou o usuário tenha acesso a um navegador.

Exemplos:

  • Um widget para computador em um PC ou Mac.
  • Um plug-in para um sistema de gerenciamento de conteúdo. A vantagem desse fluxo em relação ao fluxo de servidor da Web ou do lado do cliente é que um único projeto do console de APIs pode ser usado para seu aplicativo. Isso permite a geração de relatórios consolidados e uma instalação mais simples para os usuários.

Contas de serviço

As contas de serviço são úteis para o acesso automatizado, off-line ou programado aos dados do Google Analytics para sua própria conta. Por exemplo, para criar um painel ao vivo dos seus próprios dados do Google Analytics e compartilhá-lo com outros usuários.

Para começar a usar a Google Analytics API, primeiro é necessário usar a ferramenta de configuração, que orienta você na criação de um projeto no console de APIs do Google, na ativação da API e na criação de credenciais.

Para configurar uma nova conta de serviço:

  1. Clique em Criar credenciais > Chave da conta de serviço.
  2. Escolha se você deseja fazer o download da chave pública/privada da conta de serviço como um arquivo P12 padrão ou como um arquivo JSON, que pode ser carregado por uma biblioteca cliente da API do Google.

Seu novo par de chave pública/privada é gerado, e o download dele é feito na sua máquina. Essa é a única cópia da chave. Você é responsável por armazená-la com segurança.

Solução de problemas

Ocorre uma falha na autorização nestas situações:

  • O código de status 401 será exibido se seu access_token estiver expirado ou se você estiver usando o escopo errado para a API.

  • O código de status 403 é exibido se o usuário autorizado não tem acesso à Vista (perfil). Verifique se você está autorizado com o usuário correto e se ele tem a Vista (perfil) que selecionou.

OAuth 2.0 Playground

Com essa ferramenta, você pode percorrer o fluxo de autorização inteiro por meio de uma interface da Web. A ferramenta também exibe todos os cabeçalhos de solicitação HTTP necessários para fazer uma consulta autorizada. Se você está com dificuldade para conseguir autorização para trabalhar no seu próprio aplicativo, tente usar o OAuth 2.0 Playground. Em seguida, você pode comparar os cabeçalhos e a solicitação HTTP do Playground às informações que seu aplicativo envia ao Google Analytics. Essa verificação é uma maneira simples de garantir a formatação correta das suas solicitações.

Concessão inválida

Quando você tenta usar um token de atualização, recebe um erro invalid_grant:

  • O relógio do seu servidor não está em sincronia com o Network Time Protocol – NTP.
  • O limite de tokens de atualização foi excedido.

Os aplicativos podem solicitar vários tokens de atualização para acessar uma única conta do Google Analytics.

Por exemplo, se um usuário deseja instalar um aplicativo em várias máquinas e acessar a mesma conta do Google Analytics, é necessário ter um token diferente para cada máquina. Quando o número de tokens de atualização excede o limite, os tokens mais antigos se tornam inválidos. Se o aplicativo tenta usar um token de atualização inválido, uma resposta de erro invalid_grant é retornada.

O limite para cada par único de cliente OAuth 2.0 e conta do Google Analytics é de 25 tokens de atualização. Se o aplicativo continuar a solicitar tokens de atualização para o mesmo par de cliente/conta, quando o 26º token for emitido, o primeiro se tornará inválido. O 27º token de atualização solicitado invalidará o segundo token emitido anteriormente e assim por diante.