本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 文件層級存取控制
<a name="kb-managed-ds-custom-acl"></a>

**ACL 意識不是授權**  
Bedrock 受管知識庫提供 ACL 感知篩選，而不是安全界限。Bedrock 受管知識庫不會驗證最終使用者 — 您的應用程式負責驗證使用者並傳遞已驗證的身分內容。由於 Bedrock 受管知識庫無法驗證您提供的使用者內容的真實性，因此此功能會根據您提供的身分篩選結果，但不會構成真正的授權。在沒有上游身分驗證的情況下，您不得依賴此功能做為唯一存取控制機制。

自訂資料來源可選擇性支援文件層級存取控制。與抓取連接器不同，自訂資料來源沒有原生許可系統，因此當您使用 `IngestKnowledgeBaseDocuments`操作擷取每個文件時，您會提供存取控制清單 (ACL)。如需所有連接器的 ACL 意識概觀，請參閱 [存取控制清單意識啟用](kb-managed-acl.md)。

## 運作方式
<a name="kb-managed-ds-custom-acl-how"></a>

對於啟用 ACL 的自訂資料來源，Bedrock 受管知識庫會在擷取前篩選期間套用客戶提供的存取控制清單，僅傳回查詢使用者允許存取的文件。自訂資料來源不支援即時 ACL 驗證，因為客戶提供的 ACL 中繼資料是事實來源。

## 啟用 ACL 意識
<a name="kb-managed-ds-custom-acl-enable"></a>

若要啟用自訂資料來源的 ACL 意識，請在建立或更新資料來源`connectorParameters`時，在 `true`中將 `aclEnabled`設定為 。如需資料來源組態結構，請參閱 [Custom](kb-managed-ds-custom.md)。

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

## 擷取文件時提供存取控制
<a name="kb-managed-ds-custom-acl-ingest"></a>

您可以透過`IngestKnowledgeBaseDocuments`請求`metadata`中文件 的 `accessControlList` 欄位提供文件的 ACL。ACL 來源由 決定`metadata.type`，該欄位控制中繼資料屬性的來源：
+ **`IN_LINE_ATTRIBUTE`** — 從請求內文中的`accessControlList`陣列讀取 ACL。
+ **`S3_LOCATION`** — 從 Amazon S3 文件`.metadata.json`檔案中的`accessControlList`陣列讀取 ACL。

由於 `accessControlList`位於 之下，`metadata`而不是 的頂層欄位`KnowledgeBaseDocument`，因此文件具有單一 ACL 來源，由 控制`metadata.type`。這可防止為相同的文件提供衝突ACLs （例如，請求上的內嵌 ACL 和 S3 檔案中的 ACL)。權衡是您無法針對相同文件混合內嵌 ACL 與以 S3-based中繼資料屬性，或以 S3-based ACL 與內嵌中繼資料屬性。

每個`accessControlList`項目都包含：
+ `name` — 使用者的電子郵件地址。
+ `type` — 必須是 `USER`。
+ `access` — `ALLOW`或 `DENY`。拒絕覆寫允許。

### 內嵌 ACL (metadata.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 (metadata.type = 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>

由於自訂 ACLs 是透過 客戶提供`IngestKnowledgeBaseDocuments`，因此請在查詢之前驗證它們：

1. 確認 `aclEnabled` 位於資料來源的 `connectorParameters`(`type`) `true`中`CUSTOM`。

1. 確認每個擷取的文件都包含 `accessControlList`下的 `metadata`，且`metadata.type`符合 ACL 來源 (`IN_LINE_ATTRIBUTE` 代表內嵌， `S3_LOCATION` 代表 S3 檔案）。

1. 確認 ACL 項目欄位大小寫符合來源：內嵌 ACLs 為小寫 `name`/`type`/`access`，S3 `.metadata.json` 檔案為大寫 `Name`/`Type`/`Access`。

1. 針對您希望使用者擷取的文件，確認測試使用者的電子郵件完全符合 `ALLOW` 項目`name`中的 。

## 疑難排解
<a name="kb-managed-ds-custom-acl-troubleshooting"></a>

**注意**  
ACL 設定錯誤不會在擷取期間產生明確的錯誤。擷取失敗關閉：已無提示地省略受影響的文件，因此查詢會傳回較少或零的結果，而不是錯誤。使用上述驗證檢查來診斷這些問題。


**啟用 ACL 的自訂症狀、原因和修正**  

| 徵狀 | 可能原因 | 修正 | 
| --- | --- | --- | 
| 擷取應為應具有存取權的使用者傳回 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。 | 使用 重新擷取文件accessControlList。 |