API de aprovisionamento – autorização

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Este guia descreve como um aplicativo autoriza solicitações para a API de aprovisionamento.

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. Nenhum outro protocolo de autorização é aceito. Se o aplicativo usa o recurso 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 para o 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 ver informações detalhadas sobre 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 API Google Analytics:

Escopo Significado
https://www.googleapis.com/auth/analytics.provision Criar uma nova conta do Google Analytics com sua propriedade e vista da propriedade padrão

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 grande variedade de linguagens de programação. Verifique a página com bibliotecas e amostras 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:

Apps 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ê receberá um código de status 401 se a access_token tiver expirado ou se estiver usando o escopo incorreto 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, aparece a seguir 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 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 2º token emitido anteriormente e assim por diante.