本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# Amazon S3
Amazon S3 是一种对象存储服务，可将数据以对象形式存储在存储桶中。您可以连接 Amazon S3 存储桶作为托管知识库的数据源，以提取存储在那里的对象。
## 支持的功能
+ 通过单独的元数据文件记录元数据字段
+ 使用文件模式和 S3 密钥前缀的包含和排除内容过滤器
+ 对已添加、更新和删除的内容进行增量内容同步
+ Cross-account 亚马逊 S3 存储桶访问权限
+ Document-level 访问控制 (ACL)，使用客户提供的 ACL 文件
## 先决条件
**在 Amazon S3 中，请确保：**
+ 记下 Amazon S3 存储桶名称和存储桶拥有者的 AWS 账户 ID。该存储桶必须是与您的知识库位于同一 AWS 区域的通用存储桶，并且您必须拥有访问权限。
+ 如果存储桶位于与知识库不同的 AWS 账户中，或者使用客户托管的 KMS 密钥对其进行加密，请配置存储桶策略和（如果适用）KMS 密钥策略，以允许从您的知识库服务角色进行访问。请参阅[跨账户和 KMS-encrypted 访问权限的存储桶策略](#kb-managed-s3-bucket-policies)。
**在您的 AWS 账户中，请确保**：
+ 在知识库的 AWS Identity and Access Management (IAM) role/permissions 策略中包含连接数据源的必要权限。有关所需权限的信息，请参阅[访问数据来源的权限](kb-permissions.md#kb-permissions-access-ds)。
## 跨账户和 KMS-encrypted 访问权限的存储桶策略
如果您的 Amazon S3 存储桶与您的知识库位于不同的 AWS 账户中，或者使用客户托管的 KMS 密钥进行加密，请添加基于资源的策略以授予您的知识库服务角色访问权限。以下示例显示了所需的最少语句。
### Cross-account 存储桶策略
在拥有 Amazon S3 存储桶的账户中，将以下语句添加到存储桶策略中。{{kb-account-id}}替换为创建知识库的账户 ID、{{kb-service-role}}知识库服务角色的{{bucket-name}}名称和存储桶名称。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowBedrockKnowledgeBaseAccess",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::{{kb-account-id}}:role/{{kb-service-role}}"
},
"Action": [
"s3:GetObject",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::{{bucket-name}}",
"arn:aws:s3:::{{bucket-name}}/*"
]
}
]
}
```
有关更多一般指南，请参阅[配置对 Amazon S3 存储桶的访问权限](https://docs.aws.amazon.com/bedrock/latest/userguide/s3-bucket-access.html)。
### 加密存储桶的 KMS 密钥策略
如果您的 Amazon S3 存储桶使用客户托管的 KMS 密钥加密，请在密钥策略中添加以下声明。使用与跨账户存储桶策略相同的占位符。请等待几分钟，让关键策略更改得以传播。
```
{
"Sid": "AllowBedrockKnowledgeBaseKmsAccess",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::{{kb-account-id}}:role/{{kb-service-role}}"
},
"Action": [
"kms:Decrypt",
"kms:DescribeKey"
],
"Resource": "*"
}
```
`"Resource": "*"`此处的范围是策略所关联的密钥。
## 如何设置 Amazon S3 数据源
设置 Amazon S3 数据源涉及以下步骤：
1. **准备好你的水桶。**确认存储桶名称、账户 ID 和（用于跨账户访问）存储桶策略。如果您计划使用文档元数据，请决定`.metadata.json`文件所在的 Amazon S3 前缀。
1. **Connect 数据源。**使用 AWS 管理控制台 或 API 在知识库中创建 Amazon S3 数据源。请参阅[创建数据源](#kb-managed-ds-s3-create)。
1. **（可选）启用文档级访问控制。**根据客户提供的 ACL 文件中定义的用户权限筛选查询结果。请参阅[Document-level 访问控制](kb-managed-ds-s3-acl.md)。
## 创建数据源
------
#### [ Console ]
**将 Amazon S3 存储桶连接到您的托管知识库**
1. 在**数据源**下，为您的数据源提供一个名称。
1. 从数据源下拉列表中选择 **Amazon S3**。
1. 在 “**数据源位置**” 下，选择 Amazon S3 存储桶是位于**此 AWS 账户**还是**其他 AWS 账户**中。
1. 输入存储桶的 Amazon S3 URI。您可以选择 “**浏览 S3**” 来选择存储桶。
1. （可选）输入**元数据文件前缀**，即存储此数据源的文档元数据文件 (`.metadata.json`) 的 Amazon S3 前缀。
1. （可选）扩展 **S3 前缀筛选器模式**以包含或排除特定路径。
1. （可选）展开**文件筛选模式**以添加正则表达式模式以包含或排除特定文件。
1. （可选）要启用文档级访问控制，请选择使用 ACL **控制文档访问权限并提供全局 ACL** 文件的 Amazon S3 URI。此选项在创建后无法更改。有关更多信息，请参阅 [Document-level 访问控制](kb-managed-ds-s3-acl.md)。
------
#### [ API ]
要创建 Amazon S3 数据源，请使用适用于 Amazon Bedrock 构建时终端节点的代理发送[CreateDataSource](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateDataSource.html)请求。以下 AWS Command Line Interface 示例使用前缀和模式筛选器为同一账户中的存储桶创建数据源。有关每个字段的描述，请参阅下面的连接器参数参考。
```
aws bedrock-agent create-data-source \
--name "{{S3-connector}}" \
--knowledge-base-id "{{your-knowledge-base-id}}" \
--data-source-configuration file://s3-managed-connector.json
```
该`s3-managed-connector.json`文件包含以下内容：
```
{
"type": "MANAGED_KNOWLEDGE_BASE_CONNECTOR",
"managedKnowledgeBaseConnectorConfiguration": {
"connectorParameters": {
"type": "S3",
"version": "1",
"connectionConfiguration": {
"bucketName": "{{my-knowledge-base-bucket}}",
"bucketOwnerAccountId": "{{123456789012}}"
},
"filterConfiguration": {
"inclusionPrefixes": ["{{documents/}}"],
"inclusionPatterns": ["{{.*\\.pdf}}", "{{.*\\.txt}}"],
"exclusionPatterns": ["{{.*\\.tmp}}"]
},
"metadataFilesPrefix": "{{metadata/}}"
}
}
}
```
要启用文档级访问控制，`aclEnabled`请设置为`true`并添加带有。`aclConfiguration` `globalAccessControlListS3Uri`请参阅[Document-level 访问控制](kb-managed-ds-s3-acl.md)。
对于托管知识库，`CreateDataSource`这是异步的：操作完成后，数据源状态`AVAILABLE`会从`CREATING`变为。
------
## 连接器参数
数据源配置使用以下连接器参数。要连接到 Amazon S3，请在中指定`S3`为连接器`connectorParameters`。有关换行字段`connectorParameters`（例如`deletionProtectionConfiguration`和`mediaExtractionConfiguration`），请参阅[连接数据来源](kb-managed-connect-ds.md)。
**connectionConfiguration**
| 字段 | 必填 | 描述 |
| --- | --- | --- |
| bucketName | 是 | Amazon S3 桶的名称。 |
| bucketOwnerAccountId | 有条件 | 存储桶拥有者的 AWS 账户 ID。跨账户访问是必需的。 |
**过滤器配置（可选）**
| 字段 | 必填 | 说明 |
| --- | --- | --- |
| inclusionPrefixes | 否 | 要包含的 Amazon S3 密钥前缀列表（例如documents/）。 |
| exclusionPrefixes | 否 | 要排除的 Amazon S3 密钥前缀列表（例如archive/）。 |
| inclusionPatterns | 否 | 正则表达式列表。只有键与至少一种模式匹配的对象才会被摄取。 |
| exclusionPatterns | 否 | 正则表达式列表。不会摄取密钥与任何模式匹配的对象。 |
| maxFileSizeInMegaBytes | 否 | 连接器接收的任何单个文件的最大大小（以兆字节为单位）。以数字字符串形式提供（例如，"500"）。默认值为 "500"。 |
**Top-level 连接器参数（可选）**
| 字段 | 必填 | 说明 |
| --- | --- | --- |
| metadataFilesPrefix | 否 | 存储文档元数据文件 (.metadata.json) 的 Amazon S3 前缀。 |
| aclEnabled | 否 | 设置true为可启用文档级访问控制。创建数据源后，您无法更改此设置。有关更多信息，请参阅 [Document-level 访问控制](kb-managed-ds-s3-acl.md)。 |
| aclConfiguration | 有条件 | 包含 globalAccessControlListS3Uri — 将密钥前缀映射到访问控制条目的 JSON 文件的 Amazon S3 URI。当aclEnabled为时为必填项true；当aclEnabled为时忽略false。请参阅[Document-level 访问控制](kb-managed-ds-s3-acl.md)。 |
### 文档元数据文件
您可以通过在每个文档旁边上传一个 sidecar 文件来将元数据附加到每个文档。为每个文档创建一个名`{{filename.extension}}.metadata.json`为相同的 Amazon S3 路径的文件。元数据文件不得超过 10 KB。例如，在上传的同时`report.pdf`，还要上传`report.pdf.metadata.json`以下内容：
```
{
"metadataAttributes": {
"company": {
"value": {
"type": "STRING",
"stringValue": "BioPharm Innovations"
}
},
"created_date": {
"value": {
"type": "NUMBER",
"numberValue": 20221205
}
},
"author": {
"value": {
"type": "STRING",
"stringValue": "Lisa Thompson"
}
}
}
}
```
有关支持的属性数据类型和可在查询时应用的筛选运算符的信息，请参阅[元数据和筛选](https://docs.aws.amazon.com/bedrock/latest/userguide/kb-test-config.html)。