Amazon QLDB台帳の基本オペレーション

重要

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

QLDB API または AWS Command Line Interface （AWS CLI) を使用して、Amazon で台帳を作成、更新、削除できますQLDB。アカウントのすべての台帳を一覧表示したり、特定の台帳に関する情報を取得したりもできます。

以下のトピックでは、 AWS SDK for Java および を使用した台帳オペレーションの一般的なステップを示す短いコード例を示します AWS CLI。

完全なサンプルアプリケーションでこれらのオペレーションを示すコード例については、以下のドライバーの開始方法チュートリアルと GitHub リポジトリを参照してください。

• Java: チュートリアル | GitHub リポジトリ

• Node.js: チュートリアル | GitHub リポジトリ

• Python: チュートリアル | GitHub リポジトリ

台帳の作成

CreateLedger オペレーションを使用して、 AWS アカウントに台帳を作成します。これには、以下の情報を入力する必要があります。

• [Ledger name] (台帳名) - アカウントに作成する台帳の名前。この名前は現在の AWS リージョンのすべての台帳間で一意であることが必要です。

  台帳名の命名に関する制約は「Amazon のクォータと制限 QLDB」で定義されています。

• [Permissions mode] (アクセス許可モード) – 台帳に割り当てるアクセス許可モード。以下のオプションのいずれかを選択します。

  • すべて許可 — 台帳の APIレベルの粒度でアクセスコントロールを可能にするレガシーアクセス許可モード。

    このモードでは、この台帳のSendCommandAPIアクセス許可を持つユーザーが、指定された台帳内の任意のテーブルですべての PartiQL コマンド (つまり、ALLOW_ALL) を実行できます。このモードでは、台帳用に作成したテーブルレベルまたはコマンドレベルのIAMアクセス許可ポリシーは無視されます。

  • [Standard] (標準) - (推奨) 台帳、テーブル、PartiQL コマンドの、より詳細なレベルのアクセスコントロールを可能にするアクセス許可モード。台帳データのセキュリティを最大化する、このアクセス許可モードの使用を強く推奨します。

    デフォルトでは、このモードは、この台帳内の任意のテーブルで、任意の PartiQL コマンドを実行するすべてのリクエストを拒否します。PartiQL コマンドを許可するには、台帳のIAMアクセス許可に加えて、特定のテーブルリソースと PartiQL アクションのSendCommandAPIアクセス許可ポリシーを作成する必要があります。詳細については、「Amazon での標準アクセス許可モードの開始方法 QLDB」を参照してください。

• [Deletion protection] (削除保護) - (オプション) ユーザーが台帳を削除できないようにするフラグ。台帳の作成時に指定しない場合、この機能はデフォルトで有効 (true) です。

  削除保護が有効になっている場合は、台帳を削除する前に、まず無効にする必要があります。無効にするには、UpdateLedger オペレーションを使用してフラグを false に設定します。

