本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# ACL-aware 在托管知识库上检索
<a name="kb-test-retrieve-acl"></a>

在托管知识库数据源上启用 ACL 感知后，您可以通过在[检索](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Retrieve.html)请求中传递用户上下文来筛选查询结果。Bedrock 托管知识库仅返回允许提供的用户访问的文档。有关 ACL 感知的工作原理、身份模型、连接器支持以及您在启用 ACL 感知时的职责的概述，请参阅[访问控制列表感知启用](kb-managed-acl.md)。

**重要**  
ACL 感知提供 ACL-aware 的是过滤而不是授权。Bedrock 托管知识库不对最终用户进行身份验证——您的应用程序必须对用户进行身份验证并通过经过验证的身份上下文。有关更多信息，请参阅 [访问控制列表感知启用](kb-managed-acl.md)。

## 在检索请求中使用用户上下文
<a name="kb-test-retrieve-acl-api"></a>

要执行 ACL-aware 检索，请在您的[检索](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Retrieve.html)请求中包含该`userContext`字段。`userContext`指定用户的身份。始终`userId`是用户与底层数据源关联的通用电子邮件地址。

```
{
    "knowledgeBaseId": "{{your-knowledge-base-id}}",
    "retrievalQuery": {
        "text": "{{your query}}"
    },
    "userContext": {
        "userId": "{{user@example.com}}"
    }
}
```

如果您未在 “检索” 请求`userContext`中提供，则 ACL-enabled 数据源将返回零结果。 Non-ACL 同一知识库中的数据源会正常返回结果。

## 使用 ACL 的检索行为
<a name="kb-test-retrieve-acl-behavior"></a>

启用 ACL 感知后，以下行为适用：
+ ** ACL-enabled 数据源所需的用户上下文**-如果您未在 “检索” 请求中提供用户上下文，则 ACL-enabled 数据源将返回零结果。 Non-ACL 同一知识库中的数据源会正常返回结果。
+ **缺少 ACL 元数据意味着无法访问** — 如果 ACL-enabled 数据源中的文档没有 ACL（例如，连接器未能提取权限或该文档是公开的），则该文档不会返回给任何用户。缺少的权限被视为受限权限，而不是公开权限。
+ **混合数据源**-您可以在同一个知识库中同时使用两个数据源 ACL-enabled 和非 ACL 数据源。无论用户上下文如何，来自非 ACL 数据源的文档都会返回给所有用户。
+ **部分结果**-当实时 ACL 验证拒绝访问某些文档时，响应中包含的结果可能少于请求的结果`maxResults`。Bedrock 托管知识库不会填充其他文档。您的应用程序处理的响应结果应少于请求的结果。
+ **拒绝覆盖允许**-如果用户同时出现在文档的允许列表和拒绝列表中，则访问将被拒绝。

**注意**  
Third-party 身份提供商凭证最多可缓存 1 小时。访问可以继续，直到缓存刷新。  
对访问控制权限的更改最终是一致的。更新通常会在几分钟内生效。

## 问题排查
<a name="kb-test-retrieve-acl-troubleshooting"></a>

如果 ACL-aware 检索未返回任何结果或意外结果，则原因通常是特定于连接器的，即权限、凭据或 ACL 配置。请参阅您的连接器的故障排除指南：
+ [SharePoint](kb-managed-ds-sharepoint-acl.md#kb-managed-ds-sharepoint-acl-troubleshooting)
+ [OneDrive](kb-managed-ds-onedrive-acl.md#kb-managed-ds-onedrive-acl-troubleshooting)
+ [Google Drive](kb-managed-ds-googledrive-acl.md#kb-managed-ds-googledrive-acl-troubleshooting)
+ [Confluence](kb-managed-ds-confluence-acl.md#kb-managed-ds-confluence-acl-troubleshooting)
+ [Amazon S3](kb-managed-ds-s3-acl.md#kb-managed-ds-s3-acl-troubleshooting)
+ [自定义](kb-managed-ds-custom-acl.md#kb-managed-ds-custom-acl-troubleshooting)