使用者管理

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 方法。

更新大量使用者

如要更新大量使用者的權限，強烈建議您使用批次處理功能，這麼做不僅可以節省配額，而且也能提升效能。詳情請參閱下方的批次處理一節。在帳戶中執行此操作的必要步驟如下：

  1. 取得該帳戶的所有使用者連結：
    • list所有accountUserLinks。
  2. 為具有適當權限的每位使用者建構更新要求：
    • 每 accountUserLink update。
  3. 為包含上述更新要求的「每 300 位使用者建構單一批次要求」：
    • 為每 300 位使用者呼叫 batch。

從帳戶階層中刪除使用者

若要將某位使用者的所有行為從帳戶階層中移除 (也就是帳戶、資源和資料檢視 (設定檔))，步驟如下：

  1. 取得各個實體層級的所有使用者連結。對帳戶執行 3 項 list 要求：
    • list所有accountUserLinks。
    • 將 webpropertyId 參數設為 ~all，藉此list所有 webpropertyUserLinks。
    • 將 webpropertyId 和 profileId 參數設為 ~all 以list所有 profileUserLinks。
  2. 尋找及刪除具有本機權限的使用者。針對步驟 1 中 3 項清單作業收到的每個回應，逐一執行每個 entityUserLink：
    • 如果 userRef 屬性與使用者相符，「且」已設定 local 權限，「然後」在資源上執行 delete

如要進一步瞭解帳戶使用者連結、網站資源使用者連結，以及資料檢視 (設定檔) 使用者連結資源的 delete 方法，請參閱 API 參考資料。

更新單一使用者

使用者權限也可以透過 Management API 更新。舉例來說，假設您不知道資料檢視 (設定檔) 名稱或 ID，將使用者權限層級從 READ_AND_ANALYZE 變更為 EDIT 的步驟如下：

  1. 取得各實體層級的所有使用者連結 針對該帳戶執行 3 項 list 要求：

    • list所有accountUserLinks。
    • 將 webpropertyId 參數設為 ~all，藉此list所有 webpropertyUserLinks。
    • 將 webpropertyId 和 profileId 參數設為 ~all 以list所有 profileUserLinks。

  2. 尋找及更新具備本機權限的使用者。針對步驟 #1 中 3 項清單作業收到的每個回應，重複執行每個 entityUserLink：

    • 如果 userRef 屬性與使用者相符，「且」使用者俱備具備 READ_AND_ANALYZE 存取權的 local 權限，那麼請在資源上執行 update。

如要進一步瞭解帳戶使用者連結、網站資源使用者連結，以及資料檢視 (設定檔) 使用者連結資源的 update 方法，請參閱 API 參考資料。

新增單一使用者

如要在帳戶階層 (例如資料檢視 (設定檔)) 中新增使用者，請按照下列步驟操作：

  1. 使用 Management API 或網頁介面擷取帳戶、資源和資料檢視 (設定檔) 的 ID。
  2. 透過執行 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 設定各種資料資源。