• AWS KMS key — (オプション) 保管中のデータの暗号化に使用する AWS Key Management Service (AWS KMS) のキー。次のいずれかの種類の AWS KMS keysを選択します。

  • AWS 所有KMSキー – ユーザーに代わって が所有および管理するKMSキー AWS を使用します。

    台帳の作成時にこのパラメータを定義しない場合、台帳ではデフォルトでこの種類のキーを使用します。このキーの種類を指定するときに文字列 AWS_OWNED_KMS_KEY を使用することもできます。このオプションには追加のセットアップは必要ありません。

  • カスタマーマネージドKMSキー – 作成、所有、管理するアカウントで対称暗号化KMSキーを使用します。QLDB は非対称キー をサポートしていません。

    このオプションでは、アカウントでKMSキーを作成するか、既存のキーを使用する必要があります。カスタマーマネージドキーの作成手順については、「 デベロッパーガイド」の「対称暗号化KMSキーの作成」を参照してください。 AWS Key Management Service

    ID、エイリアス、または Amazon リソースネーム () を使用して、カスタマーマネージドKMSキーを指定できますARN。詳細については、「 AWS Key Management Service デベロッパーガイド」の「キー識別子 (KeyId）」を参照してください。

    注記

    クロスリージョンキーはサポートされていません。指定されたKMSキーは台帳と同じ AWS リージョン にある必要があります。

  詳細については、「Amazon での保管時の暗号化 QLDB」を参照してください。

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

台帳は、 が台帳QLDBを作成し、そのステータスを に設定するまで、使用する準備ができていませんACTIVE。

台帳の作成 (Java)

を使用して台帳を作成するには AWS SDK for Java

1. AmazonQLDB クラスのインスタンスを作成します。

2. リクエスト情報を指定する CreateLedgerRequest クラスのインスタンスを作成します。

   台帳名とアクセス許可モードを指定する必要があります。

3. リクエストオブジェクトをパラメータとして指定して、createLedger メソッドを実行します。

createLedger リクエストは、台帳に関する情報を含む CreateLedgerResult オブジェクトを返します。DescribeLedger オペレーションを使用して台帳の作成後に台帳のステータスを確認する例については、次のセクションを参照してください。

次の例は、前述のステップを示しています。

例 — 既定の構成設定を使用する

AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
CreateLedgerRequest request = new CreateLedgerRequest()
        .withName(ledgerName)
        .withPermissionsMode(PermissionsMode.STANDARD);
CreateLedgerResult result = client.createLedger(request);

注記

台帳では、指定しない場合、次のデフォルト設定が使用されます。

• 削除保護 - 有効 (true)。

• KMS キー AWS 所有KMSキー。

例 – 削除保護の無効化、カスタマーマネージドKMSキーの使用、タグのアタッチ

AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();

Map<String, String> tags = new HashMap<>();
tags.put("IsTest", "true");
tags.put("Domain", "Test");

CreateLedgerRequest request = new CreateLedgerRequest()
        .withName(ledgerName)
        .withPermissionsMode(PermissionsMode.STANDARD)
        .withDeletionProtection(false)
        .withKmsKey("arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab")
        .withTags(tags);
CreateLedgerResult result = client.createLedger(request);

台帳の作成 (AWS CLI)

デフォルトの構成設定を使用して、vehicle-registration という名前の新しい台帳を作成します。

例

aws qldb create-ledger --name vehicle-registration --permissions-mode STANDARD

注記

台帳では、指定しない場合、次のデフォルト設定が使用されます。

• 削除保護 - 有効 (true)。

• KMS キー AWS 所有KMSキー。

または、 vehicle-registration という名前の新しい台帳を作成し、削除保護を無効にして、指定されたカスタマーマネージドKMSキーと指定されたタグを使用します。

例

aws qldb create-ledger \
    --name vehicle-registration \
    --no-deletion-protection \
    --permissions-mode STANDARD \
    --kms-key arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \
    --tags IsTest=true,Domain=Test

台帳の作成 (AWS CloudFormation)

また、AWS CloudFormation テンプレートを使用して台帳を作成することもできます。詳細については、「 AWS CloudFormation ユーザーガイド」のAWS「：QLDB:::Ledger」リソースを参照してください。

台帳の説明

DescribeLedger オペレーションを使用して、台帳に関する詳細を表示します。台帳名を指定する必要があります。DescribeLedger の出力は CreateLedger の出力と同じ形式です。次の情報が含まれています。

• [Ledger name] (台帳名) - 説明を表示する台帳の名前。

• ARN – 台帳の Amazon リソースネーム (ARN) を次の形式で指定します。

  arn:aws:qldb:aws-region:account-id:ledger/ledger-name

• [Deletion protection] (削除保護) - 削除保護機能が有効になっているかどうかを示すフラグ。

• [Creation date and time] (作成日時) - 台帳が作成された日時 (エポック時刻形式)。

• [State] (状態) - 台帳の現在のステータス。これは、以下の値のいずれかになります。

  • CREATING

  • ACTIVE

  • DELETING

  • DELETED

• [Permissions mode] (アクセス許可モード) – 台帳に割り当てられるアクセス許可モード。これは、以下の値のいずれかになります。

  • ALLOW_ALL – 台帳の APIレベルの粒度でアクセスコントロールを可能にするレガシーアクセス許可モード。

  • STANDARD - 台帳、テーブル、PartiQL コマンドの、より詳細なレベルのアクセスコントロールを可能にするアクセス許可モード。

• [Encryption description] (暗号化の説明) - 台帳の保管中のデータの暗号化に関する情報。これには以下の項目が含まれます。

  • AWS KMS key ARN – 台帳が保管時の暗号化に使用するカスタマーマネージドKMSキーARNの 。これが未定義の場合、台帳は暗号化に AWS 所有KMSキーを使用します。

  • [Encryption status] (暗号化ステータス) — 台帳の保管時の暗号化の現在のステータス。これは、以下の値のいずれかになります。

    • ENABLED — 暗号化は、指定されたキーを使用して完全に有効になります。

    • UPDATING — 指定されたキーの変更はアクティブに処理されています。

      の主な変更はQLDB非同期です。キーの変更が処理されている間も、パフォーマンスに影響を与えることなく、台帳にフルアクセスできます。キーの更新にかかる時間は、台帳のサイズによって異なります。

    • KMS_KEY_INACCESSIBLE – 指定されたカスタマーマネージドKMSキーにアクセスできず、台帳が損なわれます。キーが無効化または削除されたか、キーの許可が取り消されました。台帳に障害が発生すると、アクセスできず、読み取りまたは書き込みリクエストも受け付けません。

      障害のある台帳は、キーの許可を復元した後、または無効化されたキーを再度有効にした後に、自動的にアクティブ状態に戻ります。ただし、カスタマーマネージドKMSキーの削除は元に戻せません。キーを削除すると、そのキーで保護されている台帳にアクセスできなくなり、データが完全に回復不可能になります。

  • アクセス不可 AWS KMS key — エラーが発生した場合にキーがKMS最初にアクセス不能になった日時をエポック時間形式で表します。

    KMS キーがアクセス可能な場合、これは未定義です。

  詳細については、「Amazon での保管時の暗号化 QLDB」を参照してください。

注記

QLDB 台帳を作成すると、ステータスが から CREATINGに変わると、台帳を使用できるようになりますACTIVE。

台帳の説明 (Java)

を使用して台帳を記述するには AWS SDK for Java

1. AmazonQLDB クラスのインスタンスを作成します。または、CreateLedger リクエストに対してインスタンス化した AmazonQLDB クライアントの同じインスタンスを使用できます。

2. DescribeLedgerRequest クラスのインスタンスを作成し、説明を表示する台帳の名前を指定します。

3. リクエストオブジェクトをパラメータとして指定して、describeLedger メソッドを実行します。

4. describeLedger リクエストは、台帳に関する現在の情報を含む DescribeLedgerResult オブジェクトを返します。

以下のサンプルコードは、前述のステップの例です。クライアントの describeLedger メソッドを呼び出せば、いつでも台帳の情報を収集できます。

例

AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
DescribeLedgerRequest request = new DescribeLedgerRequest().withName(ledgerName);
DescribeLedgerResult result = client.describeLedger(request);
System.out.printf("%s: ARN: %s \t State: %s \t CreationDateTime: %s \t DeletionProtection: %s
                   \t PermissionsMode: %s \t EncryptionDescription: %s",
        result.getName(),
        result.getArn(),
        result.getState(),
        result.getCreationDateTime(),
        result.getDeletionProtection(),
        result.getPermissionsMode(),
        result.getEncryptionDescription());

台帳の説明 (AWS CLI)

作成した vehicle-registration 台帳の説明を表示します。

例

aws qldb describe-ledger --name vehicle-registration

台帳の更新

UpdateLedger オペレーションでは、既存台帳の次の構成設定を変更できます。

• [Deletion protection] (削除保護) - ユーザーが台帳を削除できないようにするフラグ。この機能が有効な場合は、台帳を削除するためにフラグを false に設定して無効にする必要があります。

  このパラメータを定義しない場合、台帳の削除保護設定は変更されません。

• AWS KMS key – 保管中のデータの暗号化に使用する AWS Key Management Service （AWS KMS) のキー。このパラメータを定義しない場合、台帳のKMSキーは変更されません。

  注記

  Amazon は、2021 年 7 月 22 AWS KMS keys 日にカスタマー管理のサポートQLDBを開始しました。起動前に作成された台帳は AWS 所有のキー デフォルトで によって保護されますが、現在、カスタマーマネージドキーを使用した保管時の暗号化の対象にはなりません。

  台帳の作成時刻は、 QLDBコンソールで確認できます。

  以下のいずれかのオプションを使用します。

  • AWS 所有KMSキー – ユーザーに代わって が所有および管理するKMSキー AWS を使用します。この種類のキーを使用するには、このパラメーターに文字列 AWS_OWNED_KMS_KEY を指定します。このオプションには追加のセットアップは必要ありません。

  • カスタマーマネージドKMSキー – 作成、所有、管理するアカウントで対称暗号化KMSキーを使用します。QLDB は非対称キー をサポートしていません。

    このオプションでは、アカウントでKMSキーを作成するか、既存のキーを使用する必要があります。カスタマーマネージドキーの作成手順については、「 デベロッパーガイド」の「対称暗号化KMSキーの作成」を参照してください。 AWS Key Management Service

    ID、エイリアス、または Amazon リソースネーム () を使用して、カスタマーマネージドKMSキーを指定できますARN。詳細については、「 AWS Key Management Service デベロッパーガイド」の「キー識別子 (KeyId）」を参照してください。

    注記

    クロスリージョンキーはサポートされていません。指定されたKMSキーは台帳と同じ AWS リージョン にある必要があります。

  の主な変更はQLDB非同期です。キーの変更が処理されている間も、パフォーマンスに影響を与えることなく、台帳にフルアクセスできます。

  キーは必要に応じて切り替えることができますが、キーの更新にかかる時間は、台帳のサイズによって異なります。DescribeLedger オペレーションを使用して保管時の暗号化のステータスを確認します。

  詳細については、「Amazon での保管時の暗号化 QLDB」を参照してください。

UpdateLedger の出力は CreateLedger の出力と同じ形式です。

台帳の更新 (Java)

を使用して台帳を更新するには AWS SDK for Java

1. AmazonQLDB クラスのインスタンスを作成します。

2. リクエスト情報を指定する UpdateLedgerRequest クラスのインスタンスを作成します。

   台帳名は、削除保護用の新しいブール値またはKMSキー用の新しい文字列値とともに指定する必要があります。

3. リクエストオブジェクトをパラメータとして指定して、updateLedger メソッドを実行します。

次のコード例は、前述のステップを示しています。updateLedger リクエストは、台帳に関する情報を更新した UpdateLedgerResult オブジェクトを返します。

例 - 削除保護の無効化

AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
UpdateLedgerRequest request = new UpdateLedgerRequest()
        .withName(ledgerName)
        .withDeletionProtection(false);
UpdateLedgerResult result = client.updateLedger(request);

例 – カスタマーマネージドKMSキーを使用する

AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
UpdateLedgerRequest request = new UpdateLedgerRequest()
        .withName(ledgerName)
        .withKmsKey("arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab")
UpdateLedgerResult result = client.updateLedger(request);

例 – AWS 所有KMSキーを使用する

AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
UpdateLedgerRequest request = new UpdateLedgerRequest()
        .withName(ledgerName)
        .withKmsKey("AWS_OWNED_KMS_KEY")
UpdateLedgerResult result = client.updateLedger(request);

台帳の更新 (AWS CLI)

vehicle-registration 台帳に対して削除保護が有効になっている場合は、台帳を削除する前に、まず無効にする必要があります。

例

aws qldb update-ledger --name vehicle-registration --no-deletion-protection

また、台帳の保管時の暗号化設定を変更して、カスタマーマネージドKMSキーを使用することもできます。

例

aws qldb update-ledger --name vehicle-registration --kms-key arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

または、保管時の暗号化設定を変更して、 AWS 所有KMSキーを使用することもできます。

例

aws qldb update-ledger --name vehicle-registration --kms-key AWS_OWNED_KMS_KEY

台帳アクセス許可モードの更新

UpdateLedgerPermissionsMode オペレーションでは、既存台帳のアクセス許可を変更できます。以下のオプションのいずれかを選択します。

• すべて許可 — 台帳の APIレベルの粒度でアクセスコントロールを可能にするレガシーアクセス許可モード。

  このモードでは、この台帳のSendCommandAPIアクセス許可を持つユーザーが、指定された台帳内の任意のテーブルですべての PartiQL コマンド (つまり、ALLOW_ALL) を実行できます。このモードでは、台帳用に作成したテーブルレベルまたはコマンドレベルのIAMアクセス許可ポリシーは無視されます。

• [Standard] (標準) - (推奨) 台帳、テーブル、PartiQL コマンドの、より詳細なレベルのアクセスコントロールを可能にするアクセス許可モード。台帳データのセキュリティを最大化する、このアクセス許可モードの使用を強く推奨します。

  デフォルトでは、このモードは、この台帳内の任意のテーブルで、任意の PartiQL コマンドを実行するすべてのリクエストを拒否します。PartiQL コマンドを許可するには、台帳のIAMアクセス許可に加えて、特定のテーブルリソースと PartiQL アクションのSendCommandAPIアクセス許可ポリシーを作成する必要があります。詳細については、「Amazon での標準アクセス許可モードの開始方法 QLDB」を参照してください。

重要

アクセスSTANDARD許可モードに切り替える前に、ユーザーの中断を避けるために、まず必要なIAMポリシーとテーブルタグをすべて作成する必要があります。詳細については、「標準アクセス許可モードへの移行」を参照してください。

台帳アクセス許可モードの更新 (Java)

を使用して台帳のアクセス許可モードを更新するには AWS SDK for Java

1. AmazonQLDB クラスのインスタンスを作成します。

2. リクエスト情報を指定する UpdateLedgerPermissionsModeRequest クラスのインスタンスを作成します。

   台帳名と、アクセス許可モードの新しい文字列値を指定する必要があります。

3. リクエストオブジェクトをパラメータとして指定して、updateLedgerPermissionsMode メソッドを実行します。

次のコード例は、前述のステップを示しています。updateLedgerPermissionsMode リクエストは、台帳に関する情報を更新した UpdateLedgerPermissionsModeResult オブジェクトを返します。

例 — 標準のアクセス許可モードを割り当てる

AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
UpdateLedgerPermissionsModeRequest request = new UpdateLedgerPermissionsModeRequest()
        .withName(ledgerName)
        .withPermissionsMode(PermissionsMode.STANDARD);
UpdateLedgerPermissionsModeResult result = client.updateLedgerPermissionsMode(request);

台帳アクセス許可モードの更新 (AWS CLI)

vehicle-registration 台帳に STANDARD アクセス許可モードを割り当てます。

例

aws qldb update-ledger-permissions-mode --name vehicle-registration --permissions-mode STANDARD

標準アクセス許可モードへの移行

アクセスSTANDARD許可モードに移行するには、QLDBアクセスパターンを分析し、ユーザーに リソースにアクセスするための適切なアクセス許可を付与するIAMポリシーを追加することをお勧めします。

アクセスSTANDARD許可モードに切り替える前に、まず必要なすべてのIAMポリシーとテーブルタグを作成する必要があります。それ以外の場合、アクセス許可モードを切り替えると、正しいIAMポリシーを作成するか、アクセス許可モードを に戻すまで、ユーザーが中断する可能性がありますALLOW_ALL。これらのポリシーの作成の詳細については、「Amazon での標準アクセス許可モードの開始方法 QLDB」を参照してください。

AWS 管理ポリシーを使用して、すべてのQLDBリソースへのフルアクセスを許可することもできます。AmazonQLDBFullAccess および AmazonQLDBConsoleFullAccess管理ポリシーには、すべての PartiQL QLDBアクションを含むすべてのアクションが含まれます。これらのポリシーの 1 つをプリンシパルにアタッチすることは、そのプリンシパルの ALLOW_ALL アクセス許可モードと等価です。詳細については、「AWS Amazon の マネージドポリシー QLDB」を参照してください。

台帳の削除

台帳とそのすべての内容を削除するには、DeleteLedger オペレーションを使用します。台帳の削除は回復不可能なオペレーションです。

台帳に対して削除保護が有効になっている場合は、台帳を削除する前に、まず無効にする必要があります。

DeleteLedger リクエストを発行すると、台帳の状態は ACTIVE から DELETING に変わります。台帳に使用されているストレージの量によっては、台帳を削除するのに時間がかかる場合があります。DeleteLedger オペレーションが終了すると、台帳は に存在しなくなりますQLDB。

台帳の削除 (Java)

を使用して台帳を削除するには AWS SDK for Java

1. AmazonQLDB クラスのインスタンスを作成します。

2. DeleteLedgerRequest クラスのインスタンスを作成し、削除する台帳の名前を指定します。

3. リクエストオブジェクトをパラメータとして指定して、deleteLedger メソッドを実行します。

以下のサンプルコードは、前述のステップの例です。

例

AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
DeleteLedgerRequest request = new DeleteLedgerRequest().withName(ledgerName);
DeleteLedgerResult result = client.deleteLedger(request);

台帳の削除 (AWS CLI)

vehicle-registration 台帳を削除します。

例

aws qldb delete-ledger --name vehicle-registration

台帳の一覧表示

ListLedgers オペレーションは、現在の AWS アカウント とリージョンのすべてのQLDB台帳の概要情報を返します。

台帳の一覧表示 (Java)

を使用してアカウント内の台帳を一覧表示するには AWS SDK for Java

1. AmazonQLDB クラスのインスタンスを作成します。

2. ListLedgersRequest クラスのインスタンスを作成します。

   前の ListLedgers 呼び出しからのレスポンスで NextToken の値を受け取った場合、結果の次のページを取得するには、このリクエストでその値を指定する必要があります。

3. リクエストオブジェクトをパラメータとして指定して、listLedgers メソッドを実行します。

4. listLedgers リクエストは ListLedgersResult オブジェクトを返します。このオブジェクトには、LedgerSummary オブジェクトのリストと、さらに結果があるかどうかを示すページ分割トークンが含まれます。

   • NextToken が空の場合、結果の最後のページが処理されており、それ以上の結果はありません。

   • NextToken が空でない場合、さらに結果があります。結果の次のページを取得するには、後続の ListLedgers 呼び出しで NextToken の値を使用します。

以下のサンプルコードは、前述のステップの例です。

例

AmazonQLDB client = AmazonQLDBClientBuilder.standard().build();
List<LedgerSummary> ledgerSummaries = new ArrayList<>();
String nextToken = null;
do {
    ListLedgersRequest request = new ListLedgersRequest().withNextToken(nextToken);
    ListLedgersResult result = client.listLedgers(request);
    ledgerSummaries.addAll(result.getLedgers());
    nextToken = result.getNextToken();
} while (nextToken != null);
     

台帳の一覧表示 (AWS CLI)

現在の AWS アカウント とリージョンのすべての台帳を一覧表示します。

例

aws qldb list-ledgers