本页面介绍了如何在 Vertex AI Search 中为搜索应用强制执行数据源访问权限控制。
Vertex AI Search 中数据源的访问权限控制功能可限制用户在搜索应用的结果中查看的数据。Google 会使用您的身份提供方来识别执行搜索的最终用户，并确定他们是否有权访问作为搜索结果返回的文档。
例如，假设贵公司的员工使用您的搜索应用搜索 Confluence 文档。不过，您需要确保他们无法通过该应用查看他们无权访问的内容。如果您已在 Google Cloud 中为组织的身份提供方设置了员工池，那么您也可以在 Vertex AI Search 中指定该员工池。现在，如果员工使用您的应用，他们只会获得其账号在 Confluence 中已有权访问的文档的搜索结果。
数据源访问权限控制简介
启用访问权限控制是一次性操作。
访问权限控制适用于 Cloud Storage、BigQuery、Google 云端硬盘和所有第三方数据源。
如需为 Vertex AI Search 启用数据源访问权限控制，您必须在 Google Cloud中配置组织的身份提供方。支持以下身份验证框架：
Google 身份：
情形 1：如果您使用 Google 身份，则所有用户身份和用户组都存在，并且通过 Google Cloud进行管理。如需详细了解 Google Identity，请参阅 Google Identity 文档。
情形 2：您使用的是第三方身份提供方，并且已将身份与 Google Identity 同步。最终用户在访问 Google 资源或 Google Workspace 之前，需要使用 Google 身份进行身份验证。
情形 3：您使用的是第三方身份提供方，并且已将身份与 Google 身份同步。不过，您仍在使用现有的第三方身份提供商进行身份验证。您已配置了使用 Google Identity 的 SSO，以便用户先使用 Google Identity 开始登录，然后被重定向到您的第三方身份提供商。（您可能在设置其他 Google Cloud 资源或 Google Workspace 时已完成此同步。）
第三方身份提供方联合：如果您使用外部身份提供方（例如 Azure AD、Okta 或 Ping），但不想将身份同步到 Google Cloud Identity，则必须先在 Google Cloud中设置员工身份联合，然后才能为 Vertex AI Search 启用数据源访问权限控制。
如果您使用第三方连接器，则
google.subject属性必须映射到外部身份提供商中的电子邮件地址字段。以下是常用身份提供方的google.subject和google.groups属性映射示例：google.subject=assertion.email google.groups=assertion.groupsgoogle.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']google.subject=assertion.email google.groups=assertion.groupsgoogle.subject=assertion.subject google.groups=assertion.attributes['groups']
限制
访问权限控制具有以下限制：
- 每个文档最多允许有 3,000 个读取者。每个主账号都算作一个读取者，其中主账号可以是群组或个人用户。
- 您可以为每个受 Vertex AI Search 支持的位置选择一个身份提供方。
- 如需将数据源设置为受访问权限控制，您必须在创建数据存储区时选择此设置。您无法为现有数据存储区开启或关闭此设置。
- 控制台中的数据 > 文档标签页不会显示访问受控数据源的数据，因为这些数据应仅对具有查看权限的用户可见。
- 如需预览使用第三方访问权限控制的搜索应用的界面结果，您必须登录联合控制台或使用 Web 应用。请参阅预览受访问权限控制的应用的结果。
准备工作
此过程假定您已在Google Cloud 项目中设置身份提供方。
- Google Identity：如果您使用 Google Identity，可以继续执行连接到身份提供方程序。
- 第三方身份提供方：确保您已为第三方身份提供方设置员工身份池。验证您在设置员工池时是否已指定正文和群组属性映射。 如需了解属性映射，请参阅 IAM 文档中的属性映射。如需详细了解员工身份池，请参阅 IAM 文档中的管理员工身份池提供方。
关联身份提供方
如需为 Vertex AI Search 指定身份提供方并开启数据源访问权限控制，请按以下步骤操作：
在 Google Cloud 控制台中，前往 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 的非结构化数据设置数据存储区时，您需要将数据存储区设置为受访问权限控制，并使用 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
预览采用第三方访问权限控制的应用的结果
如需在控制台中预览采用第三方访问权限控制的应用的结果，您必须使用组织的凭据登录。
您可以通过两种方式预览界面结果：
- 员工身份联合控制台。打开员工身份联合控制台，然后使用您的第三方凭据登录。请参阅在员工身份联合控制台中预览结果。
- Web 应用。启用并登录 Vertex AI Search 提供的专用 Web 应用。请参阅启用 Web 应用。
在员工身份联合控制台中预览结果
如需使用员工身份联合控制台查看结果，请按以下步骤操作：
在 Google Cloud 控制台中，前往 AI Applications 页面。
点击要预览其搜索结果的搜索应用的名称。
前往预览页面。
点击以联合身份预览，前往员工身份联合控制台。
输入员工池提供方和组织的凭据。
在随即显示的预览页面上，预览应用的结果。
如需详细了解如何预览搜索结果，请参阅获取搜索结果。
如需详细了解员工身份联合控制台，请参阅控制台（联合）简介。
向用户授予搜索权限
如需让用户能够使用您的应用搜索受访问权限控制的数据，您需要向网域或员工池中的用户授予访问权限。Google 建议您向用户群组授予自定义 IAM 角色。
- Google 身份：如果您使用 Google 身份，Google 建议您创建一个 Google 群组，其中包含需要进行搜索的所有员工。如果您是 Google Workspace 管理员，可以按照将组织中的所有用户添加到一个群组中中的步骤，将组织中的所有用户都添加到某个 Google 群组中。
- 第三方身份提供方：如果您使用外部身份提供方（例如 Okta 或 Azure AD），请将员工身份池中的所有人都添加到单个群组。
Google 建议您创建自定义 IAM 角色并授予用户群组，使用以下权限：
discoveryengine.answers.getdiscoveryengine.servingConfigs.answerdiscoveryengine.servingConfigs.searchdiscoveryengine.sessions.getdiscoveryengine.widgetConfigs.get
如需详细了解如何使用 Identity and Access Management (IAM) 为 Vertex AI Search 资源设置权限，请参阅使用 IAM 进行访问权限控制。
如需详细了解自定义角色，请参阅 IAM 文档中的自定义角色。
授权搜索微件
如果您想为受访问权限控制的应用部署搜索 widget，请按以下步骤操作：
向网域或员工池中需要进行搜索 API 调用的用户授予 Discovery Engine Viewer 角色。
生成授权令牌以传递给 widget：
- 对于 Google Identity：生成 OAuth 2.0 访问令牌。
- 对于员工身份联合：请按照为员工身份联合获取短期令牌中的步骤获取令牌。
按照添加具有授权令牌的 widget 中的步骤操作，将令牌传递给 widget。
开启 Web 应用
Web 应用是 Vertex AI Search 生成的专用网站，您和任何其他拥有登录凭据的用户都可以在其中使用您的搜索应用。
如需向用户提供搜索应用，而无需在自己的应用中集成搜索 widget 或搜索 API，您可以向用户提供 Web 应用网址。
如需启用 Web 应用，请按以下步骤操作：
在 Google Cloud 控制台中，前往 AI Applications 页面。
点击要为其创建 Web 应用的搜索应用的名称。
搜索应用必须与至少一个具有访问权限控制的数据源相关联。如需了解详情，请参阅配置具有访问权限控制的数据源。
前往集成 > 界面标签页。
点击启用 Web 应用。
如果您使用的是员工身份联合，请选择员工身份池提供方。
点击指向您 Web 应用的链接。
输入员工池提供方和组织的凭据。
预览应用的结果。
如需为 Web 应用配置结果，请参阅为搜索微件配置结果。微件的任何配置也适用于 Web 应用。
可选：如需通过此专用 Web 应用向用户提供搜索应用，请复制网址并将其发送给拥有登录凭据的用户。他们可以将 Web 应用网址加入书签，然后前往该网址以使用您的搜索应用。
如需详细了解如何获取搜索结果，请参阅获取搜索结果。