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ões: local
e effective
. As permissões "local" se aplicam à conta, propriedade ou vista da propriedade (perfil) específica. Ao atribuir permissões com a API, use a propriedade permissions.local
. As permissões Effective
representam permissões herdadas de recursos pai.
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. Isso é representado pela propriedadepermissions.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
- Atualizar um grande número de usuários
- Excluir um usuário da hierarquia da conta
- Atualizar um único usuário
- Adicionar um único usuário
Listar todos os usuários de uma conta
Para listar todos os usuários de uma conta, incluindo todos que têm 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:
- Reúna todos os links de usuário da conta:
list
todos osaccountUserLinks
.
- Crie solicitações de atualização para cada usuário com as permissões adequadas:
update
para cadaaccountUserLink
.
- 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.
- Chame
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:
- Reúna todos os links do usuário para cada nível da entidade. Execute três solicitações
list
para a conta: - 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õeslocal
estiverem definidas, então execute umdelete
no recurso
- Se as propriedades
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
Também é possível atualizar as permissões do usuário usando a API Management. Por exemplo, as etapas para alterar o nível de permissão de um usuário de READ_AND_ANALYZE
para EDIT
, supondo que você não saiba o nome ou ID da vista (perfil), são:
Reúna todos os links do usuário para cada nível da entidade. Execute três solicitações
list
para a conta: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 ele tiver permissõeslocal
com acessoREAD_AND_ANALYZE
, então execute umupdate
no recurso.
- Se as propriedades
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:
- Use a API de gerenciamento ou a interface da Web para recuperar IDs da conta, propriedade e vista da propriedade (perfil).
- Adicione o usuário executando o método
insert
do recursoprofileUserLinks
.
Agrupar chamadas
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. Solicitações em lote de permissões de usuários com mais de uma conta do Google Analytics vão resultar em um erro com a seguinte mensagem:
All batched requests must be under the same account
.
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 passa pelas contas do usuário autorizado e, para cada conta, uma única solicitação em lote é criada. Em cada solicitação em lote, ele agrupa todas as alterações de um determinado usuário.
"""A simple example of Google Analytics batched user permissions.""" import json from googleapiclient.errors import HttpError from googleapiclient.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.