The Google Analytics Management API allows for programmatic management of user permissions. This is especially useful for large companies with frequent updates to their access control lists (ACLs). Show IntroductionThere are three main resources that are used to control who can access an account, property or view (profile):
There is also special batching support for user permissions write operations. User PermissionsA user, represented by a Google Account, can be granted the following levels of access to a Google Analytics account, property or view (profile):
For additional details on each level of access see the User Permissions help center article. Assigning permissionsThe API exposes two types of permissions: local and effective. Local permissions apply to the given account, property or view (profile). When assigning permissions with the API you should use the permissions.local property. Effective permissions represent permissions that are inherited from parent resources. Inherited permissionsIf a user is granted EDIT permission on an account, all profiles and properties under that account will inherit this permissions; this will be represented by the permissions.effective property. If Google Analytics Accounts, Properties or Views belong to an organization, owners of that organization have the ability to edit users in those accounts. However, the Management API lists only explicit members of the Accounts, Properties or Views, not the organization or its owners.Use casesUser permissions in the Management API can be used to solve the following use cases:
List all users for an accountTo list all users for an account, including all users who have permissions on any property or view (profile) in the account, execute the list method of the accountUserLinks resource. Note: The local permissions property may be empty for some users if they've been granted access deeper in the account hierarchy and not on the account directly.Update a large number of usersTo update permissions for a large number of users it is highly recommended you use batching; this will not only save quota but will also be much more performant -- see the batching section below for complete details. The steps required to carry this out for an account are:
Delete a user from the account hierarchyTo remove all occurrences of a user from the account hierarchy (i.e. account, properties, and views (profiles)). The steps required to carry this out are:
See the API Reference for details on the delete method of Account User Links, Web Property User Links, and View (Profile) User Links resources. Update a single userUser permissions can also be updated using the Management API. For example, the steps to change a user's permissions level from READ_AND_ANALYZE to EDIT, assuming you don't know the view (profile) name or ID, are:
See the API Reference for details on the update method of Account User Links, Web Property User Links, and View (Profile) User Links resources. Add a single userTo add a user to the account hierarchy, for example to a view (profile), requires the following steps:
BatchingThere are performance gains and quota incentives when batching permission API write (delete, insert, update) requests.
In order to get the most out of these performance gains there are certain things you should do.
Error HandlingAll permissions calls in a batch request are treated as a single transaction. This means that if any of the mutations is in error, no changes are made. The reasons we treat them as a single call are:
Batching example - PythonBelow is a simple example in Python of how to batch requests to add a list of users to a set of views (profiles). The example loops through the accounts for the authorized user, and for each account creates a single batch request. Within each batch requests it groups all the changes for a given user. """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 = ['', '', '', ''] # call the add_users function with the list of desired permissions. add_users(emails, ['READ_AND_ANALYZE'])Next stepsNext we will examine how to use the Google Analytics Management API to configure various data resources. |