QLDB でのストリーミングの作成と管理 - Amazon Quantum Ledger Database (Amazon QLDB)
ストリームパラメータストリーム ARNAWS Management Consoleストリームの状態障害のあるストリームの処理

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

QLDB でのストリーミングの作成と管理

重要

サポート終了通知: 既存のお客様は、07/31/2025 のサポート終了まで Amazon QLDB を使用できます。詳細については、「Amazon QLDB 台帳を Amazon Aurora PostgreSQL に移行する」を参照してください。

Amazon QLDB では、台帳から Amazon Kinesis Data Streams へのジャーナルデータのストリーミングを作成し管理するための API オペレーションを提供します。QLDB ストリーミングは、ジャーナルにコミットされたドキュメントリビジョンをすべてキャプチャし、Kinesis データストリームに送信します。

AWS Management Console、 AWS SDK、または AWS Command Line Interface （AWS CLI) を使用してジャーナルストリームを作成できます。また、AWS CloudFormation テンプレートを使用してストリーミングを作成することもできます。詳細については、「AWS CloudFormation ユーザーガイド」の「AWS::QLDB::Stream」リソースを参照してください。

ストリームパラメータ

QLDB ジャーナルストリーミングを作成するには、以下の設定パラメータを指定する必要があります。

台帳名

Kinesis Data Streams へストリーミングするジャーナルデータがある QLDB 台帳。

ストリーム名

QLDB ジャーナルストリームに割り当てる名前。ユーザー定義の名前は、ストリームの目的を識別して示すのに役立ちます。

ストリーム名は、特定の台帳の他のアクティブなストリーム間で一意である必要があります。ストリーム名には、「Amazon QLDB でのクォータと制限」で定義されている台帳名と同じ命名制約があります。

QLDB では、ストリーミング名に加えて、作成する各 QLDB ストリーミングにストリーミング ID を送信します。ストリーム ID は、そのステータスに関係なく、特定の台帳のすべてのストリーム間で一意です。

開始日時

ジャーナルデータのストリーミングを開始する日時。この値には、過去の任意の日付と時刻を指定できますが、将来の日付を指定することはできません。

終了日時

(任意) ストリームの終了を指定する日時。

終了時刻のない無期限のストリームを作成する場合、ストリームを終了するには手動でキャンセルする必要があります。また、指定された終了日時に達していないアクティブな有限ストリームをキャンセルすることもできます。

ストリーミング先の Kinesis データストリーム

ストリーミングがデータレコードを書き込む Kinesis Data Streams ターゲットリソース。Kinesis データストリームの作成方法については、「Amazon Kinesis Data Streams デベロッパーガイド」の「データストリームの作成および更新」を参照してください。

重要

  • クロスリージョンおよびクロスアカウントストリームはサポートされていません。指定する Kinesis データストリームは、台帳と同じ AWS リージョン およびアカウントに存在する必要があります。

  • Kinesis Data Streams のレコード集約は、デフォルトで有効になっています。QLDB が 1 つの Kinesis Data Streams レコードで複数のデータレコードを発行できるようにします。これにより、API コールごとに送信されるレコードの数が増加します。

    レコード集約は、レコードの処理に重要な意味を持ち、ストリーミングコンシューマーで集約を解除する必要があります。詳細については、「Amazon Kinesis Data Streams デベロッパーガイド」の「KPL の主要な概念」および「コンシューマーの集約解除」を参照してください。

IAM ロール

QLDB が Kinesis データストリームへの書き込み許可を引き受けられるようにする IAM ロール。QLDB コンソールを使用してこのロールを自動的に作成するか、IAM で手動で作成できます。手動で作成する方法については、「ストリームアクセス許可」を参照してください。

ジャーナルストリーミングをリクエストするときに QLDB にロールを渡すには、IAM ロールリソースで iam:PassRole アクションを実行するための許可が必要です。

ストリーム ARN

すべての QLDB ジャーナルストリーミングは台帳のサブリソースであり、Amazon リソースネーム (ARN) によって一意に識別されます。以下は、exampleLedger という名前の台帳の、ストリーミング ID が IiPT4brpZCqCq3f4MTHbYy である QLDB ストリーミングの ARN の例です。

