使用 IAM 條件控管 Memory Bank 的存取權

Memory Bank 可讓您根據範圍屬性，控管記憶和記憶修訂版本資源的存取權。您可以使用 IAM 條件定義精細的存取控管機制，例如根據一般運算語言中定義的條件，限制特定使用者或群組的存取權。

本文說明如何為專案中的記憶和修訂版本，建立及套用條件式存取政策。

如要瞭解權限總覽，請參閱「查看必要角色」。

總覽

您可以使用 IAM 條件，設定只有在符合指定條件時，才授予記憶和記憶修訂版本資源的存取權。您可以使用 API 屬性 "aiplatform.googleapis.com/memoryScope"，搭配以一般運算語言編寫的運算式，根據記憶資源中的 scope 欄位控管記憶存取權。範圍是建立或生成記憶時提供的任意字典，例如 {'user_id': '123'}，可讓您整理哪些記憶屬於哪個群組。

這些條件式 Identity and Access Management 政策是在專案層級建立，適用於專案中的所有記憶。您可以將 IAM 條件套用至各種主體，包括專案使用者和服務帳戶。

IAM 條件可用於同時將 Identity and Access Management (IAM) 權限授予多項相關 Memory Bank 資源，包括尚未建立的資源。您可以限制記憶和修訂版本的存取權，讓使用者只能存取自己的資訊，或讓開發人員只能查看特定記憶庫資源，不需特別授予權限。

事前準備

如要為記憶和記憶修訂版本設定條件式 IAM 政策，請按照下列步驟操作：

• 查看 IAM 條件：請參閱 IAM 條件總覽。
• 判斷必要角色：找出適合您用途的專屬 Memory Bank IAM 角色，確保遵循最小權限原則。

• 找出受影響的主體：找出組織中應獲得哪些權限的人員。舉例來說，請參考以下範例：

  • 開發人員是否能查看所有記憶。
  • 專案管理員是否能查看所有記憶。
  • 特定代理身分是否只能存取特定記憶。
• 授予 IAM 角色：確認您具備必要角色，當中含有執行本文件所述工作所需的權限。

  如要取得將 IAM 條件套用至 Agent Platform Memory Bank 資源所需的權限，請要求管理員授予您下列 IAM 角色：

  • 專案：專案 IAM 管理員 (`roles/resourcemanager.projectIamAdmin`)

  如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

  這些預先定義的角色具備必要權限，可將 IAM 條件套用至 Agent Platform Memory Bank 資源。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

  所需權限

  必須具備下列權限，才能將 IAM 條件套用至 Agent Platform Memory Bank 資源：

  • 在專案層級設定條件式 IAM 存取權：`resourcemanager.projects.setIamPolicy`

  您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

  如要對整個組織使用 IAM 條件，您也必須具備管理組織政策的權限。

建立回憶集的條件式存取權

如要授予記憶體的條件式存取權，請在專案層級的 IAM 政策繫結中新增條件。條件會使用 api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) 函式檢查記憶體資源的範圍對應。建立或生成記憶時，您需要定義範圍。

如需建立含條件 IAM 政策的詳細指南，請參閱「允許政策中的條件」。

如要將單一角色授予主體，請按照下列步驟操作：

resource "google_project_iam_member" "example" {
  project    = "PROJECT_ID"
  role       = "ROLE"
  member     = "MEMBER"
  condition {
    title       = "Memory Access Condition"
    description = "IAM condition for Memory Bank"
    expression  = "CONDITION"
  }
}

範圍層級權限的最佳做法

為 Memory Bank 建立條件時，請遵循下列最佳做法：

1. 使用專門的記憶庫角色：記憶庫 IAM 條件只能用於適用於記憶和記憶修訂版本的角色。您可以使用 aiplatform.googleapis.com/memoryViewer、aiplatform.googleapis.com/memoryEditor 和 aiplatform.googleapis.com/memoryUser 等特殊角色，避免授予過多權限。詳情請參閱「Specialized Memory Bank IAM 角色」。

2. 使用肯定條件：建議在 aiplatform.googleapis.com/memoryScope 上使用肯定條件 (例如檢查是否相等或是否存在鍵/值組合)，以提高準確度。由於不支援的類型和服務會以空白範圍表示，負面條件 (例如檢查不相等) 可能會不小心比對到大量資源，導致權限過於寬鬆，並授予非預期的權限。

