Permissões de usuário - guia do desenvolvedor

Este documento explica conceitos importantes sobre o uso da API de gerenciamento para visualizar e gerenciar permissões de usuário em contas, propriedades e vistas da propriedade (perfis) do Google Analytics.

Introdução

Com as permissões de usuário na API de gerenciamento, você pode listar, criar, editar e excluir usuários da sua conta do Google Analytics. Isso é útil quando você deseja automatizar a adição de novos usuários no Google Analytics ou a remoção um conjunto de usuários.

Antes de começar

Todas as Google Analytics APIs são acessadas de maneira semelhante. Antes de começar a usar a API de gerenciamento:

  • Leia a página Bibliotecas cliente para ver uma lista completa de bibliotecas cliente específicas de linguagens de programação que funcionam com a API.
  • Leia o Guia de referência para saber mais sobre a interface da API e sobre como acessar dados sem uma biblioteca cliente.

Cada biblioteca cliente fornece um único objeto de serviço de análise para acessar todos os dados da API de gerenciamento. Para criar o objeto de serviço, normalmente é necessário seguir estas etapas:

  1. Registre seu aplicativo no Google Developers Console.
  2. Autorize o acesso aos dados do Google Analytics.
  3. Crie um objeto de serviço "Analytics".

Se você não tiver concluído essas etapas, pare e leia o Tutorial de apresentação da Google Analytics API. Ele orienta você sobre as etapas iniciais de criação de um aplicativo da Google Analytics API. Depois de concluí-lo, você saberá como acessar Google Analytics APIs para realizar tarefas reais.

Conceitos

Hierarquia de contas

O Google Analytics tem uma hierarquia de contas na qual um usuário autorizado pode ter várias contas, cada conta pode ter várias propriedades e cada propriedade pode ter várias vistas da propriedade (perfis).

Uma hierarquia com uma conta no nível superior, duas propriedades da Web no segundo nível e conectadas à conta.No terceiro nível, um único perfil está conectado à propriedade da Web mais à esquerda, e dois perfis estão conectados à propriedade da Web mais à direita.Usuários e permissões têm três níveis cada um.
Figura 1: a hierarquia da conta

Níveis de permissão

Um usuário, representado por uma Conta do Google, pode receber diferentes níveis de acesso a uma conta, propriedade ou vista da propriedade (perfil) do Google Analytics.

Os níveis de acesso são:

  • MANAGE_USERS
  • EDIT
  • COLLABORATE
  • READ_AND_ANALYZE

Para ver detalhes adicionais sobre cada nível de acesso, consulte as permissões do usuário.

Permissões herdadas

Se um usuário recebe a permissão EDIT em uma conta, todos os perfis e propriedades dessa conta herdam essa permissão. Da mesma forma, se um usuário recebe a permissão COLLABORATE em uma propriedade, todos os perfis da propriedade também herdam essa permissão.

Uso de permissões

As APIs expõem dois tipos de permissões: local e effective. As permissões locais se aplicam à conta, propriedade ou vista da propriedade (perfil) real. Somente permissões local podem ser configuradas. Permissões effective representam permissões que são herdadas de recursos pai.

Recuperação das permissões para o usuário autorizado

Você pode recuperar as informações de permissões do usuário autorizado no momento realizando uma operação list ou get em um recurso de contas, propriedades da Web ou vistas da propriedade (perfis).

Para realizar essas operações, o usuário precisa autorizar um dos escopos a seguir:

  • https://www.googleapis.com/auth/analytics.readonly
  • https://www.googleapis.com/auth/analytics

Gerenciamento das permissões do usuário

Os recursos a seguir estão disponíveis para visualizar e gerenciar permissões do usuário para contas, propriedades e vistas da propriedade (perfis) do Google Analytics:

Essas operações só podem ser realizadas por usuários com permissões MANAGE_USERS e que autorizaram o seguinte escopo:

  • Escopo https://www.googleapis.com/auth/analytics.manage.users.

Limites de link da conta do usuário

Há um limite máximo de cem contas por usuário para a API.

  • As tentativas de chamar o método insert com um usuário que já tem cem ou mais contas retornarão um erro.
  • Consulte Limites e cotas para conhecer os limites gerais.

Casos de uso

As permissões do usuário na API de gerenciamento podem ser usadas para resolver os seguintes casos de uso:

