此页面由 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 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 身份：如果您使用 Google 身份，则可以继续连接到身份提供方程序。
第三方身份提供方：确保您已设置员工身份池。设置员工池时，请确保您已指定主题和群组属性映射。如需了解属性映射，请参阅属性映射。如需详细了解员工身份池，请参阅 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 字段。例如：

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

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

来自 BigQuery 的非结构化数据

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

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

[
  {
    "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：创建数据存储区时，请添加标志 "aclEnabled": "true" 。
按照创建搜索数据存储空间中的数据导入步骤操作时，如果使用 API，请将 BigQuerySource.dataSchema 设置为 document。

BigQuery 中的结构化数据

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

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

[
  {
    "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)，请参阅使用 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 应用配置结果，请参阅针对搜索微件。该 widget 的任何配置也包括适用于 Web 应用
可选：如需通过此专用 Web 应用向用户提供搜索应用，请复制网址并将其发送给拥有登录凭据的用户。他们可以将该 Web 应用网址加入书签，并转到该网址使用您的搜索应用。

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