API de relatórios principais - autorização

O documento descreve como um aplicativo pode receber autorização para fazer solicitações à API de relatórios principais.

Autorização de solicitações

Os usuários precisam primeiro fazer login com uma Conta do Google para visualizar as informações dela no website do Google Analytics. Da mesma forma, no primeiro acesso ao seu aplicativo, os usuários precisam autorizar o aplicativo 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, você o registra usando o Google Developers Console. Em seguida, o Google fornece informações que serão usadas posteriormente, como um ID de cliente e uma chave secreta do cliente.
  2. Ative a Google Analytics API no Google Developers Console. Se ela não estiver indicada no Developers Console, pule 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 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.

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

As diretrizes a seguir descrevem casos de uso comuns para fluxos específicos do OAuth 2.0:

Servidor da Web

Este fluxo é útil para o acesso automatizado/off-line/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

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

Exemplo:

Aplicativos instalados

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

Exemplos:
  • Um widget para computador em um PC ou Mac.
  • Um plug-in para um sistema de gerenciamento de conteúdo. O benefício desse fluxo em relação ao fluxo de servidor da Web ou do lado do cliente é que um único projeto do Developers Console 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

Útil para o acesso automatizado/off-line/programado aos dados do Google Analytics para sua própria conta. Por exemplo, criar um painel ao vivo dos seus próprios dados do Google Analytics e compartilhá-lo com outros usuários.

Você precisa seguir algumas etapas para configurar as contas de serviço de forma que funcionem com o Google Analytics:

Para começar a usar a Google Analytics API, primeiro, é necessário criar ou selecionar um projeto no Google Developers Console e ativar a API. O uso desse link orienta você no processo e automaticamente ativa a Google Analytics API.

Como opção, você mesmo pode ativar a Google Analytics API no Developers Console desta forma:

  1. Abra a página Credenciais.

Nos dois casos, você é encaminhado para a página Credenciais e pode criar as credenciais do seu projeto.

Para configurar uma nova conta de serviço:

  1. Clique em Adicionar credenciais > Conta de serviço.
  2. Escolha se 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 de API do Google.

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

Solução de problemas

Se você tiver problemas com a autenticação e os códigos de status 401 ou 403 forem exibidos, veja algumas etapas para resolver seus problemas:

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 da propriedade (perfil). Verifique se você está autorizado com o usuário correto e se ele tem a vista da propriedade (perfil) que você selecionou.

OAuth 2.0 Playground. É uma ferramenta fantástica que permite percorrer todo o fluxo de autorização 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 as solicitações HTTP às informações que seu aplicativo enviou ao Google Analytics. Essa verificação é uma maneira simples de garantir que você está formatando suas solicitações corretamente.

OAuth 1.0 Playground. Semelhante ao OAuth 2.0 Playground, mas para a versão anterior do OAuth.

Concessão inválida

Se você receber uma resposta de erro invalid_grant ao tentar usar um token de atualização, o erro pode ter ser sido causado pelos seguintes motivos:

  1. O relógio do seu servidor não está em sincronia com o NTP.
  2. 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, isso é útil em situações em que um usuário deseja instalar um aplicativo em várias máquinas e acessar a mesma conta do Google Analytics. Nesse caso, são necessários dois tokens de atualização, um para cada instalação. Quando o número de tokens de atualização excede o limite, os tokens 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 (esse limite está sujeito a alterações). 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 invalida o segundo token emitido anteriormente e assim por diante.