Gerenciamento de usuários

A API de gerenciamento do Google Analytics permite o gerenciamento programático das permissões de usuários. Isso é especialmente útil para empresas grandes com atualizações frequentes das suas listas de controle de acesso (ACLs, na sigla em inglês).

Introdução

Três recursos principais são usados para controlar quem pode acessar uma conta, propriedade ou vista da propriedade (perfil):

Também há suporte para envio em lotes especiais para operações de gravação das permissões de usuários.

Permissões de usuários

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

  • MANAGE_USERS: necessário para enviar solicitações de gravação às APIs de permissões de usuários.
  • EDIT: necessário para editar recursos de gerenciamento de dados.
  • COLLABORATE
  • READ_AND_ANALYZE

Para detalhes adicionais sobre cada nível de acesso, consulte o artigo da Central de Ajuda sobre Permissões de usuários.

Atribuição de permissões

A API expõe dois tipos de permissão: local e effective. As permissões "local" se aplicam à conta, propriedade ou vista da propriedade (perfil) específica. Quando você atribuir permissões com a API, use a propriedade permissions.local. Permissões effective representam permissões que são herdadas de recursos pai.

Permissões herdadas

Se um usuário recebe a permissão EDIT em uma conta, todos os perfis e as propriedades dessa conta herdam essa permissão. Isso é representado pela propriedade permissions.effective.

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 aqueles com permissões em qualquer propriedade ou vista (perfil) na conta, execute o método list do recurso accountUserLinks.

Atualizar um grande número de usuários

Para atualizar permissões para um grande número de usuários, recomendamos usar o envio em lotes. Além de economizar a cota, essa estratégia é mais eficiente. Consulte a seção sobre lotes abaixo para ver detalhes completos. As etapas necessárias para realizar essa ação em uma conta são:

  1. Reúna todos os links de usuário da conta:
    • list para todos os accountUserLinks.
  2. Crie solicitações de atualização para cada usuário com as permissões adequadas:
    • update para todos os accountUserLink.
  3. Crie uma única solicitação em lote para cada 300 usuários com as solicitações de atualização acima:
    • Chame batch para cada 300 usuários.

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 (perfil)). 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:
    • list para todos os accountUserLinks.
    • list para todos os webpropertyUserLinks configurando o parâmetro webpropertyId como ~all.
    • list para todos os profileUserLinks configurando 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 corresponderem ao usuário e se as permissões local estiverem definidas, então execute delete no recurso.

Consulte a referência de APIs para ver detalhes sobre o método delete dos recursos de links do usuário da conta, da propriedade da Web e da vista (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. Reúna todos os links do usuário para cada nível da entidade. Execute três solicitações list para a conta:

    • list para todos os accountUserLinks.
    • list para todos os webpropertyUserLinks configurando o parâmetro webpropertyId como ~all.
    • list para todos os profileUserLinks configurando 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 corresponderem ao usuário e se o usuário tiver permissão local com acesso READ_AND_ANALYZE, então execute um update no recurso.

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

Adicionar um único usuário

Para adicionar um usuário à hierarquia de contas, por exemplo, a uma vista da propriedade (perfil), siga estas 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.

Lotes

Há ganhos de desempenho e incentivos de cota ao enviar solicitações de gravação (exclusão, inserção, atualização) em lotes à API de permissão de usuários.

  • As solicitações em lote de permissões de usuários 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 de usuários é contabilizado como uma única operação de gravação.
  • É possível fazer até 300 solicitações da API de permissões de usuários 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. Enviar solicitações em lote de permissões de usuários com mais de uma conta do Google Analytics gera um erro com a mensagem a seguir: All batched requests must be under the same account (Todas as solicitações em lote precisam estar na mesma conta).

Tratamento de erros

Todas as chamadas de permissão em uma solicitação em lote são tratadas como uma única transação. Isso significa que, se alguma das mutações for um erro, nenhuma alteração será feita. Os motivos pelos quais as tratamos como uma única chamada são:

  • Várias edições podem ser necessárias para ajustar as permissões de um único usuário. Se uma das edições estiver incorreta, o comprometimento de uma parte do lote pode fazer com que as permissões do usuário fiquem em um estado indesejado.
  • Ao tratar as edições como uma única transação, otimizamos o tráfego e podemos reduzir a cota necessária para a chamada.

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.

"""A simple example of Google Analytics batched user permissions."""
import json
from apiclient.errors import HttpError
from apiclient.http import BatchHttpRequest

def call_back(request_id, response, exception):
  """Handle batched request responses."""
  print request_id
  if exception is not None:
    if isinstance(exception, HttpError):
      message = json.loads(exception.content)['error']['message']
      print ('Request %s returned API error : %s : %s ' %
             (request_id, exception.resp.status, message))
  else:
    print response

def add_users(users, permissions):
  """Adds users to every view (profile) with the given permissions.

  Args:
    users: A list of user email addresses.
    permissions: A list of user permissions.
  Note: this code assumes you have MANAGE_USERS level permissions
  to each profile and an authorized Google Analytics service object.
  """

  # Get the a full set of account summaries.
  account_summaries = analytics.management().accountSummaries().list().execute()

  # Loop through each account.
  for account in account_summaries.get('items', []):
    account_id = account.get('id')

    # Loop through each user.
    for user in users:
      # Create the BatchHttpRequest object.
      batch = BatchHttpRequest(callback=call_back)

      # Loop through each property.
      for property_summary in account.get('webProperties', []):
        property_id = property_summary.get('id')

        # Loop through each view (profile).
        for view in property_summary.get('profiles', []):
          view_id = view.get('id')

          # Construct the Profile User Link.
          link = analytics.management().profileUserLinks().insert(
              accountId=account_id,
              webPropertyId=property_id,
              profileId=view_id,
              body={
                  'permissions': {
                      'local': permissions
                  },
                  'userRef': {
                      'email': user
                  }
              }
          )
          batch.add(link)

      # Execute the batch request for each user.
      batch.execute()

if __name__ == '__main__':

  # Construct a list of users.
  emails = ['ona@gmail.com', 'emi@gmail.com', 'sue@gmail.com', 'liz@gmail.com']

  # call the add_users function with the list of desired permissions.
  add_users(emails, ['READ_AND_ANALYZE'])

Próximas etapas

Em seguida, examinaremos como usar a API de gerenciamento do Google Analytics para configurar vários recursos de dados.