此页面由 Cloud Translation API 翻译。

使用数据源访问权限控制

本页介绍了如何在 Vertex AI Agent Builder 中为搜索应用强制执行数据源访问权限控制。

在 Vertex AI Agent Builder 中对数据源进行访问控制可限制用户在搜索应用的结果中查看的数据。Google 会使用您的身份提供程序来识别执行搜索的最终用户，并确定他们是否有权访问作为结果返回的文档。

例如，假设贵公司员工使用您的搜索应用搜索 Confluence 文档。不过，您需要确保他们无法通过该应用查看不被允许访问的内容。如果您已在 Google Cloud 中为贵组织的身份提供方设置了员工池，则还可以在 Vertex AI Agent Builder 中指定该员工池。现在，如果员工使用您的应用，他们只能看到其账号在 Confluence 中已有权访问的文档的搜索结果。

数据源访问权限控制简介

开启访问权限控制是一项一次性操作。

访问控制适用于 Cloud Storage、BigQuery、Google 云端硬盘和所有第三方数据源。

如需为 Vertex AI Agent Builder 开启数据源访问权限控制，您必须在 Google Cloud 中配置组织的身份提供程序。支持以下身份验证框架：

Google Identity：如果您使用 Google Identity，则所有用户身份和用户组均通过 Google Cloud 进行呈现和管理。如需详细了解 Google Identity，请参阅 Google Identity 文档。
第三方身份提供方联合：如果您使用外部身份提供方（例如 Okta 或 Azure AD），则必须先在 Google Cloud 中设置员工身份联合，然后才能为 Vertex AI Agent Builder 开启数据源访问权限控制。

如果您使用第三方连接器，google.subject 属性必须映射到外部身份提供程序中的电子邮件地址字段。以下是常用身份提供程序的 google.subject 和 google.groups 属性映射示例：
- 使用 OIDC 协议的 Azure AD
```
google.subject=assertion.email
google.groups=assertion.groups
```
- 使用 SAML 协议的 Azure AD
```
google.subject=assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'][0]
google.groups=assertion.attributes['http://schemas.microsoft.com/ws/2008/06/identity/claims/groups']
```
- 使用 OIDC 协议的 Okta
```
google.subject=assertion.email
google.groups=assertion.groups
```
- 使用 SAML 协议的 Okta
```
google.subject=assertion.subject
google.groups=assertion.attributes['groups']
```

限制

访问权限控制具有以下限制：

每个文档最多有 250 名读者。每个主账号都算作一个读者，主账号可以是群组，也可以是个人用户。
您可以为每个 Vertex AI Search 支持的位置选择一个身份提供程序。
只有在身份提供程序中明确定义的身份和群组才会遵循访问权限控制。不支持在第三方应用中原生定义的身份或群组。
如需将数据源设为受控访问，您必须在创建数据存储区时选择此设置。您无法为现有数据存储区开启或关闭此设置。
控制台中的数据 > 文档标签页不会显示受访问权限控制的数据源的数据，因为只有具有查看权限的用户才能看到这些数据。
如需预览使用第三方访问权限控制的搜索应用的界面结果，您必须登录联合控制台或使用 Web 应用。请参阅预览受访问权限控制的应用的结果。

准备工作

此过程假定您已在 Google Cloud 项目中设置身份提供程序。

Google Identity：如果您使用 Google Identity，可以继续执行连接到身份提供方过程。
第三方身份提供方：确保您已为第三方身份提供方设置员工身份池。设置员工池时，请确保您已指定主题和群组属性映射。如需了解属性映射，请参阅 IAM 文档中的属性映射。如需详细了解员工身份池，请参阅 IAM 文档中的管理员工身份池提供方。

连接到您的身份提供方

如需为 Vertex AI Agent Builder 指定身份提供方并开启数据源访问权限控制，请按以下步骤操作：

在 Google Cloud 控制台中，前往 Agent Builder 页面。

Agent Builder
前往设置 > 身份验证页面。
针对要更新的地理位置，点击添加身份提供方。
在添加身份提供方对话框中，选择您的身份提供方。如果您选择第三方身份提供方，还应选择适用于您的数据源的员工队伍。
点击保存更改。

配置具有访问权限控制的数据源

如需对数据源应用访问权限控制，请根据您要设置的数据源类型，按照以下步骤操作：

第三方数据源：创建应用时无需进行额外配置。请跳至预览具有第三方访问权限控制功能的应用的结果
Google 云端硬盘：创建应用时无需进行其他配置。
Cloud Storage 中的非结构化数据
Cloud Storage 中的结构化数据
来自 BigQuery 的非结构化数据
来自 BigQuery 的结构化数据

Cloud Storage 中的非结构化数据

