注意：Vertex AI Search 即将更名为 Agent Search。我们正在更新内容，以反映新品牌。

设置数据源访问权限控制

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

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

例如，假设您公司的员工使用您的搜索应用跨 Confluence 文档进行搜索。不过，您需要确保他们无法通过该应用查看他们无权访问的内容。如果您已在中为您组织的身份提供方设置了员工池，那么您也可以在 Agent Search 中指定该员工池。 Google Cloud 现在，如果员工使用您的应用，他们只会获得其账号在 Confluence 中已有权访问的文档的搜索结果。

数据源访问权限控制简介

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

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

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

Google 身份：
- 场景 1：如果您使用 Google 身份，则所有用户身份和用户群组都存在并会通过 Google Cloud进行管理。如需详细了解 Google 身份，请参阅 Google 身份文档。
- 场景 2：您使用第三方身份提供方，并已将身份同步到 Google 身份。您的最终用户在访问 Google 资源或 Google Workspace 之前，使用 Google 身份进行身份验证。
- 场景 3：您使用第三方身份提供方，并已将身份同步到 Google 身份。不过，您仍在使用现有的第三方身份提供方执行身份验证。您已使用 Google 身份配置了单点登录，以便您的用户开始使用 Google 身份登录，然后被定向到您的第三方身份提供方。（您可能在设置其他 Google Cloud 资源或 Google Workspace 时已完成此同步。）
第三方身份提供方联合：如果您使用外部身份提供方（例如 Microsoft Entra ID、Okta 或 Ping），但不想将身份信息同步到 Google Cloud Identity，则必须先在中设置员工身份联合 Google Cloud ，然后才能为 Agent Search 启用数据源访问权限控制。

如果您使用第三方连接器，则 google.subject属性必须映射到外部身份提供方中的邮箱地址字段。以下是常用身份提供方的 google.subject 和 google.groups 属性映射示例：
- 使用 OIDC 协议的 Microsoft Entra ID
```
google.subject=assertion.email
google.groups=assertion.groups
```
- 使用 SAML 协议的 Microsoft Entra ID
```
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']
```

限制

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

每个文档最多允许有 3,000 个读取者。每个主账号都算作一个读取者，其中主账号可以是群组或个人用户。
您可以为每个 Agent Search 支持的位置选择一个身份提供方。
如需将数据源设置为受访问权限控制，您必须在创建数据存储区时选择此设置。您无法为现有数据存储区开启或关闭此设置。
控制台中的数据 > 文档标签页不会显示受访问权限控制的数据源的数据，因为这些数据应仅对具有查看权限的用户可见。
如需预览使用第三方访问权限控制的搜索应用的界面结果，您必须登录联合控制台。请参阅预览受访问权限控制的应用的结果。

准备工作

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

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

关联身份提供方

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

在 Google Cloud 控制台中，前往 AI Applications 页面。

AI Applications
前往设置 > 身份验证 页面。
点击要更新的位置对应的修改图标。
在添加身份提供方 对话框中选择您的身份提供方。如果您选择第三方身份提供方，请同时选择适用于您的数据源的员工池。
点击保存更改 。

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

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

第三方数据源：创建应用时无需进行其他配置。跳至预览采用第三方访问权限控制的应用的结果
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 中的非结构化数据设置数据存储区时，您需要将数据存储区设置为受访问权限控制，并使用 Agent 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 中的结构化数据设置数据存储区时，您需要将数据存储区设置为受访问权限控制，并使用 Agent 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

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

如需在 Google Cloud 控制台中预览采用第三方访问权限控制的应用的结果，您必须使用组织的凭据登录。

如需预览界面结果，请按以下步骤操作：

在 Google Cloud 控制台中，前往 AI Applications 页面。

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

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

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

向用户授予搜索权限

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

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

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

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

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

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

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

向网域或员工池中需要调用 Search API 的用户授予 Discovery Engine Viewer 角色。
生成授权令牌以传递给您的微件：
- 对于 Google 身份：生成 OAuth 2.0 访问令牌。
- 对于员工身份联合：按照为员工身份联合获取短期有效的令牌中的步骤获取令牌。
按照添加带有授权令牌的微件中的步骤将令牌传递给您的微件。

后续步骤

获取搜索结果。