本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 从Amazon QLDB 导出日记账数据
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
Amazon QLDB 使用不可变的事务日志（称为*日记账*）进行数据存储。日记账会跟踪已提交数据的每一次更改，并保存完整、可验证的更改历史记录。
您可以访问分类账中的日记账内容，以进行各种用途，包括分析、审计、数据保留、验证，以及导出到其他系统。以下主题描述了如何将您 AWS 账户中的日记账[区块](journal-contents.md)导出到您的 Amazon Simple Storage Service（Amazon S3）存储桶中。日记账导出作业将您的数据以 [Amazon Ion](ion.md) 格式的文本或二进制表示，或 *JSON Lines* 文本格式的形式写入 Amazon S3 中作为对象。
在 JSON 行格式中，导出的数据对象中的每个区块都是由换行符分隔的有效 JSON 对象。您可以使用这种格式将 JSON 导出与 Amazon Athena 等分析工具直接集成，因为这些服务可以自动解析以换行 AWS Glue 符分隔的 JSON。有关数据格式的更多信息，请参阅 [JSON 行](https://jsonlines.org/)。
有关 Amazon S3 的更多信息，请参阅 [Amazon Simple Storage Service 用户指南](https://docs.aws.amazon.com/AmazonS3/latest/userguide/)。
**注意**
如果您将 JSON 指定为导出作业的输出格式，QLDB 会将 Ion 日记账数据在导出的数据对象中将其转换为 JSON 格式。有关更多信息，请参阅[向下转换至 JSON](export-journal.output.md#export-journal.output.json)。
**Topics**
+ [请求在 QLDB 中导出日记账](export-journal.request.md)
+ [QLDB 中的日记账导出输出](export-journal.output.md)
+ [QLDB 中的日记账导出权限](export-journal.perms.md)
+ [日记账导出的常见错误](export-journal.errors.md)
# 请求在 QLDB 中导出日记账
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
Amazon QLDB 提供了一个 API，用于请求导出指定日期和时间范围以及指定的 Amazon S3 存储桶目标的日记账区块。日记账导出作业可以以 [Amazon Ion](ion.md) 格式的文本或二进制形式或 [JSON 行](https://jsonlines.org/)文本格式写入数据对象。您可以使用 AWS 管理控制台、S AWS DK 或 AWS Command Line Interface (AWS CLI) 来创建导出任务。
**Topics**
+ [AWS 管理控制台](#export-journal.request.con)
+ [QLDB API](#export-journal.request.api)
+ [导出作业到期](#export-journal.request.expiration)
## AWS 管理控制台
请按照以下步骤使用 QLDB 控制台在 QLDB 中提交日记账导出请求。
**请求导出（控制台）**
1. [登录并打开亚马逊 QLDB 控制台，网址为 /qldb。 AWS 管理控制台 https://console.aws.amazon.com](https://console.aws.amazon.com/qldb)
1. 在导航窗格中，选择 **导出**。
1. 选择 **创建导出作业**。
1. 在**创建导出作业**页面上，输入以下导出设置：
+ **分类账** - 要导出其日记账区块的分类帐。
+ **开始日期和时间** - 要导出的日记账数据块范围的起始时间戳（协调世界时（UTC））。此时间戳必须早于**结束日期和时间**。如果您提供的开始时间戳早于分类账的 `CreationDateTime`，QLDB 会将其默认为分类账的 `CreationDateTime`。
+ **结束日期和时间** - 要导出的日记账区块范围的独占结束时间戳（UTC）。此日期和时间不能是未来的时间。
+ **日记账区块的目标** — 您的导出作业写入数据对象的 Amazon S3 存储桶和前缀名称。使用以下 Amazon S3 URI 格式。
```
s3://amzn-s3-demo-qldb-cloudtrail/prefix/
```
您必须为输出对象指定 S3 存储桶名称和可选的前缀名称。以下是示例。
```
s3://amzn-s3-demo-qldb-cloudtrail/journalExport/
```
存储桶名称和前缀都必须符合 Amazon S3 命名规则和惯例。有关命名存储桶更多信息，请参阅 *Amazon Simple Storage Service 开发人员指南*中的[存储桶限制和约束](https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html)。有关更多信息，请参阅[对象键和元数据](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)。
**注意**
不支持跨区域查询。指定的 Amazon S3 存储桶必须与您的账本 AWS 区域 相同。
+ **S3 加**密 - 您的导出作业在 Amazon S3 存储桶中写入数据时使用的加密设置。有关在 Amazon S3 中使用服务器端加密选项的信息，请参阅 *Amazon S3 开发人员指南* 中的[使用服务器端加密保护数据](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)。
+ **存储桶默认加密** - 使用指定 Amazon S3 存储桶的默认加密设置。
+ **AES-256** ‐ 具有 Amazon S3 托管密钥的服务器端加密（SSE-S3）。
+ **AWS-KMS** — 使用带有 AWS KMS 托管密钥的服务器端加密 (SSE-KMS)。
如果您选择此类型，并选择**选择不同的 AWS KMS key**某个选项，则您还必须在以下 Amazon资源名称（ARN）格式中指定对称加密的 KMS 密钥。
```
arn:aws:kms:aws-region:account-id:key/key-id
```
+ **服务访问权限**：在您的 Amazon S3 存储桶中授予 QLDB 写入权限的 IAM 角色。如果适用，IAM 角色还必须授予 QLDB 使用您的 KMS 密钥的权限。
要在请求日记账导出时将角色传递给 QLDB，您必须具有对 IAM 角色资源执行 `iam:PassRole` 操作的权限。
+ **创建和使用新的服务角色** — 让控制台为您创建一个具有指定 Amazon S3 存储桶所需权限的新角色。
+ **使用现有的服务角色**-要了解如何在 IAM 中手动创建此角色，请参阅[导出权限](export-journal.perms.md)。
+ **输出格式** - 导出的日记账数据的输出格式
+ **Ion 文本** -（默认）Amazon Ion 的文本表示形式
+ **Ion 二进制** — Amazon Ion 的二进制表示
+ **JSON** - 以换行符分隔的 JSON 文本格式
如果您选择 JSON，QLDB 会在导出的数据对象中将 Ion 日记账数据向下转换为 JSON。有关更多信息，请参阅[向下转换至 JSON](export-journal.output.md#export-journal.output.json)。
1. 根据需要进行设置后，选择 **创建导出作业**。
完成导出作业所需的时间取决于数据大小。如果您的请求提交成功，控制台将返回主**导出**页面，并列出您的导出作业及其当前状态。
1. 您可以在 Amazon S3 控制台上查看导出对象。
打开 Amazon S3 控制台，网址为 [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
要了解有关这些输出对象格式的更多信息，请参阅 [QLDB 中的日记账导出输出](export-journal.output.md)。
**注意**
导出作业将在完成七天后过期。有关更多信息，请参阅[导出作业到期](#export-journal.request.expiration)。
## QLDB API
您也可以使用带软件开发工具包的 Amazon QLDB API 或者，请求日记导出。 AWS AWS CLI QLDB API 提供以下操作以供应用程序使用：
+ `ExportJournalToS3`— 将日期和时间范围内的日记账内容从给定分类账导出到指定的 Amazon S3 存储桶。导出作业可以 Amazon Ion 格式的文本或二进制形式或 JSON 行文本格式写入数据对象。
+ `DescribeJournalS3Export`— 返回有关日记账导出作业的详细信息。输出包括其当前状态、创建时间和原始导出请求的参数。
+ `ListJournalS3Exports`— 返回与当前 AWS 账户 和地区相关联的所有账本的日记账导出作业描述的列表。每个导出作业描述的输出都包含与 `DescribeJournalS3Export` 返回的相同的详细信息。
+ `ListJournalS3ExportsForLedger`— 返回给定分类账的日记账导出作业描述列表。每个导出作业描述的输出都包含与 `DescribeJournalS3Export` 返回的相同的详细信息。
有关这些 API 操作的完整介绍，请参阅 [Amazon QLDB API 参考](api-reference.md)。
有关使用导出日记账数据的信息 AWS CLI，请参阅[AWS CLI 命令参考](https://docs.aws.amazon.com/cli/latest/reference/qldb/index.html)。
### Java 中的示例应用程序
有关基本导出操作的 Java 代码示例，请参阅 GitHub 存储库 a [ws-samples/-amazon-qldb-dmv-sample](https://github.com/aws-samples/amazon-qldb-dmv-sample-java) java。有关如何下载和安装此示例应用程序的说明，请参阅 [安装 Amazon QLDB Java 示例应用程序](sample-app.java.md)。在请求导出之前，请确保按照 [Java 教程](getting-started.java.tutorial.md) 中的步骤 1-3 创建一个示例分类帐并用示例数据加载它。
以下类中的教程代码提供了创建导出、检查导出状态和处理导出输出的示例。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/qldb/latest/developerguide/export-journal.request.html)
## 导出作业到期
已完成的日记账导出作业有 7 天的保留期。此限制到期后，它们会自动被硬删除。此到期时间是一项硬性限制，无法更改。
在删除已完成的导出作业后，您将无法再使用 QLDB 控制台或以下 API 操作来检索有关该任务的元数据：
+ `DescribeJournalS3Export`
+ `ListJournalS3Exports`
+ `ListJournalS3ExportsForLedger`
但是，此过期时间对导出数据本身没有影响。所有元数据都保留在导出文件中写入的清单文件中。此过期时间旨在提供更顺畅的API操作体验，以列出日记账导出作业。QLDB 会移除旧的导出作业，确保您只看到最近的导出，而不必解析多页作业。
# QLDB 中的日记账导出输出
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
除包含您的日记账区块的数据对象外，Amazon QLDB 日记账导出作业还会写入两个清单文件。这些文件都保存在[导出请求](export-journal.request.md)指定的 Amazon S3 存储桶中。以下章节介绍每个输出对象的格式和内容。
**注意**
如果您将 JSON 指定为导出作业的输出格式，QLDB 会将 Amazon Ion 日记账数据在导出的数据对象中将其转换为 JSON 格式。有关更多信息，请转至 [向下转换至 JSON](#export-journal.output.json)。
**Topics**
+ [清单文件](#export-journal.output.manifest)
+ [数据对象](#export-journal.output.data)
+ [向下转换至 JSON](#export-journal.output.json)
+ [导出处理器库（Java）](#export-journal.output.processor)
## 清单文件
Amazon QLDB 为每个导出请求在提供的 S3 存储桶中创建两个清单文件。*初始清单*文件将在您提交导出请求后立即创建。*最终清单*文件是在导出完成后写入的。您可以使用这些文件来检查 Amazon S3 中导出作业的状态。
清单文件内容的格式与请求的导出输出格式相对应。
### 初始清单
初始清单表明您的导出作业已启动。它包含您传递给请求的输入参数。除了 Amazon S3 目标以及导出的开始和结束时间参数外，此文件还包含一个 `exportId`。此 `exportId` 是 QLDB 分配给每个导出作业的唯一 ID。
文件命名约定如下。
```
s3://amzn-s3-demo-qldb-cloudtrail/prefix/exportId.started.manifest
```
下面是 Ion 文本格式的初始清单文件及其内容示例。
```
s3://amzn-s3-demo-qldb-cloudtrail/journalExport/8UyXulxccYLAsbN1aon7e4.started.manifest
```
```
{
ledgerName:"my-example-ledger",
exportId:"8UyXulxccYLAsbN1aon7e4",
inclusiveStartTime:2019-04-15T00:00:00.000Z,
exclusiveEndTime:2019-04-15T22:00:00.000Z,
bucket:"amzn-s3-demo-qldb-cloudtrail",
prefix:"journalExport",
objectEncryptionType:"NO_ENCRYPTION",
outputFormat:"ION_TEXT"
}
```
`outputFormat`只有在导出请求中指定时，初始清单才会包含该清单。如果您没有指定输出格式，导出的数据将默认为 `ION_TEXT`。
[DescribeJournalS3Export API 操作和导出](https://docs.aws.amazon.com/qldb/latest/developerguide/API_DescribeJournalS3Export.html)的 Amazon S3 对象的内容类型也表明了输出格式。
### 最终清单
最终清单表示特定日记账*链*的导出作业已完成。导出作业为每个分支写入一个单独的最终清单文件。
**注意**
在 Amazon QLDB 中，分支是分类账日记账的分区。QLDB 目前仅支持单链日记账。
最终清单包括导出期间写入的数据对象密钥的有序列表。文件命名约定如下。
```
s3://amzn-s3-demo-qldb-cloudtrail/prefix/exportId.strandId.completed.manifest
```
`strandId` 是 QLDB 分配给链的唯一 ID。下面是 Ion 文本格式的最终清单文件及其内容示例。
```
s3://amzn-s3-demo-qldb-cloudtrail/journalExport/8UyXulxccYLAsbN1aon7e4.JdxjkR9bSYB5jMHWcI464T.completed.manifest
```
```
{
keys:[
"2019/04/15/22/JdxjkR9bSYB5jMHWcI464T.1-4.ion",
"2019/04/15/22/JdxjkR9bSYB5jMHWcI464T.5-10.ion",
"2019/04/15/22/JdxjkR9bSYB5jMHWcI464T.11-12.ion",
"2019/04/15/22/JdxjkR9bSYB5jMHWcI464T.13-20.ion",
"2019/04/15/22/JdxjkR9bSYB5jMHWcI464T.21-21.ion"
]
}
```
## 数据对象
Amazon QLDB 会以 Amazon Ion 格式的文本或二进制表示，或 *JSON Lines* 文本格式，将日记账数据对象写入提供的 Amazon S3 存储桶中。
在 JSON 行格式中，导出的数据对象中的每个区块都是由换行符分隔的有效 JSON 对象。您可以使用这种格式将 JSON 导出与 Amazon Athena 等分析工具直接集成，因为这些服务可以自动解析以换行 AWS Glue 符分隔的 JSON。有关数据格式的更多信息，请参阅 [JSON 行](https://jsonlines.org/)。
### 数据对象名称
日记账导出作业使用以下命名约定写入这些数据对象。
```
s3://amzn-s3-demo-qldb-cloudtrail/prefix/yyyy/mm/dd/hh/strandId.startSn-endSn.ion|.json
```
+ 每个导出作业的输出数据都被分成多个块。
+ `yyyy/mm/dd/hh`— 您提交导出请求的日期和时间。在同一小时内导出的对象是按相同的 Amazon S3 前缀进行分组。
+ `strandId`— 包含要导出的日记账区块的特定链的唯一 ID。
+ `startSn-endSn`— 对象中包含的序列号范围。序列号指定区块在链中的位置。
例如，假设您指定以下路径。
```
s3://amzn-s3-demo-qldb-cloudtrail/journalExport/
```
您的导出作业会创建一个类似于以下的 Amazon S3 数据对象。此示例显示了 Ion 格式的对象名称。
```
s3://amzn-s3-demo-qldb-cloudtrail/journalExport/2019/04/15/22/JdxjkR9bSYB5jMHWcI464T.1-5.ion
```
### 数据对象内容
每个数据对象都包含以下格式的日记账区块对象。
```
{
blockAddress: {
strandId: String,
sequenceNo: Int
},
transactionId: String,
blockTimestamp: Datetime,
blockHash: SHA256,
entriesHash: SHA256,
previousBlockHash: SHA256,
entriesHashList: [ SHA256 ],
transactionInfo: {
statements: [
{
//PartiQL statement object
}
],
documents: {
//document-table-statement mapping object
}
},
revisions: [
{
//document revision object
}
]
}
```
*区块*是在事务过程中提交到日记账的对象。区块包含事务元数据、以及代表事务中提交的文档修订版本条目、和提交这些修订的 [PartiQL](ql-reference.md) 语句。
以下是一个带有 Ion 文本格式样本数据的模块示例。有关块对象字段的更多信息，请参阅[Amazon QLDB 中的日记账内容](journal-contents.md)。
**注意**
数据块示例仅用于参考。显示的哈希值并非实际计算的哈希值。
```
{
blockAddress:{
strandId:"JdxjkR9bSYB5jMHWcI464T",
sequenceNo:1234
},
transactionId:"D35qctdJRU1L1N2VhxbwSn",
blockTimestamp:2019-10-25T17:20:21.009Z,
blockHash:{{WYLOfZClk0lYWT3lUsSr0ONXh+Pw8MxxB+9zvTgSvlQ=}},
entriesHash:{{xN9X96atkMvhvF3nEy6jMSVQzKjHJfz1H3bsNeg8GMA=}},
previousBlockHash:{{IAfZ0h22ZjvcuHPSBCDy/6XNQTsqEmeY3GW0gBae8mg=}},
entriesHashList:[
{{F7rQIKCNn0vXVWPexilGfJn5+MCrtsSQqqVdlQxXpS4=}},
{{C+L8gRhkzVcxt3qRJpw8w6hVEqA5A6ImGne+E7iHizo=}}
],
transactionInfo:{
statements:[
{
statement:"CREATE TABLE VehicleRegistration",
startTime:2019-10-25T17:20:20.496Z,
statementDigest:{{3jeSdejOgp6spJ8huZxDRUtp2fRXRqpOMtG43V0nXg8=}}
},
{
statement:"CREATE INDEX ON VehicleRegistration (VIN)",
startTime:2019-10-25T17:20:20.549Z,
statementDigest:{{099D+5ZWDgA7r+aWeNUrWhc8ebBTXjgscq+mZ2dVibI=}}
},
{
statement:"CREATE INDEX ON VehicleRegistration (LicensePlateNumber)",
startTime:2019-10-25T17:20:20.560Z,
statementDigest:{{B73tVJzVyVXicnH4n96NzU2L2JFY8e9Tjg895suWMew=}}
},
{
statement:"INSERT INTO VehicleRegistration ?",
startTime:2019-10-25T17:20:20.595Z,
statementDigest:{{ggpon5qCXLo95K578YVhAD8ix0A0M5CcBx/W40Ey/Tk=}}
}
],
documents:{
'8F0TPCmdNQ6JTRpiLj2TmW':{
tableName:"VehicleRegistration",
tableId:"BPxNiDQXCIB5l5F68KZoOz",
statements:[3]
}
}
},
revisions:[
{
hash:{{FR1IWcWew0yw1TnRklo2YMF/qtwb7ohsu5FD8A4DSVg=}}
},
{
blockAddress:{
strandId:"JdxjkR9bSYB5jMHWcI464T",
sequenceNo:1234
},
hash:{{t8Hj6/VC4SBitxnvBqJbOmrGytF2XAA/1c0AoSq2NQY=}},
data:{
VIN:"1N4AL11D75C109151",
LicensePlateNumber:"LEWISR261LL",
State:"WA",
City:"Seattle",
PendingPenaltyTicketAmount:90.25,
ValidFromDate:2017-08-21,
ValidToDate:2020-05-11,
Owners:{
PrimaryOwner:{
PersonId:"GddsXfIYfDlKCEprOLOwYt"
},
SecondaryOwners:[]
}
},
metadata:{
id:"8F0TPCmdNQ6JTRpiLj2TmW",
version:0,
txTime:2019-10-25T17:20:20.618Z,
txId:"D35qctdJRU1L1N2VhxbwSn"
}
}
]
}
```
在`revisions`字段中，某些修订版本对象可能只包含一个 `hash` 值而不包含其他属性。这是仅供内部使用的系统修订版，不包含用户数据。导出作业将这些修订包含在各自的区块中，因为这些修订的哈希值是日记完整哈希链的一部分。加密验证需要完整的哈希链。
## 向下转换至 JSON
如果您将 JSON 指定为导出作业的输出格式，QLDB 会将 Amazon Ion 日记账数据在导出的数据对象中将其转换为 JSON 格式。但是，在某些情况下，如果您的数据使用 JSON 中不存在的丰富 Ion 类型，则将 Ion 转换为 JSON 时会有损失。
有关 Ion 与 JSON 转换规则的详细信息，请参阅*Amazon Ion Cookbook*中的[向下转换至 JSON](https://amzn.github.io/ion-docs/guides/cookbook.html#down-converting-to-json)。
## 导出处理器库（Java）
QLDB 为 Java 提供了一个可扩展的框架，该框架可以简化 Amazon S3 中的导出处理。该框架库处理读取导出的输出并按顺序遍历导出的区块的工作。要使用此导出处理器，请参阅 GitHub 存储库 [awslabs/-java amazon-qldb-export-processor](https://github.com/awslabs/amazon-qldb-export-processor-java)。
# QLDB 中的日记账导出权限
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
在向 Amazon QLDB 提交日记账导出请求之前，您必须在指定的 Amazon S3 存储桶中为 QLDB 提供写入权限。如果您选择将客户托管 AWS KMS key 的作为 Amazon S3 存储桶的对象加密类型，您还必须授予 QLDB 使用您指定的对称加密密钥的权限。Amazon RDS 不支持[非对称 KMS 密钥](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html)。
要为您的导出作业提供必要的权限，您可以让 QLDB 扮演具有相应权限策略的 IAM 服务角色。服务角色是由一项服务担任、代表您执行操作的 [IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)。IAM 管理员可以在 IAM 中创建、修改和删除服务角色。有关更多信息，请参阅《IAM 用户指南》**中的[创建向 AWS 服务委派权限的角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html)。
**注意**
要在请求日记账导出时将角色传递给 QLDB，您必须具有对 IAM 角色资源执行 `iam:PassRole` 操作的权限。这是对 QLDB 分类账资源的 `qldb:ExportJournalToS3` 权限的补充。
要了解如何使用 IAM 控制对 QLDB 的访问权限，请参阅 [Amazon MQ 如何与 IAM 协同工作](security_iam_service-with-iam.md)。有关 QLDB 策略示例，请参阅[Amazon QLDB 基于身份的策略示例](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-export-to-s3-bucket)。
在此示例中，您创建一个角色，允许 QLDB 代表您将对象写入 Amazon S3 存储桶。有关更多信息，请参阅《IAM 用户指南》中的 [创建向 AWS 服务委派权限的角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html)**。
如果您是首次在中 AWS 账户 导出 QLDB 日记，则必须先通过执行以下操作创建具有相应策略的 IAM 角色。或者，您可以[使用 QLDB 控制台](export-journal.request.md#export-journal.request.con)自动为您创建角色。否则，您可以选择之前创建的角色。
**Topics**
+ [创建权限策略](#export-journal.perms.create-policy)
+ [创建 IAM 角色](#export-journal.perms.create-role)
## 创建权限策略
完成以下步骤来为 QLDB 日记账导出作业创建权限策略。此示例显示了 Amazon S3 存储桶策略，该策略授予 QLDB 向您的指定存储桶写入对象的权限。如果适用，示例还显示了一个密钥策略，允许 QLDB 使用您指定的对称加密 KMS 密钥。
有关 Amazon S3 的存储桶策略的更多信息，请参阅 *Amazon Simple Storage Service 用户指南*中的[使用存储桶策略和用户策略](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-iam-policies.html)。有关 AWS KMS 密钥策略的更多信息，请参阅 *AWS Key Management Service 开发人员指南*中的[使用 AWS KMS中的密钥策略](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html)。
**注意**
您的 Amazon S3 存储桶和 KMS 密钥必须与您的 QLDB 账本 AWS 区域 相同。
**使用 JSON 策略编辑器创建策略**
1. 登录 AWS 管理控制台 并打开 IAM 控制台，网址为[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。
1. 在左侧的导航栏中，选择 **Policies（策略）**。
如果这是您首次选择 **Policies**，则会显示 **Welcome to Managed Policies** 页面。选择**开始使用**。
1. 在页面的顶部，选择 **Create Policy（创建策略）**。
1. 请选择 **JSON** 选项卡。
1. 输入 JSON 策略文档。
+ 如果您正在使用客户托管的 KMS 密钥进行 Amazon S3 对象加密，请使用以下示例策略文档。要使用此政策，请用您自己的信息替换*amzn-s3-demo-qldb-cloudtrail*示例*1234abcd-12ab-34cd-56ef-1234567890ab*中的*123456789012*、、和。*us-east-1*
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "QLDBJournalExportS3Permission",
"Action": [
"s3:PutObjectAcl",
"s3:PutObject"
],
"Effect": "Allow",
"Resource": "arn:aws:s3:::amzn-s3-demo-qldb-cloudtrail/*"
},
{
"Sid": "QLDBJournalExportKMSPermission",
"Action": [ "kms:GenerateDataKey" ],
"Effect": "Allow",
"Resource": "arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
]
}
```
+ 对于其他加密类型，请使用以下示例策略文档。要使用此策略，请在示例*amzn-s3-demo-qldb-cloudtrail*中使用您自己的 Amazon S3 存储桶名称替换。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "QLDBJournalExportS3Permission",
"Action": [
"s3:PutObjectAcl",
"s3:PutObject"
],
"Effect": "Allow",
"Resource": "arn:aws:s3:::amzn-s3-demo-qldb-cloudtrail/*"
}
]
}
```
1. 选择**Review policy（查看策略）**。
**注意**
您可以随时在**可视化编辑器**和 **JSON** 选项卡之间切换。不过，如果您进行更改或在**可视化编辑器**选项卡中选择 **Review policy（查看策略）**，IAM 可能会调整您的策略结构以针对可视化编辑器进行优化。有关更多信息，请参阅《IAM 用户指南》**中的[调整策略结构](https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_policies.html#troubleshoot_viseditor-restructure)。
1. 在 **Review policy（查看策略）**页面上，为创建的策略输入 **Name（名称）**和 **Description（说明）**（可选）。查看策略**摘要**以查看您的策略授予的权限。然后，选择**创建策略**以保存您的工作。
## 创建 IAM 角色
为您的 QLDB 日记账导出作业创建权限策略后，您可以创建一个 IAM 角色并将您的策略附加到该角色。
**创建用于 QLDB 的服务角色（IAM 控制台）**
1. 登录 AWS 管理控制台 并打开 IAM 控制台，网址为[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。
1. 在 IAM 控制台的导航窗格中，选择**角色**，然后选择**创建角色**。
1. 对于 **Trusted entity type**（可信实体类型），选择 **AWS 服务**。
1. 对于**服务或使用案例**，请选择 **QLDB**，然后选择 **QLDB** 使用案例。
1. 选择**下一步**。
1. 选中您之前创建的策略旁边的方框。
1. （可选）设置[权限边界](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html)。这是一项高级特征，可用于服务角色，但不可用于服务相关角色。
1. 打开**设置权限边界**部分，然后选择**使用权限边界控制最大角色权限**。
IAM 包含您账户中的 AWS 托管策略和客户托管策略列表。
1. 选择要用于权限边界的策略。
1. 选择**下一步**。
1. 输入有助于识别角色的作用的角色名称或者角色名称后缀。
**重要**
命名角色时，请注意以下事项：
角色名称在您内部必须是唯一的 AWS 账户，并且不能因大小写而变得唯一。
例如，不要同时创建名为 **PRODROLE** 和 **prodrole** 的角色。当角色名称在策略中使用或者作为 ARN 的一部分时，角色名称区分大小写，但是当角色名称在控制台中向客户显示时（例如，在登录期间），角色名称不区分大小写。
创建角色后，您无法编辑该角色的名称，因为其他实体可能会引用该角色。
1. （可选）对于**描述**，输入角色的描述。
1. （可选）要编辑角色的使用案例和权限，请在**步骤 1：选择可信实体**或**步骤 2：添加权限**部分中选择**编辑**。
1. （可选）为了帮助识别、组织或搜索角色，请以键值对形式添加标签。有关在 IAM 中使用标签的更多信息，请参阅 *IAM 用户指南*中的[AWS Identity and Access Management 资源标签](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html)。
1. 检查该角色，然后选择**创建角色**。
以下的 JSON 文档是一个信任策略的示例，该策略允许 QLDB 假定一个附有特定权限的 IAM 角色。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "qldb.amazonaws.com"
},
"Action": [ "sts:AssumeRole" ],
"Condition": {
"ArnEquals": {
"aws:SourceArn": "arn:aws:qldb:us-east-1:123456789012:*"
},
"StringEquals": {
"aws:SourceAccount": "123456789012"
}
}
}
]
}
```
**注意**
以下示例演示如何使用 `aws:SourceArn` 和 `aws:SourceAccount` 全局条件上下文键来防范*混淆代理*问题。通过这个信任策略，QLDB 只能为同一账户`123456789012`中的任何 QLDB 资源扮演角色。
有关更多信息，请参阅[防止跨服务混淆代理](cross-service-confused-deputy-prevention.md)。
创建 IAM 角色后，返回 QLDB 控制台并刷新“**创建导出作业**”页面，以便它可以找到您的新角色。
# 日记账导出的常见错误
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
本节介绍了 Amazon QLDB 为日记账导出请求引发的运行时系统错误。
以下是该服务返回的常见异常列表。每个异常都包括特定的错误消息，然后是简短的描述和可能的解决方案建议。
**AccessDeniedException**
消息：用户：*userARN*无权PassRole 在资源上执行：iam：*roleARN*
您无权将 IAM 角色传递给 QLDB 服务。QLDB 要求所有日记账导出请求都有一个角色，并且您必须具有将该角色传递给 QLDB 的权限。该角色为 QLDB 提供了在您指定的 Amazon S3 存储桶中的写入权限。
核实您定义了一个 IAM policy，该策略授予对您指定的 QLDB 服务（`qldb.amazonaws.com`）的 IAM 角色资源执行 `PassRole` API 操作的权限。有关策略示例，请参阅[Amazon QLDB 基于身份的策略示例](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-export-to-s3-bucket)。
**IllegalArgumentException**
消息：QLDB 在验证 S3 配置时遇到错误：*errorCode**errorMessage*
导致此错误的一个可能原因是 Amazon S3 中不存在所提供的 Amazon S3 存储桶。或者，QLDB 没有足够的权限将对象写入您指定的 Amazon S3 存储桶。
验证您在导出任务请求中提供的 S3 存储桶名称是否正确。有关命名存储桶的信息，请参阅*Amazon Simple Storage Service 户指南* 中的 [存储桶限制和局限](https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html)。
此外，请确认您是否为指定的存储桶定义了一个向 QLDB 服务（`qldb.amazonaws.com`）授予 `PutObject` 和 `PutObjectAcl` 权限的策略。要了解更多信息，请参阅[导出权限](export-journal.perms.md)。
**IllegalArgumentException**
消息：在验证 S3 配置时，来自 Amazon S3 的意外响应。来自 S3 的回复：*errorCode**errorMessage*
尝试将日记账导出数据写入提供的 S3 失败，并显示提供的 Amazon S3 错误响应。有关可能原因的更多信息，请参阅 *Amazon Simple Storage Service 用户指南*中的[Amazon S3 故障排除](https://docs.aws.amazon.com/AmazonS3/latest/userguide/troubleshooting.html)。
**IllegalArgumentException**
消息：Amazon S3 存储桶前缀不得超过 128 个字符
日记账导出请求中提供的前缀包含超过 128 个字符。
**IllegalArgumentException**
消息：开始日期不得早于结束日期
`InclusiveStartTime` 和 `ExclusiveEndTime` 必须采用 [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) 日期和时间格式以及通用协调时间（UTC）。
**IllegalArgumentException**
消息：结束日期不能是未来的日期
`InclusiveStartTime` 和 `ExclusiveEndTime` 都必须采用 `ISO 8601` 日期和时间格式以及 UTC。
**IllegalArgumentException**
消息：提供的对象加密设置 (S3EncryptionConfiguration) 与 AWS Key Management Service (AWS KMS) 密钥不兼容
您 `KMSKeyArn` 提供的是 `NO_ENCRYPTION` 或 `ObjectEncryptionType` 中的一个 `SSE_S3`。您只能为客户提供对象加密类型的托管 AWS KMS key `SSE_KMS`。有关在 Amazon S3 中使用服务器端加密选项的信息，请参阅 *Amazon S3 开发人员指南* 中的[使用服务器端加密保护数据](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)。
**LimitExceededException**
消息：已超出 2 个同时运行日记账导出任务的限制
QLDB 强制执行两个并发日记账导出任务的默认限制。