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

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

這份文件說明如何為專案中的回憶集和修訂版本建立及套用條件存取權政策。

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

總覽

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

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

IAM 條件可同時授予多個相關 Memory Bank 資源身分與存取權管理 (IAM) 權限，包括尚未建立的資源。您可以限制記憶和修訂版本的存取權，讓使用者只能存取自己的資訊，或讓開發人員只能查看特定 Memory Bank 資源，不必取得特殊權限。

事前準備

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

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

• 找出受影響的主體：找出貴機構中應獲得哪些權限的使用者。舉例來說，請看以下範例：

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

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

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

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

  這些預先定義的角色具備必要的權限，可對 Agent Platform Memory Bank 資源套用 IAM 條件。如要查看確切的必要權限，請展開「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. 使用專屬的 Memory Bank 角色： Memory Bank IAM 條件僅適用於記憶內容和記憶內容修訂版本適用的角色。您可以運用 aiplatform.googleapis.com/memoryViewer、aiplatform.googleapis.com/memoryEditor 和 aiplatform.googleapis.com/memoryUser 等專門角色，避免授予過於寬鬆的存取權。詳情請參閱「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 條件運算式中的錯誤會導致存取遭拒，因此這兩個運算式會產生相同的結果。

專屬的 Memory Bank IAM 角色

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

搭配 Memory Bank 使用 IAM 條件

本節涵蓋下列使用 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'}"
  }
}

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

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

也就是說，使用者可建立、更新、刪除及生成回憶集，並建立及復原這些回憶集的修訂版本，範圍包括 {'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 支援：針對多個範圍運作的方法不支援 IAM 條件，例如 ListMemories 和 PurgeMemories。如要授予這些權限，您必須授予主體無條件角色，例如 aiplatform.googleapis.com/memoryViewer、aiplatform.googleapis.com/memoryUser，或相關的無條件 Gemini Enterprise Agent Platform 角色。