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

# Document-level 访问控制
<a name="kb-managed-ds-custom-acl"></a>

**ACL 感知不是授权**  
Bedrock 托管知识库提供 ACL-aware 筛选功能，而不是安全边界。Bedrock Managed Knowledge Base 不对最终用户进行身份验证——您的应用程序负责对用户进行身份验证并传递经过验证的身份上下文。由于 Bedrock Managed Knowledge Base 无法验证您提供的用户上下文的真实性，因此此功能会根据您提供的身份筛选结果，但并不构成真正的授权。如果没有上游身份验证，则不得依赖此功能作为唯一的访问控制机制。

自定义数据源可以选择支持文档级访问控制。与爬网连接器不同，自定义数据源没有本机权限系统，因此在操作中摄取每个文档时，您需要为每个文档提供访问控制列表 (ACL)。`IngestKnowledgeBaseDocuments`有关所有连接器的 ACL 感知概述，请参阅[访问控制列表感知启用](kb-managed-acl.md)。

## 工作原理
<a name="kb-managed-ds-custom-acl-how"></a>

对于 ACL-enabled 自定义数据源，Bedrock Managed Knowledge Base 在检索前筛选期间应用客户提供的访问控制列表，仅返回允许查询用户访问的文档。 Real-time 自定义数据源不支持 ACL 验证，因为客户提供的 ACL 元数据是真实来源。

## 启用 ACL 感知
<a name="kb-managed-ds-custom-acl-enable"></a>

要为自定义数据源启用 ACL 感知，请在创建或更新数据源`connectorParameters`时`aclEnabled`将其`true`设置为。有关数据源的配置结构，请参见[自定义](kb-managed-ds-custom.md)。

```
"connectorParameters": {
    "type": "CUSTOM",
    "version": "1",
    "aclEnabled": true
}
```

## 在摄取文档时提供访问控制
<a name="kb-managed-ds-custom-acl-ingest"></a>

您可以通过`IngestKnowledgeBaseDocuments`请求中文档上的`accessControlList`字段提供文档`metadata`的 ACL。ACL 来源由`metadata.type`控制元数据属性来源的同一字段确定：
+ **`IN_LINE_ATTRIBUTE`**— ACL 是从请求正文中的`accessControlList`数组中读取的。
+ **`S3_LOCATION`**— ACL 是从 Amazon S3 中文档`.metadata.json`文件中的`accessControlList`数组中读取的。

由于`accessControlList`文档位于`metadata`而不是顶层字段之下`KnowledgeBaseDocument`，因此文档只有一个 ACL 源，由控制`metadata.type`。这样可以防止为同一文档提供相互冲突的 ACL（例如，请求中的内联 ACL 和 S3 文件中的 ACL）。权衡之处在于，对于同一文档，您不能将内联 ACL 与 S3-based 元数据属性混用，或 S3-based 将 ACL 与内联元数据属性混用。

每个`accessControlList`条目都包含：
+ `name`— 用户的电子邮件地址。
+ `type`— 一定是`USER`。
+ `access`— 要`ALLOW`么是`DENY`。拒绝覆盖允许。

### 内联 ACL（元数据.type = IN\_LINE\_ATTRIBUTE）
<a name="kb-managed-ds-custom-acl-inline"></a>

`accessControlList`直接在请求正文中提供内联元数据属性的旁边。

```
PUT /knowledgebases/{{KB12345678}}/datasources/{{DS12345678}}/documents HTTP/1.1
Content-type: application/json

{
    "documents": [
        {
            "content": {
                "dataSourceType": "CUSTOM",
                "custom": {
                    "customDocumentIdentifier": {
                        "id": "hr-policy-2026"
                    },
                    "inlineContent": {
                        "textContent": {
                            "data": "Annual leave policy: All full-time employees are entitled to..."
                        },
                        "type": "TEXT"
                    },
                    "sourceType": "IN_LINE"
                }
            },
            "metadata": {
                "type": "IN_LINE_ATTRIBUTE",
                "inlineAttributes": [
                    {
                        "key": "department",
                        "value": { "stringValue": "HR", "type": "STRING" }
                    }
                ],
                "accessControlList": [
                    {
                        "name": "{{alice@example.com}}",
                        "type": "USER",
                        "access": "ALLOW"
                    },
                    {
                        "name": "{{bob@example.com}}",
                        "type": "USER",
                        "access": "DENY"
                    }
                ]
            }
        }
    ]
}
```

