QLDB のジャーナルエクスポート出力 - Amazon Quantum Ledger Database (Amazon QLDB)

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

QLDB のジャーナルエクスポート出力

Amazon QLDB ジャーナルエクスポートジョブでは、ジャーナルブロックを含むデータオブジェクトに加え、2 つのマニフェストファイルが書き出されます。これらはすべて、エクスポートリクエストで指定した Amazon S3 バケットに保存されます。以下のセクションでは、各出力オブジェクトの形式と内容について説明します。

注記

エクスポートジョブの出力形式として JSON を指定すると、QLDB はエクスポートされたデータオブジェクトの Amazon Ion ジャーナルデータを JSON にダウンコンバートします。詳細については、「JSON へのダウンコンバート」に進んでください。

マニフェストファイル

Amazon QLDB では、エクスポートリクエストごとに、指定した S3 バケットに 2 つのマニフェストファイルが作成されます。エクスポートリクエストを送信するとすぐに、最初のマニフェストファイルが作成されます。エクスポートが完了したら、最終的なマニフェストファイルが書き出されます。これらのファイルを使用して、Simple Storage Service (Amazon S3) のエクスポートジョブのステータスを確認できます。

マニフェストファイルの内容の形式は、エクスポートで要求された出力形式に対応しています。

最初のマニフェスト

最初のマニフェストでは、エクスポートジョブが開始したことを示します。このマニフェストには、リクエストに渡した入力パラメータが含まれます。エクスポートの Simple Storage Service (Amazon S3) 送信先、エクスポート用の開始時間パラメータや終了時間パラメータに加え、このファイルには exportId も含まれます。exportId は、QLDB が各エクスポートジョブに割り当てる、一意の ID です。

このファイルの命名規則は次のとおりです。

s3://DOC-EXAMPLE-BUCKET/prefix/exportId.started.manifest

以下は、Ion テキスト形式の最初のマニフェストファイルとその内容の例です。

s3://DOC-EXAMPLE-BUCKET/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:"DOC-EXAMPLE-BUCKET", prefix:"journalExport", objectEncryptionType:"NO_ENCRYPTION", outputFormat:"ION_TEXT" }

初期のマニフェストには、エクスポートリクエストで指定された場合のみ、outputFormat が含まれます。出力形式を指定しない場合、エクスポートされたデータはデフォルトの ION_TEXT 形式 になります。

DescribeJournalS3Export API オペレーションとエクスポートされた Amazon S3 オブジェクトのコンテンツタイプも出力形式を示します。

最終的なマニフェスト

最終的なマニフェストは、特定のジャーナルストランドのエクスポートジョブが完了したことを示します。エクスポートジョブでは、ストランドごとに個別に最終的なマニフェストファイルが書き出されます。

注記

Amazon QLDB で、ストランドは台帳のジャーナルの仕切りです。QLDB は現在、単一ストランドのジャーナルのみをサポートしています。

最終的なマニフェストには、エクスポート中に書き出されたデータオブジェクトキーの順序付きリストが含まれます。このファイルの命名規則は次のとおりです。

s3://DOC-EXAMPLE-BUCKET/prefix/exportId.strandId.completed.manifest

strandId は、QLDB がストランドに割り当てる一意の ID です。以下は、Ion テキスト形式の最終的なマニフェストファイルとその内容の例です。

s3://DOC-EXAMPLE-BUCKET/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 S3 バケットに Amazon Ion 形式のバイナリ表現または JSON Lines テキスト形式で、ジャーナルデータオブジェクトを書き込みます。

JSON Lines 形式では、エクスポートされたデータオブジェクトの各ブロックは、改行で区切られた有効な JSON オブジェクトです。この形式を使用して、JSON エクスポートを Amazon Athena や などの分析ツールと直接統合できます。 AWS Glue これらのサービスは改行区切りの JSON を自動的に解析できるためです。形式の詳細については、JSON Lines を参照してください。

データオブジェクト名

ジャーナルエクスポートジョブでは、以下の命名規則に従ってこれらのデータオブジェクトが書き込まれます。

s3://DOC-EXAMPLE-BUCKET/prefix/yyyy/mm/dd/hh/strandId.startSn-endSn.ion|.json
  • 各エクスポートジョブの出力データはチャンクに分割されます。

  • yyyy/mm/dd/hh – エクスポートリクエストを送信したときの日時。同じ時間内にエクスポートされたオブジェクトは、同じ Simple Storage Service (Amazon S3) プレフィックスにグループ分けされます。

  • strandId – エクスポートされるジャーナルブロックを含む特定のストランドの一意の ID。

  • startSn-endSn – オブジェクトに含まれるシーケンス番号の範囲。シーケンス番号は、ストランド内のブロックの場所を指定します。

たとえば、次のパスを指定するとします。

s3://DOC-EXAMPLE-BUCKET/journalExport/

エクスポートジョブで、次のような Simple Storage Service (Amazon S3) データオブジェクトが作成されます。この例では、オブジェクト名を Ion 形式で示しています。

s3://DOC-EXAMPLE-BUCKET/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 ステートメントと共に、トランザクションのメタデータが含まれます。

以下に、Ion テキスト形式のサンプルデータを含むブロックの例を示します。ブロックオブジェクトのフィールドの詳細については、「Amazon QLDB のジャーナルコンテンツ」を参照してください。

注記

このブロック例は、情報提供のみを目的として記載されています。示されているハッシュは、実際に計算されたハッシュ値ではありません。

{ 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」(Amazon Ion クックブック) の「Down-converting to JSON」(JSON へのダウンコンバート) を参照してください。

エクスポートプロセッサライブラリ (Java)

QLDB は、Amazon S3 でのエクスポート処理を効率化する Java 用の拡張可能なフレームワークを提供します。このフレームワークライブラリは、エクスポートの出力を読み取り、エクスポートされたブロックを順番に反復処理します。このエクスポートプロセッサを使用するには、 GitHub リポジトリ awslabs/amazon-qldb-export-processor-java を参照してください。