为 Cloud Storage 中的非结构化数据设置数据存储区时，您还需要上传 ACL 元数据并将数据存储区设置为受控访问：

准备数据时，请使用 acl_info 字段在元数据中添加 ACL 信息。例如：

{
   "id": "<your-id>",
   "jsonData": "<JSON string>",
   "content": {
     "mimeType": "<application/pdf or text/html>",
     "uri": "gs://<your-gcs-bucket>/directory/filename.pdf"
   },
   "acl_info": {
     "readers": [
       {
         "principals": [
           { "group_id": "group_1" },
           { "user_id": "user_1" }
         ]
       }
     ]
   }
 }

如需详细了解包含元数据的非结构化数据，请参阅准备数据以便提取中的“非结构化数据”部分。

按照创建搜索数据存储空间中的数据存储空间创建步骤操作时，您可以在控制台中或使用 API 执行以下操作来启用访问权限控制：
- 控制台：创建数据存储区时，在创建数据存储区期间选择此数据存储区包含访问权限控制信息。
- API：创建数据存储区时，请在 JSON 载荷中添加标志 "aclEnabled": "true"。
在创建搜索数据存储空间中按照数据导入步骤操作时，请务必执行以下操作：
- 将包含 ACL 信息的元数据上传到与非结构化数据相同的存储桶中
- 如果使用 API，请将 GcsSource.dataSchema 设置为 document

Cloud Storage 中的结构化数据

为 Cloud Storage 中的结构化数据设置数据存储区时，您还需要上传 ACL 元数据并将数据存储区设置为受控访问：

准备数据时，请使用 acl_info 字段在元数据中添加 ACL 信息。例如：

{
   "id": "<your-id>",
   "jsonData": "<JSON string>",
   "acl_info": {
     "readers": [
       {
         "principals": [
           { "group_id": "group_1" },
           { "user_id": "user_1" }
         ]
       }
     ]
   }
 }

按照创建搜索数据存储空间中的步骤创建数据存储空间时，您可以在控制台中或使用 API 执行以下操作来启用访问权限控制：
- 控制台：创建数据存储区时，在创建数据存储区期间选择此数据存储区包含访问权限控制信息。
- API：创建数据存储区时，请在 JSON 载荷中添加标志 "aclEnabled": "true"。
在创建搜索数据存储空间中按照数据导入步骤操作时，请务必执行以下操作：
- 将包含 ACL 信息的元数据上传到与非结构化数据相同的存储桶中
- 如果使用 API，请将 GcsSource.dataSchema 设置为 document

来自 BigQuery 的非结构化数据

为 BigQuery 中的非结构化数据设置数据存储区时，您需要将数据存储区设置为受控访问，并使用 Vertex AI Search 的预定义架构提供 ACL 元数据：

准备数据时，请指定以下架构。请勿使用自定义架构。

[
  {
    "name": "id",
    "mode": "REQUIRED",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "jsonData",
    "mode": "NULLABLE",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "content",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "mimeType",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  }
  {
    "name": "acl_info",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "readers",
        "type": "RECORD",
        "mode": "REPEATED",
        "fields": [
          {
            "name": "principals",
            "type": "RECORD",
            "mode": "REPEATED",
            "fields": [
              {
                "name": "user_id",
                "type": "STRING",
                "mode": "NULLABLE"
              },
              {
                "name": "group_id",
                "type": "STRING",
                "mode": "NULLABLE"
              }
            ]
          }
        ]
      }
    ]
  }
]

将 ACL 元数据作为列添加到 BigQuery 表中。
按照创建搜索数据存储空间中的步骤操作时，请在控制台中或使用 API 启用访问权限控制：
- 控制台：创建数据存储区时，在创建数据存储区期间选择此数据存储区包含访问权限控制信息。
- API：创建数据存储区时，请在 JSON 载荷中添加标志 "aclEnabled": "true"。
按照创建搜索数据存储空间中的数据导入步骤操作时，如果使用 API，请将 BigQuerySource.dataSchema 设置为 document。

来自 BigQuery 的结构化数据

为 BigQuery 中的结构化数据设置数据存储区时，您需要将数据存储区设置为受访问控制，并使用 Vertex AI Search 的预定义架构提供 ACL 元数据：

准备数据时，请指定以下架构。请勿使用自定义架构。

[
  {
    "name": "id",
    "mode": "REQUIRED",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "jsonData",
    "mode": "NULLABLE",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "acl_info",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "readers",
        "type": "RECORD",
        "mode": "REPEATED",
        "fields": [
          {
            "name": "principals",
            "type": "RECORD",
            "mode": "REPEATED",
            "fields": [
              {
                "name": "user_id",
                "type": "STRING",
                "mode": "NULLABLE"
              },
              {
                "name": "group_id",
                "type": "STRING",
                "mode": "NULLABLE"
              }
            ]
          }
        ]
      }
    ]
  }
]