### S3-based ACL（元数据类型 = S3\_LOCATION）
<a name="kb-managed-ds-custom-acl-s3"></a>

将文档的元数据指向 Amazon S3 中的某个`.metadata.json`文件。元数据属性和`accessControlList`都是从该文件中读取的。

```
"metadata": {
    "type": "S3_LOCATION",
    "s3Location": {
        "uri": "s3://{{amzn-s3-demo-bucket}}/{{hr-policy-2026}}.metadata.json"
    }
}
```

该`.metadata.json`文件使用的格式与 Amazon S3 数据源的[每个文档的元数据文件](kb-managed-ds-s3-acl.md#kb-managed-ds-s3-acl-perdoc)格式相同。此文件使用大写的 ACL 字段名 (`Name``Type`,,`Access`)，这与内联请求中使用的小写字段名 (`name``type`、、`access`) 不同。

```
{
    "metadataAttributes": {},
    "accessControlList": [
        {
            "Name": "{{alice@example.com}}",
            "Type": "USER",
            "Access": "ALLOW"
        },
        {
            "Name": "{{bob@example.com}}",
            "Type": "USER",
            "Access": "DENY"
        }
    ]
}
```

## 验证配置
<a name="kb-managed-ds-custom-acl-verify"></a>

由于自定义 ACL 是客户通过提供的`IngestKnowledgeBaseDocuments`，因此请在查询之前对其进行验证：

1. 确认`aclEnabled``true`在数据源的 `connectorParameters` (`type``CUSTOM`) 中。

1. 确认每份收录的文档都包含一个与 ACL 源相`metadata.type`匹配的`accessControlList`底`metadata`部（`IN_LINE_ATTRIBUTE`对于内联文件，`S3_LOCATION`对于 S3 文件）。

1. 确认 ACL 条目字段大小写与来源相匹配：内联 ACL 小写`type`/`name`/`access`，S3 文件大写`Type`/`Name`/`Access`。`.metadata.json`

1. 确认测试用户的电子邮件与您希望他们检索的文档`ALLOW`条目`name`中的电子邮件完全匹配。

## 问题排查
<a name="kb-managed-ds-custom-acl-troubleshooting"></a>

**注意**  
ACL 配置错误不会在检索过程中产生明显的错误。检索失败关闭：受影响的文档被静默省略，因此查询返回的结果较少或为零，而不是错误。使用上面的验证检查来诊断这些问题。


**ACL-enabled 自定义症状、原因和修复方法**  

| 症状 | 可能的原因 | Fix | 
| --- | --- | --- | 
| 对于本应具有访问权限的用户，检索会返回 0 个结果。 | 该userId电子邮件与任何accessControlList条目都不匹配。 | 将用户的电子邮件与ALLOW条目name中的对齐。 | 
| 内联 ACL 被拒绝或忽略。 | 字段大小写错误，或者不metadata.type是IN\_LINE\_ATTRIBUTE。 | 使用小写的name/type/access并设置metadata.type为。IN\_LINE\_ATTRIBUTE | 
| 未应用 S3-based ACL。 | metadata.type不是S3\_LOCATION，或者.metadata.json文件丢失accessControlList。 | 设置metadata.type为S3\_LOCATION并包含accessControlList在文件中。 | 
| 文件永远不会退还给任何人。 | 该文档是在没有. accessControlList  | Re-ingest 带有accessControlList. 的文档 |