3. 盡可能縮短條件：建議您在 IAM 條件運算式中使用最短、最簡單的邏輯，尤其是打算使用大量條件時。IAM 允許政策有大小限制，簡化條件可避免達到這些 IAM 限制。詳情請參閱「限制」一節。舉例來說，您可以省略檢查運算式 'user_id' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) && api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA' 中是否存在索引鍵，改用較短的陳述式 api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA'。如果缺少 user_id 鍵，較長的運算式會評估為 false，而較短的運算式會導致錯誤。由於 IAM 條件運算式中的錯誤會導致存取遭拒，因此這兩個運算式會產生相同的結果。

專用記憶庫 IAM 角色

使用 IAM 條件時，請務必避免 IAM 政策過於寬鬆。下表列出授予 Memory Bank API 條件式 IAM 角色時，可使用的特殊角色：

搭配使用 IAM 條件和 Memory Bank

本節涵蓋下列範例，說明如何搭配使用 IAM 條件和 Memory Bank：

1. 授予記憶體讀取權限，範圍必須完全相符。

2. 授予記憶體寫入權限，範圍包含特定鍵/值組合。

3. 授予記憶體完整存取權，範圍包含特定索引鍵。

4. 授予記憶體完整存取權，範圍包含特定前置字元。

5. 授予記憶體完整存取權，並使用一組允許的值設定金鑰範圍。

授予記憶體讀取權限，且範圍完全相符

下列條件只會將範圍為 {"userId": "userA"} 的記憶體檢視權限授予個人 userA@gmail.com。

這表示只要範圍是 {"userId": "userA"}，成員就能取得及擷取記憶，以及列出和取得這些記憶的修訂版本。使用者無法存取範圍為 {'userId': 'userA', 'source': 'ADK'} 的記憶。

{
  "members": ["user:userA@gmail.com"],
  "role": "roles/aiplatform.memoryViewer",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) == {'userId': 'userA'}"
  }
}

將記憶體的寫入權限授予範圍包含特定鍵/值組合的使用者

下列條件會將包含鍵/值組合 'userId': 'userA' 的任何記憶體編輯權限授予個人 developerA@corp.com。

也就是說，使用者可以建立、更新、刪除及生成記憶，以及建立和復原這些記憶的修訂版本，範圍包括 {'userId': 'userA'} 和 {'userId': 'userA', 'source': 'ADK'}。

{
  "members": ["user:developerA@corp.com"],
  "role": "roles/aiplatform.memoryEditor",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['userId'] == 'userA'"
  }
}

授予記憶體完整存取權，範圍包含特定金鑰

下列條件會將群組 group:engineering@corp.com 使用者 (檢視者和編輯者) 存取權授予具有 'admin_override' 或 'public_access_flag' 鍵的回憶。

這表示群組成員對 {'admin_override': 'true'}、{'admin_override': 'true', 'public_access_flag': 'false'} 和 {'userId': 'userA', 'public_access_flag': 'false'} 等範圍的記憶體具有完整的讀取和寫入權限。

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.memoryUser",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "('admin_override' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {})) || ('public_access_flag' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {}))"
  }
}

授予記憶體完整存取權，範圍包含特定前置字串

下列條件會將群組 group:engineering@corp.com 使用者 (檢視者和編輯者) 存取權授予索引鍵為 'userId' 且值開頭為 'user' 的記憶。您可以使用 'startsWith' 檢查前置字元，並使用 'endsWith' 檢查後置字元。

也就是說，群組成員對範圍為 {'userId': 'userA'}、{'userId': 'userB', 'public_access_flag': 'false'} 等的記憶體具有完整讀寫權限。

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.memoryUser",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['userId'].startsWith('user')"
  }
}

授予記憶體的完整存取權，並設定一組允許的值做為鍵的範圍

下列條件會授予群組 group:engineering@corp.com 使用者 (檢視者和編輯者) 存取權，允許他們存取具有鍵 'userId' 且值為 'userA' 或 'userB' 的記憶。

這表示群組成員對 {'userId': 'userA'}、{'userId': 'userB', 'public_access_flag': 'false'} 等範圍的記憶體具有完整讀寫權限。

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.memoryUser",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['userId'] in ['userA', 'userB']"
  }
}

限制

• 主體限制：IAM 政策最多只能有 1500 個不重複的主體。您可以使用 Google 群組管理這項限制。詳情請參閱「所有主體的限制」。

• API 支援：針對多個範圍運作的方法 (例如 ListMemories 和 PurgeMemories) 不支援 IAM 條件。如要授予這些權限，您必須授予主體無條件角色，例如 aiplatform.googleapis.com/memoryViewer、aiplatform.googleapis.com/memoryUser 或相關的無條件 Gemini Enterprise Agent Platform 角色。