arn:aws:qldb:us-east-1:123456789012:stream/exampleLedger/IiPT4brpZCqCq3f4MTHbYy

次のセクションでは、 AWS Management Consoleを使用して QLDB ストリーミングを作成およびキャンセルする方法について説明します。

AWS Management Console

QLDB コンソールを使用して QLDB ストリーミングを作成またはキャンセルするには、次の手順に従います。

ストリームを作成するには (コンソール)

  1. にサインインし AWS Management Console、https://console.aws.amazon.com/qldb で Amazon QLDB コンソールを開きます。

  2. ナビゲーションペインで、[ストリーム] を選択します。

  3. [Create QLDB stream] (QLDB ストリームを作成) を選択します。

  4. [Create QLDB stream] (QLDB ストリームを作成) ページで、以下の設定を入力します。

    • [Stream name] (ストリーム名) - QLDB ストリーミングに割り当てる名前。

    • [Ledger] (台帳) - ストリーミングするジャーナルデータがある台帳。

    • [Start date and time] (開始日時) - ジャーナルデータのストリーミングを開始する、協定世界時 (UTC、Coordinated Universal Time) でのタイムスタンプ (ストリーミング期間に含まれます)。このタイムスタンプのデフォルトは、現在の日時です。これを将来の日時にすることはできません。また、[終了日時] より前の日付にする必要があります。

    • [End date and time] (終了日時) - (オプション) ストリーミングの終了時期を指定する UTC 形式のタイムスタンプ (ストリーミング期間に含まれません)。このパラメータを空白のままにすると、ストリームはキャンセルするまで無期限に実行されます。

    • [Destination stream] (送信先ストリーム) - ストリーミングがデータレコードを書き込む Kinesis Data Streams ターゲットリソース。次の ARN 形式を使用します。

      arn:aws:kinesis:aws-region:account-id:stream/kinesis-stream-name

      以下に例を示します。

      arn:aws:kinesis:us-east-1:123456789012:stream/stream-for-qldb

      クロスリージョンおよびクロスアカウントストリームはサポートされていません。指定された Kinesis データストリームは、台帳と同じ AWS リージョン および アカウントにある必要があります。

    • [Enable record aggregation in Kinesis Data Streams] (Kinesis Data Streams でレコード集約を有効にする) — (デフォルトで有効) QLDB が 1 つの Kinesis Data Streams レコードで複数のデータレコードを発行できるようにします。これにより、API コールごとに送信されるレコードの数が増加します。

    • [Service access] (サービスアクセス) - Kinesis データストリームへの書き込み許可を QLDB に付与する IAM ロール。

      ジャーナルストリーミングをリクエストするときに QLDB にロールを渡すには、IAM ロールリソースで iam:PassRole アクションを実行するための許可が必要です。

      • [Create and use a new service role] (新しいサービスロールを作成して使用する) - 指定された Kinesis データストリームに必要な許可を持つ新しいロールをコンソールで作成できます。

      • [Use an existing service role] (既存のサービスロールを使用する) - IAM でこのロールを手動で作成する方法については、「ストリームアクセス許可」を参照してください。

    • [Tags] (タグ) - (オプション) タグをキーと値の組み合わせとしてアタッチすることで、メタデータをストリーミングに追加します。ストリームにタグを追加すると、台帳の整理と識別がしやすくなります。詳細については、「Amazon QLDB リソースのタグ付け」を参照してください。

      [Add tag (タグの追加)] を選択し、必要に応じて、任意のキーと値の組み合わせを入力します。

  5. 設定が正しいことを確認したら、[Create QLDB stream] (QLDB ストリームを作成) を選択します。

    リクエストの送信が正常に完了すると、コンソールがメインの [Streams] (ストリーム) ページに戻り、QLDB ストリーミングが最新のステータスで一覧表示されます。

  6. ストリーミングがアクティブになったら、Kinesis を使用して、コンシューマーアプリケーションでストリーミングデータを処理します。

    Kinesis Data Streams コンソール (https://console.aws.amazon.com/kinesis/) を開きます。

ストリームデータレコード形式の詳細については、「Kinesis での QLDB ストリーミングレコード」を参照してください。

エラーの原因となるストリームの処理方法については、「障害のあるストリームの処理」を参照してください。

ストリームをキャンセルするには (コンソール)

キャンセルすると、QLDB ストリーミングは再開できません。Kinesis Data Streams へのデータの配信を再開するには、新しい QLDB ストリーミングを作成します。

  1. Amazon QLDB コンソール (https://console.aws.amazon.com/qldb) を開きます。

  2. ナビゲーションペインで、[ストリーム] を選択します。

  3. QLDB ストリーミングのリストで、キャンセルするアクティブなストリーミングを選択します。

  4. [Cancel stream (ストリームをキャンセル)] を選択します。表示されたボックスに「cancel stream」と入力して、削除を確定します。

AWS SDK または で QLDB API を使用してジャーナルストリームを作成および管理 AWS CLI する方法の詳細については、「」を参照してくださいQLDB でのストリーミングを使用した開発。

ストリームの状態

QLDB ストリーミングのステータスは、以下のいずれかになります。

  • ACTIVE - 現在、データのストリーミング中またはストリーミングを待機 (終了時刻が指定されていない無期限ストリーミングの場合) しています。

  • COMPLETED - 指定された時間範囲内のすべてのジャーナルブロックのストリーミングが正常に完了しました。これは終了状態です。

  • CANCELED - 指定された終了時刻より前にユーザーのリクエストによって終了し、データのストリーミングはアクティブではありません。これは終了状態です。

  • IMPAIRED - アクションが必要なエラーが発生したため、レコードを Kinesis に書き込めません。これは、回復可能な非終端状態です。

    1 時間以内にエラーを解決すると、ストリームは自動的に ACTIVE 状態に移行します。1 時間経過してもエラーが未解決のままである場合、ストリームは自動的に FAILED 状態に移行します。

  • FAILED - エラーのため、レコードを Kinesis に書き込めず、回復不能な終了状態です。

次の図は、QLDB ストリーミングリソースの状態がどのように遷移するかを示しています。

QLDB ストリーミングリソースがアクティブ状態、キャンセル状態、完了状態、障害状態、および失敗状態の間でどのように遷移するかを示す状態図。

端末ストリームの有効期限

端末状態 (CANCELED、COMPLETED、および FAILED) のストリームリソースには、7 日間の保持期間が適用されます。この制限の有効期限が切れると、自動的にハード削除されます。

終了状態のストリーミングが削除されると、QLDB コンソールまたは QLDB API を使用してストリーミングリソースの詳細取得または一覧表示ができなくなります。

障害のあるストリームの処理

ストリーミングでエラーが発生した場合は、IMPAIRED 状態にまず移行します。QLDB は引き続き IMPAIRED ストリーミングを最大 1 時間再試行します。

1 時間以内にエラーを解決すると、ストリームは自動的に ACTIVE 状態に移行します。1 時間経過してもエラーが未解決のままである場合、ストリームは自動的に FAILED 状態に移行します。

障害のあるストリームまたは失敗したストリームには、次のいずれかのエラー原因があります。

  • KINESIS_STREAM_NOT_FOUND - ストリーミング先の Kinesis Data Streams リソースは存在しません。QLDB ストリーミングリクエストで指定した Kinesis データストリームが正しいことを確認します。次に、Kinesis に移動し、指定したデータストリームを作成します。

  • IAM_PERMISSION_REVOKED - QLDB に、指定した Kinesis データストリームにデータレコードを書き込むための十分な許可がありません。以下のアクションに対して QLDB サービス (qldb.amazonaws.com) 許可を付与する、指定した Kinesis データストリーム用のポリシーを定義していることを確認します。

    • kinesis:PutRecord

    • kinesis:PutRecords

    • kinesis:DescribeStream

    • kinesis:ListShards

障害のあるストリームのモニタリング

ストリーミングに障害が発生すると、ストリーミングに関する詳細と発生したエラーを示すバナーが QLDB コンソールに表示されます。DescribeJournalKinesisStream API オペレーションを使用して、ストリーミングのステータスと基になっているエラー原因を取得することもできます。

また、Amazon CloudWatch を使用して、ストリーミングの IsImpaired メトリクスをモニタリングするアラームを作成することもできます。CloudWatch で QLDB メトリクスをモニタリングする方法については、「Amazon QLDB のディメンションとメトリクス」を参照してください。