将 ACL 元数据作为列添加到 BigQuery 表中。
按照创建搜索数据存储空间中的步骤操作时，请在控制台中或使用 API 启用访问权限控制：
- 控制台：创建数据存储区时，在创建数据存储区期间选择此数据存储区包含访问权限控制信息。
- API：创建数据存储区时，请在 JSON 载荷中添加标志 "aclEnabled": "true"。
在创建搜索数据存储区中按照数据导入步骤操作时，请务必执行以下操作：
- 如果使用控制台，则在指定要上传的数据类型时，选择包含结构化数据及其元数据的 JSONL
- 如果使用 API，请将 BigQuerySource.dataSchema 设置为 document

预览具有第三方访问权限控制功能的应用的结果

如需在控制台内预览具有第三方访问权限控制功能的应用的结果，您需要使用贵组织的凭据登录。

您可以通过两种方式预览界面结果：

“Workforce Identity Federation”控制台。打开“员工身份联合”控制台，然后使用您的第三方凭据登录。请参阅在员工身份联合控制台中预览结果。
Web 应用。启用并登录 Vertex AI Search 提供的专用 Web 应用。请参阅开启 Web 应用。

在员工身份联合控制台中预览结果

如需使用员工身份联合控制台查看结果，请按以下步骤操作：

在 Google Cloud 控制台中，前往 Agent Builder 页面。

Agent Builder
点击您要预览其搜索结果的搜索应用的名称。
前往预览页面。
点击以联合身份预览，前往员工身份联合控制台。
输入您的员工池提供方和组织的凭据。
在随即显示的预览页面上预览应用的结果。

如需详细了解如何预览搜索结果，请参阅获取搜索结果。

如需详细了解员工身份联合控制台，请参阅控制台（联合）简介。

向用户授予搜索权限

如需让用户能够使用您的应用搜索受访问权限控制的数据，您需要向网域或员工池中的用户授予访问权限。Google 建议您向用户群组授予自定义 IAM 角色。

Google 身份：如果您使用的是 Google 身份，Google 建议您创建一个包含需要进行搜索的所有员工的 Google 群组。如果您是 Google Workspace 管理员，则可以按照将组织中的所有用户添加到群组中的步骤，将组织中的所有用户添加到 Google 群组中。
第三方身份提供方：如果您使用外部身份提供方（例如 Okta 或 Azure AD），请将员工身份池中的所有人添加到一个群组。

Google 建议您创建一个自定义 IAM 角色，并向用户群组授予以下权限：

discoveryengine.answers.get
discoveryengine.servingConfigs.answer
discoveryengine.servingConfigs.search
discoveryengine.sessions.get

如需详细了解使用 Identity and Access Management (IAM) 的 Vertex AI Agent Builder 资源的权限，请参阅使用 IAM 进行访问权限控制。

如需详细了解自定义角色，请参阅 IAM 文档中的自定义角色。

如果您想为受访问权限控制的应用部署搜索微件，请按以下步骤操作：

向您网域或员工队伍中需要发出搜索 API 调用的用户授予“发现引擎查看者”角色。
生成要传递给微件的授权令牌：
- 对于 Google Identity：生成 OAuth 2.0 访问令牌。
- 对于员工身份联合：请按照为员工身份联合获取短期令牌中的步骤获取令牌。
按照添加包含授权令牌的 widget 中的步骤将令牌传递给 widget。

开启 Web 应用

该 Web 应用是由 Vertex AI Search 生成的专用网站，您和拥有登录凭据的任何其他用户都可以在该网站上使用您的搜索应用。

如需向用户提供搜索应用，而无需在您自己的应用中集成搜索微件或搜索 API，您可以向用户提供 Web 应用网址。

如需开启 Web 应用，请按以下步骤操作：

在 Google Cloud 控制台中，前往 Agent Builder 页面。

Agent Builder
点击要为其创建 Web 应用的搜索应用的名称。

搜索应用必须与至少一个具有访问控制权限的数据源相关联。如需了解详情，请参阅配置具有访问控制功能的数据源。
依次前往集成 > 界面标签页。
点击启用 Web 应用。
如果您使用的是员工身份联合，请选择员工池提供方。
点击指向您的 Web 应用的链接。
输入您的员工池提供方和组织的凭据。
预览应用的结果。
如需为 Web 应用配置结果，请参阅为搜索微件配置结果。微件的所有配置也适用于 Web 应用。
可选：如需通过此专用 Web 应用向用户提供搜索应用，请复制网址并将其发送给拥有登录凭据的用户。用户可以将 Web 应用网址添加为书签，然后访问该网址以使用您的搜索应用。

如需详细了解如何获取搜索结果，请参阅获取搜索结果。