Listar todos os usuários de uma conta

Para listar todos os usuários de uma conta, incluindo todos os usuários com permissões em qualquer propriedade ou vista da propriedade (perfil) na conta, você simplesmente executa o método list do recurso accountUserLinks.

Excluir um usuário da hierarquia de contas

Remova todas as ocorrências de um usuário da hierarquia de contas (ou seja, conta, propriedades e vistas da propriedade (perfis)). As etapas necessárias para realizar essa ação são:

  1. Pegue todos os links de usuário para cada nível da entidade.
    Execute três solicitações list para a conta:
    1. list para todos os accountUserLinks.
    2. list para todos os webpropertyUserLinks configurando o parâmetro webpropertyId como ~all.
    3. list para todos os profileUserLinks definindo os parâmetros webpropertyId e profileId como ~all.
  2. Encontre e exclua usuários com permissões locais.
    Para cada resposta recebida das três operações "list" na etapa 1, repita em cada entityUserLink:
    • Se as propriedades userRef correspondem ao usuário e se as permissões local estão definidas, então execute um delete no recurso.

Consulte a Referência de APIs para detalhes sobre o método delete dos recursos de links do usuário da conta, links do usuário da propriedade da Web e links do usuário da vista da propriedade (perfil).

Atualizar um único usuário

As permissões do usuário também podem ser atualizadas utilizando a API de gerenciamento. Por exemplo, as etapas para alterar o nível de permissões de um usuário de READ_AND_ANALYZE para EDIT, supondo que você não saiba o nome ou ID da vista da propriedade (perfil), são:

  1. Pegue todos os links de usuário para cada nível da entidade.
    Execute três solicitações list para a conta:
    1. list para todos os accountUserLinks.
    2. list para todos os webpropertyUserLinks configurando o parâmetro webpropertyId como ~all.
    3. list para todos os profileUserLinks definindo os parâmetros webpropertyId e profileId como ~all.
  2. Encontre e atualize usuários com permissões locais.
    Para cada resposta recebida das três operações "list" na etapa 1, repita em cada entityUserLink:
    • Se as propriedades userRef correspondem ao usuário e se o usuário tem permissões local com acesso READ_AND_ANALYZE, execute um update no recurso.

Consulte a Referência de APIs para detalhes sobre o método update dos recursos de links do usuário da conta, links do usuário da propriedade da Web e links do usuário da vista da propriedade (perfil).

Adicionar um único usuário

A adição de um usuário à hierarquia de contas, por exemplo, a uma vista da propriedade (perfil), requer as seguintes etapas:

  1. Use a API de gerenciamento ou a interface da Web para recuperar IDs da conta, propriedade e vista da propriedade (perfil).
  2. Adicione o usuário executando o método insert do recurso profileUserLinks.

Consulte a Referência de APIs para ver detalhes sobre o método insert dos recursos de links do usuário da conta, links do usuário da propriedade da Web e links do usuário da vista da propriedade (perfil).

Lotes

Há ganhos de desempenho e incentivos de cota ao colocar em lote solicitações de gravação (exclusão, inserção, atualização) da API de permissão do usuário.

  • As solicitações em lote de permissões do usuário podem aproveitar as otimizações de back-end e ter ganhos de desempenho significativos.
  • Cada grupo de 30 solicitações em lote da API de permissões do usuário é contabilizado como uma única operação de gravação.
  • É possível fazer até 300 solicitações da API de permissões do usuário em uma única solicitação em lote, o que permite um número de QPS com limite por usuário mais alto.

Para aproveitar ao máximo esses ganhos de desempenho, você deve realizar algumas ações.

  • Agrupe sua solicitação de API por usuário.
  • Faça solicitações em lote apenas para uma conta. Solicitações em lote de permissões de usuários com mais de uma conta do Google Analytics resultará em um erro com a mensagem a seguir: Todas as solicitações em lote precisam estar na mesma conta.

Exemplo de lote - Python

Veja a seguir um exemplo simples em python de como colocar solicitações em lote para adicionar uma lista de usuários a um conjunto de vistas da propriedade (perfil). O exemplo executa um loop nas contas do usuário autorizado e, para cada conta, cria uma única solicitação em lote. Em cada solicitação em lote, ele agrupa todas as alterações de determinado usuário.