Google Analytics Management API 可讓您透過程式管理使用者權限。對於經常更新存取控制清單 (ACL) 的大型公司而言,這項功能特別實用。
簡介
您可以透過三種主要資源,控制有權存取帳戶、資源或資料檢視 (設定檔) 的使用者:
此外,系統也支援使用者權限寫入作業的特殊批次作業。
使用者權限
由 Google 帳戶代表的使用者,可獲得下列 Google Analytics (分析) 帳戶、資源或資料檢視 (設定檔) 的存取權:
MANAGE_USERS
- 需要這項權限才能向使用者權限 API 發出寫入要求。EDIT
- 需要這項權限才能編輯資料管理資源。COLLABORATE
READ_AND_ANALYZE
如要進一步瞭解每個存取層級,請參閱「使用者權限」說明中心文章。
指派權限
API 提供兩種權限:local
和 effective
。本機權限會套用至指定帳戶、資源或資料檢視 (設定檔)。透過 API 指派權限時,請使用 permissions.local
屬性。Effective
權限代表繼承自父項資源的權限。
沿用權限
如果使用者獲得帳戶的 EDIT
權限,該帳戶下的所有設定檔和資源都會沿用這項權限,並以 permissions.effective 資源表示。
用途
Management API 中的使用者權限可用於解決下列使用情境:
列出帳戶的所有使用者
如要列出帳戶的所有使用者 (包括對帳戶中任何資源或資料檢視 (設定檔) 權限的所有使用者),請執行 accountUserLinks 資源的 list
方法。
更新大量使用者
如要更新大量使用者的權限,強烈建議您使用批次處理功能,這麼做不僅可以節省配額,而且也能提升效能。詳情請參閱下方的批次處理一節。在帳戶中執行此操作的必要步驟如下:
- 取得該帳戶的所有使用者連結:
list
所有accountUserLinks
。
- 為具有適當權限的每位使用者建構更新要求:
- 每
accountUserLink
update
。
- 每
- 為包含上述更新要求的「每 300 位使用者建構單一批次要求」:
- 為每 300 位使用者呼叫
batch
。
- 為每 300 位使用者呼叫
從帳戶階層中刪除使用者
若要將某位使用者的所有行為從帳戶階層中移除 (也就是帳戶、資源和資料檢視 (設定檔)),步驟如下:
- 取得各個實體層級的所有使用者連結。對帳戶執行 3 項
list
要求: - 尋找及刪除具有本機權限的使用者。針對步驟 1 中 3 項清單作業收到的每個回應,逐一執行每個
entityUserLink
:- 如果
userRef
屬性與使用者相符,「且」已設定local
權限,「然後」在資源上執行delete
- 如果
如要進一步瞭解帳戶使用者連結、網站資源使用者連結,以及資料檢視 (設定檔) 使用者連結資源的 delete
方法,請參閱 API 參考資料。
更新單一使用者
使用者權限也可以透過 Management API 更新。舉例來說,假設您不知道資料檢視 (設定檔) 名稱或 ID,將使用者權限層級從 READ_AND_ANALYZE
變更為 EDIT
的步驟如下:
取得各實體層級的所有使用者連結 針對該帳戶執行 3 項
list
要求:尋找及更新具備本機權限的使用者。針對步驟 #1 中 3 項清單作業收到的每個回應,重複執行每個
entityUserLink
:- 如果
userRef
屬性與使用者相符,「且」使用者俱備具備READ_AND_ANALYZE
存取權的local
權限,那麼請在資源上執行update
。
- 如果
如要進一步瞭解帳戶使用者連結、網站資源使用者連結,以及資料檢視 (設定檔) 使用者連結資源的 update
方法,請參閱 API 參考資料。
新增單一使用者
如要在帳戶階層 (例如資料檢視 (設定檔)) 中新增使用者,請按照下列步驟操作:
- 使用 Management API 或網頁介面擷取帳戶、資源和資料檢視 (設定檔) 的 ID。
- 透過執行
profileUserLinks
資源的insert
方法新增使用者。
批次處理
批次權限 API 寫入 (刪除、插入、更新) 要求時,您可以提高效能和配額獎勵,
- 批次處理使用者權限要求可善用後端最佳化功能,並大幅提升效能。
- 每 30 個批次使用者權限 API 要求只會計為一次「單一寫入作業」。
- 單一批次要求最多可提出 300 個使用者權限 API 要求,藉此提高每位使用者限制 QPS。
為充分發揮這些成效成長效益,您需要完成一些事項。
- 依使用者將 API 要求分組。
- 每個帳戶只能提出批次要求。對多個 Google Analytics (分析) 帳戶發出批次使用者權限要求時,會導致錯誤並顯示下列訊息:
All batched requests must be under the same account
。
處理錯誤
系統會將批次要求中的所有權限呼叫視為單一交易。也就是說,如有任何異動有誤,系統不會進行任何變更。我們將這些呼叫視為一次呼叫,原因如下:
- 您可能需要進行多次編輯,才能調整單一使用者的權限。如果其中一項編輯格式錯誤,分批提交部分批次可能會導致使用者的權限意外。
- 透過將編輯視為單一交易,我們得以最佳化流量,並降低呼叫所需的配額。
批次處理範例 - Python
下方的 Python 簡易範例說明如何批次要求,以將使用者名單新增至一組資料檢視 (設定檔)。此範例會循環處理已授權使用者的帳戶,且每個帳戶都會建立一個批次要求。會在每個批次要求中,將特定使用者的所有變更分組。
"""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'])
後續步驟
接下來,我們將探討如何使用 Google Analytics Management API 設定各種資料資源。