使用 IAM 條件控管記憶體庫的存取權

根據預設，記憶體身分與存取權管理權限位於專案層級。本文說明如何使用 IAM Conditions，更精細地控管 Vertex AI Agent Engine Memory Bank 資源的存取權。

總覽

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

這些有條件的身分與存取權管理政策是在專案層級建立，並套用至專案中的所有記憶體。您可以對所有類型的主體套用 IAM 條件，包括專案使用者和服務帳戶。

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

事前準備

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

檢閱 IAM 條件：請先參閱 IAM 條件總覽。
判斷必要角色：找出適合您用途的專屬記憶體庫 IAM 角色，確保遵循最小權限原則。
找出受影響的主體：找出貴機構中應獲得哪些權限的使用者。舉例來說，請參考以下內容：
- 開發人員是否應能查看所有回憶集錦。
- 專案管理員是否應能查看所有回憶集錦。
- 特定代理程式身分是否只能存取特定記憶體。
授予 IAM 角色：請確認您具備必要的角色，其中包含執行本文件工作所需的權限。
如要取得對 Vertex AI Agent Engine Memory Bank 資源套用 IAM 條件所需的權限，請要求管理員授予下列 IAM 角色：
- 專案：專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin)
如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這些預先定義的角色具備權限，可對 Vertex AI Agent Engine 記憶體庫資源套用 IAM 條件。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：
所需權限

如要將 IAM 條件套用至 Vertex AI Agent Engine Memory Bank 資源，必須具備下列權限：
- 在專案層級設定條件式 IAM 存取權： resourcemanager.projects.setIamPolicy
您或許還可透過自訂角色或其他預先定義的角色取得這些權限。
如果您打算在整個機構中使用 IAM 條件，也需要管理機構政策的權限。

為回憶集錦建立條件存取權

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

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

如要將單一角色授予主體，請執行下列步驟：

控制台

前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面。

前往 IAM
選取專案。
選取要授予角色的主體：
- 如要將角色授予資源上已有其他角色的主體，請找出包含該主體的列，依序點選該列的「Edit principal」(編輯主體) 和「Add another role」(新增其他角色)。
  
  如要將角色授予服務代理，請選取「包含 Google 提供的角色授予項目」核取方塊，查看服務代理的電子郵件地址。Google
  
  注意： 管理資源存取權時，您無法編輯沿用的角色。如要編輯沿用的角色，請前往授予角色的資源。
- 如要將角色授予資源上還沒有任何角色的主體，請點選「Grant Access」(授予存取權)，然後輸入主體 ID，例如 my-user@example.com 或 //iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com。
從下拉式清單中選取要授予的角色。為遵循安全性最佳做法，請選擇僅含主體所需權限的角色。您可以選擇其中一個專屬的 Memory Bank IAM 角色。
以 aiplatform.googleapis.com/memoryScope 做為 API 屬性，為角色新增條件。如需可能的條件陳述式，請參閱下方的範例。
按一下 [儲存]。主體就會取得指定資源的角色。

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
您可以使用 add-iam-policy-binding 指令，快速將角色授予主體。

使用下方的任何指令資料之前，請先替換以下項目：
- PROJECT_ID：您的 Google Cloud 專案 ID。專案 ID 為英數字元，例如 my-project。
- PRINCIPAL：主體或成員的 ID，通常採用以下形式： PRINCIPAL_TYPE:ID。例如 user:my-user@example.com 或 principalSet://iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com。如需 PRINCIPAL 可擁有的完整值清單，請參閱「主體 ID」。
  
  如果是 user 主體類型，識別碼中的網域名稱必須是 Google Workspace 網域或 Cloud Identity 網域。如要瞭解如何設定 Cloud Identity 網域，請參閱 Cloud Identity 總覽。
- ROLE_NAME：要撤銷的角色名稱。請使用下列其中一種格式：
  - 預先定義的角色：roles/aiplatform.IDENTIFIER
  - 專案層級自訂角色：projects/PROJECT_ID/roles/IDENTIFIER
  從下拉式清單中選取要授予的角色。為遵循安全性最佳做法，請選擇僅含主體所需權限的角色。您可以選擇其中一個專屬的 Memory Bank IAM 角色。
