API de relatórios principais – autorização

Este guia descreve como um aplicativo autoriza solicitações à API de relatórios principais.

Autorização de solicitações

Para poder visualizar as informações das suas contas no site 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 à API Google Analytics 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á outros protocolos de autorização compatíveis. Se o aplicativo usa o Fazer login com o Google, alguns aspectos da autorização são administrados para você.

Autorizar solicitações com OAuth 2.0

Todas as solicitações à API Google Analytics 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 API Google Analytics 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 para que o aplicativo seja autorizado a solicitar alguns dos dados dele.
  5. Se o usuário aprovar, o Google fornecerá ao aplicativo um token de acesso de curta duração.
  6. O aplicativo solicita dados de usuário, anexando o token de acesso à solicitação.
  7. Se o Google determinar que a solicitação e o token são válidos, ele retornará os dados solicitados.

Alguns fluxos incluem etapas adicionais, como atualizar tokens para adquirir novos tokens de acesso. Para mais informações sobre fluxos de vários tipos de aplicativos, acesse a documentação OAuth 2.0 do Google.

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

Escopo Significado
https://www.googleapis.com/auth/analytics.readonly Acesso somente leitura à Google Analytics API.

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 Client-ID 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.

Exemplos

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

Exemplos

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 cliente é que um único projeto do Console de APIs pode ser usado no 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 API Google Analytics, 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ê quer 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:

  • Você vai receber um código de status 401 se a access_token tiver 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

Ao tentar usar um token de atualização, você recebe um erro invalid_grant:

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

Por exemplo, se um usuário quer 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 tentar usar um token de atualização invalidado, uma resposta de erro invalid_grant será 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 2º token emitido anteriormente e assim por diante.