本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 從 Amazon QLDB 匯出日誌資料
**重要**
終止支援通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 終止支援為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
Amazon QLDB 使用不可變的交易日誌，稱為*日誌*，用於資料儲存。日誌會追蹤您遞交資料的每個變更，並維護一段時間內完整且可驗證的變更歷史記錄。
您可以出於各種目的存取總帳中的日誌內容，包括分析、稽核、資料保留、驗證和匯出到其他系統。下列主題說明如何將日誌[區塊](journal-contents.md)從總帳匯出至 中的 Amazon Simple Storage Service (Amazon S3) 儲存貯體 AWS 帳戶。日誌匯出任務會以 Amazon Ion 格式的文字或二進位表示法或 JSON Lines 文字格式，將您的資料寫入 Amazon S3 做為物件。 [Amazon QLDB 中的 Amazon Ion 資料格式參考](ion.md) **
在 JSON Lines 格式中，匯出的資料物件中的每個區塊都是由新行分隔的有效 JSON 物件。您可以使用此格式直接整合 JSON 匯出與 Amazon Athena 等分析工具， AWS Glue 因為這些服務可以自動剖析換行分隔 JSON。如需格式的詳細資訊，請參閱 [JSON Lines](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，直到 07/31/2025 終止支援為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon 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 Lines](https://jsonlines.org/) 文字格式寫入資料物件。您可以使用 AWS 管理主控台、 AWS 開發套件或 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. 登入 AWS 管理主控台，並在 https：//[https://console.aws.amazon.com/qldb](https://console.aws.amazon.com/qldb) 開啟 Amazon 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 S3 開發人員指南*》中的[儲存貯體限制](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 Resource Name (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 主控台上查看匯出物件。
開啟位於 [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/) 的 Amazon S3 主控台。
若要進一步了解這些輸出物件的格式，請參閱 [QLDB 中的日誌匯出輸出](export-journal.output.md)。
**注意**
匯出任務會在完成七天後過期。如需詳細資訊，請參閱[匯出任務過期](#export-journal.request.expiration)。
## QLDB API
您也可以使用 Amazon QLDB API 搭配 AWS SDK 或 來請求日誌匯出 AWS CLI。QLDB API 提供下列操作供應用程式使用：
+ `ExportJournalToS3` – 將日期和時間範圍內的日誌內容從指定的總帳匯出到指定的 Amazon S3 儲存貯體。匯出任務可以將資料寫入為 Amazon Ion 格式的文字或二進位表示法，或 JSON Lines 文字格式的物件。
+ `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 儲存庫 [aws-samples/amazon-qldb-dmv-sample-java](https://github.com/aws-samples/amazon-qldb-dmv-sample-java)。如需如何下載和安裝此範例應用程式的指示，請參閱 [安裝 Amazon QLDB Java 範例應用程式](sample-app.java.md)。在請求匯出之前，請務必遵循 中的步驟 1–3 [Java 教學課程](getting-started.java.tutorial.md) 來建立範例總帳，並使用範例資料將其載入。
下列類別中的教學課程程式碼提供建立匯出、檢查匯出狀態，以及處理匯出輸出的範例。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/qldb/latest/developerguide/export-journal.request.html)
## 匯出任務過期
已完成的日誌匯出任務受 7 天的保留期限制。它們會在此限制過期後自動硬刪除。此過期期間是硬性限制，無法變更。
刪除完成的匯出任務後，您無法再使用 QLDB 主控台或下列 API 操作來擷取任務的中繼資料：
+ `DescribeJournalS3Export`
+ `ListJournalS3Exports`
+ `ListJournalS3ExportsForLedger`
不過，此過期不會影響匯出的資料本身。所有中繼資料都會保留在匯出所寫入的資訊清單檔案中。此過期旨在為列出日誌匯出任務的 API 操作提供更順暢的體驗。QLDB 會移除舊匯出任務，以確保您只看到最近的匯出，而不必剖析多頁任務。
# QLDB 中的日誌匯出輸出
**重要**
終止支援通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 終止支援為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon 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](https://docs.aws.amazon.com/qldb/latest/developerguide/API_DescribeJournalS3Export.html) API 操作和匯出的 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 Lines 格式中，匯出的資料物件中的每個區塊都是由新行分隔的有效 JSON 物件。您可以使用此格式直接整合 JSON 匯出與 Amazon Athena 等分析工具， AWS Glue 因為這些服務可以自動剖析換行分隔 JSON。如需格式的詳細資訊，請參閱 [JSON Lines](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。不過，在某些情況下，將 Ion 轉換為 JSON 會造成失真，其中您的資料使用 JSON 中不存在的豐富 Ion 類型。
如需 Ion 轉換至 JSON 轉換規則的詳細資訊，請參閱[《Amazon Ion 技術指南》中的向下轉換至 JSON](https://amzn.github.io/ion-docs/guides/cookbook.html#down-converting-to-json)。 **
## 匯出處理器程式庫 (Java)
QLDB 為 Java 提供可擴展的架構，可簡化 Amazon S3 匯出的處理。此架構程式庫會依序處理讀取匯出輸出和反覆查看匯出區塊的工作。若要使用此匯出處理器，請參閱 GitHub 儲存庫 [awslabs/amazon-qldb-export-processor-java](https://github.com/awslabs/amazon-qldb-export-processor-java)。
# QLDB 中的日誌匯出許可
**重要**
終止支援通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 終止支援為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon 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 S3 不支援[非對稱 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 QLDB 如何與 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 金鑰必須與 AWS 區域 QLDB 總帳位於相同的 中。
**若要使用 JSON 政策編輯器來建立政策**
1. 登入 AWS 管理主控台 並開啟位於 https：//[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 的 IAM 主控台。
1. 在左側的導覽欄中，選擇 **Policies** (政策)。
如果這是您第一次選擇 **Policies (政策)**，將會顯示 **Welcome to Managed Policies (歡迎使用受管政策)** 頁面。選擇 **Get Started (開始使用)**。
1. 在頁面頂端，選擇 **Create policy (建立政策)**。
1. 選擇 **JSON** 標籤。
1. 輸入 JSON 政策文件。
+ 如果您使用客戶受管 KMS 金鑰進行 Amazon S3 物件加密，請使用下列範例政策文件。若要使用此政策，請將範例中的 *amzn-s3-demo-qldb-cloudtrail*、*us-east-1*、*123456789012* 和 *1234abcd-12ab-34cd-56ef-1234567890ab* 取代為您自己的資訊。
```
{
"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"
}
]
}
```
+ 對於其他加密類型，請使用下列範例政策文件。若要使用此政策，請以您自己的 Amazon S3*3 儲存貯體名稱取代範例中的 amzn-s3-demo-qldb-cloudtrail*。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "QLDBJournalExportS3Permission",
"Action": [
"s3:PutObjectAcl",
"s3:PutObject"
],
"Effect": "Allow",
"Resource": "arn:aws:s3:::amzn-s3-demo-qldb-cloudtrail/*"
}
]
}
```
1. 選擇**檢閱政策**。
**注意**
您可以隨時切換 **Visual editor** (視覺化編輯器) 與 **JSON** 標籤。不過，如果您進行更改或在 **Visual editor** (視覺編輯工具) 索引標籤中選擇 **Review policy** (檢閱政策)，IAM 可能會調整您的政策結構以針對視覺編輯工具進行最佳化。如需詳細資訊，請參閱 *IAM 使用者指南*中的[調整政策結構](https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_policies.html#troubleshoot_viseditor-restructure)。
1. 在 **Review policy** (檢閱政策) 頁面上，為您正在建立的政策輸入選用的 **Name** (名稱) 與 **Description** (描述)。檢閱政策 **Summary** (摘要) 來查看您的政策所授予的許可。然後選擇 **Create policy (建立政策)** 來儲存您的工作。
## 建立 IAM 角色
為您的 QLDB 日誌匯出任務建立許可政策之後，您就可以建立 IAM 角色，並將政策連接到該角色。
**建立 QLDB 的服務角色 (IAM 主控台）**
1. 登入 AWS 管理主控台 並開啟位於 https：//[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 的 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. 檢閱角色，然後選擇 **Create role** (建立角色)。
下列 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，直到 07/31/2025 終止支援為止。如需詳細資訊，請參閱[將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
本節說明 Amazon QLDB 針對日誌匯出請求擲回的執行時間錯誤。
以下是 服務傳回的常見例外狀況清單。每個例外狀況都包含特定的錯誤訊息，後面接著可能解決方案的簡短描述和建議。
**AccessDeniedException**
訊息：使用者：*userARN* 未獲授權執行：iam：PassRole on resource： *roleARN*
您沒有將 IAM 角色傳遞至 QLDB 服務的許可。QLDB 需要所有日誌匯出請求的角色，而且您必須具有將此角色傳遞給 QLDB 的許可。此角色會在您指定的 Amazon S3 儲存貯體中為 QLDB 提供寫入許可。
請確認您定義了 IAM 政策，該政策授予對 QLDB 服務 () 的指定 IAM 角色資源執行 `PassRole` API 操作的許可`qldb.amazonaws.com`。如需政策範例，請參閱[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)。
此外，請確認您為指定的儲存貯體定義政策，以授予 `PutObject`和 QLDB 服務的`PutObjectAcl`許可 (`qldb.amazonaws.com`)。如需詳細資訊，請參閱 [匯出許可](export-journal.perms.md)。
**IllegalArgumentException**
訊息：驗證 Amazon S3 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) 金鑰不相容
您已提供 `ObjectEncryptionType`的 `KMSKeyArn` `NO_ENCRYPTION`或 `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 會強制執行兩個並行日誌匯出任務的預設限制。