- CONDITION：使用 aiplatform.googleapis.com/memoryScope 做為 API 屬性，為角色新增條件。請參閱下方的範例，瞭解可能的條件陳述式。
執行下列指令：
Linux、macOS 或 Cloud Shell
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=PRINCIPAL --role=ROLE_NAME \
    --condition=CONDITION
```
Windows (PowerShell)
```
gcloud projects add-iam-policy-binding PROJECT_ID `
    --member=PRINCIPAL --role=ROLE_NAME `
    --condition=CONDITION
```
Windows (cmd.exe)
```
gcloud projects add-iam-policy-binding PROJECT_ID ^
    --member=PRINCIPAL --role=ROLE_NAME ^
    --condition=CONDITION
```
回應會包含更新後的 IAM 政策。

Terraform

如要瞭解如何套用或移除 Terraform 設定，請參閱「基本 Terraform 指令」。詳情請參閱 Terraform 供應商參考文件。

如果您使用 Terraform 設定 IAM 政策，可以在 google_project_iam_member 資源中加入條件，限制成員存取回憶集錦。

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"
  }
}

請替換下列變數：

PROJECT_ID：您的 Google Cloud 專案 ID。專案 ID 為英數字元，例如 my-project。
ROLE：要授予的 IAM 角色，例如 roles/aiplatform.memoryEditor。
MEMBER：要授予角色的主體，例如 user:developerA@corp.com。如需 MEMBER 可擁有的完整值清單，請參閱「主體 ID」。
CONDITION：您的 IAM 條件陳述式，使用 aiplatform.googleapis.com/memoryScope 做為 API 屬性。請參閱下方的範例，瞭解可能的條件陳述式。

範圍層級權限的最佳做法

為記憶體庫建立條件時，請遵循下列最佳做法：

使用專屬的記憶體庫角色：記憶體庫 IAM 條件僅適用於記憶體和記憶體修訂版本適用的角色。您可以運用 aiplatform.googleapis.com/memoryViewer、aiplatform.googleapis.com/memoryEditor 和 aiplatform.googleapis.com/memoryUser 等專門角色，避免過度寬鬆的存取權。詳情請參閱專用記憶體庫 IAM 角色。
使用正向條件：建議在 aiplatform.googleapis.com/memoryScope 中使用正向條件 (例如檢查等號或鍵/值組合是否存在)，以提高準確度。由於不支援的類型和服務會以空白範圍表示，因此負面條件 (例如不相等檢查) 可能會意外比對到各種資源，導致權限過於寬鬆，允許授予非預期的權限。
盡可能縮短條件：建議您在 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 角色時可使用的專屬角色：

角色名稱	說明	包含的權限
`roles/aiplatform.memoryViewer`	授予回憶和回憶修訂版本的唯讀存取權。	`aiplatform.googleapis.com/memories.get` `aiplatform.googleapis.com/memories.list` `aiplatform.googleapis.com/memories.retrieve` `aiplatform.googleapis.com/memoryRevisions.list` `aiplatform.googleapis.com/memoryRevisions.get`
`roles/aiplatform.memoryEditor`	可授予記憶體的寫入和生成權限，以及記憶體修訂版本的復原權限。	`aiplatform.googleapis.com/memories.create` `aiplatform.googleapis.com/memories.update` `aiplatform.googleapis.com/memories.delete` `aiplatform.googleapis.com/memories.generate` `aiplatform.googleapis.com/memoryRevisions.rollback`
`roles/aiplatform.memoryUser`	授予回憶集和修訂版本的完整存取權，包括所有檢視者和編輯者權限。	包含 `memoryEditor` 和 `memoryViewer` 的所有權限。

搭配使用 IAM 條件與 Memory Bank

本節將說明下列使用 IAM 條件搭配 Memory Bank 的範例：

授予範圍完全相符的回憶集錦讀取權限。
授予記憶體寫入權限，範圍包含特定鍵/值組合。
使用含有特定金鑰的範圍，授予回憶記錄的完整存取權。
授予記憶體完整存取權，範圍包含特定前置字串。
授予記憶體完整存取權，並設定一組允許的值做為鍵的範圍。

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

以下條件會授予個人 userA@gmail.com 檢視權限，但僅限於範圍完全符合 {"userId": "userA"} 的回憶集錦。

也就是說，只要範圍完全是 {"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'。