Autorização

Este guia descreve como um aplicativo autoriza solicitações à API User Deletion.

Autorizar solicitações

Para poderem visualizar as informações das suas contas no site do Google Analytics, os usuários precisam fazer login nas respectivas Contas do Google. Da mesma forma, quando os usuários acessam o aplicativo pela primeira vez, eles precisam autorizar o app 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.user.deletion Exclui dados usando a API User Deletion.

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

Esse fluxo é ideal para o acesso automatizado, off-line ou programado dos dados do Google Analytics de um usuário.

Exemplo:

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

Lado do cliente

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

Exemplo:

Aplicativos instalados

Este fluxo é para aplicativos distribuídos como um pacote e instalados pelo usuário. Esse fluxo exige 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. A vantagem desse fluxo em comparação com o servidor da Web ou do lado do cliente é que um único projeto do Console de APIs pode ser usado para seu aplicativo. Isso possibilita 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 acesso automatizado, off-line ou programado aos dados do Google Analytics da sua conta. Por exemplo, para criar um painel em tempo real com 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:

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

  • Você vai receber um código de status 403 se o usuário autorizado não tiver acesso à visualização (perfil). Verifique se você tem autorização do usuário correto e se ele tem a visualização (perfil) selecionada.

Playground do OAuth 2.0

Essa ferramenta permite que você percorra 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ê não conseguir autorização para trabalhar no seu próprio aplicativo, tente fazer isso usando o playground do OAuth 2.0. Em seguida, compare os cabeçalhos HTTP e a solicitação do playground com o que seu aplicativo está enviando ao Google Analytics. Essa verificação é uma maneira simples de garantir que você está formatando suas solicitações corretamente.

Concessão inválida

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

  • O relógio do servidor não está sincronizado com o Network Time Protocol — NTP (em inglês).
  • 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 quiser instalar um aplicativo em várias máquinas e acessar a mesma conta do Google Analytics, um token separado será necessário 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 inválido, 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 solicitando tokens de atualização para o mesmo par de cliente/conta, quando o 26o token for emitido, o primeiro se tornará inválido. O 27º token de atualização solicitado invalidaria o segundo token emitido anteriormente e assim por diante.