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

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] (アクセス許可モード) – 台帳に割り当てるアクセス許可モード。以下のオプションのいずれかを選択します。

  • [Allow all] (すべて許可) - 台帳の API レベル詳細度でアクセスコントロールを可能にする、レガシーアクセス許可モード。

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

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

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

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

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

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

  • AWS 所有の KMS キー - ユーザーに代わって AWS が所有、管理している KMS キーを使用します。

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

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

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

    カスタマーマネージド KMS キーは、ID、エイリアス、または Amazon リソースネーム (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 QLDB は、カスタマーマネージド AWS KMS keysのサポートを 2021 年 7 月 22 日に開始しました。ローンチ前に作成された台帳は、デフォルトでは AWS 所有のキー によって保護されますが、カスタマーマネージドキーを使用した保管時の暗号化には現在適用されません。

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

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

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

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

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

    カスタマーマネージド KMS キーは、ID、エイリアス、または Amazon リソースネーム (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 オペレーションでは、既存台帳のアクセス許可を変更できます。以下のオプションのいずれかを選択します。

• [Allow all] (すべて許可) - 台帳の API レベル詳細度でアクセスコントロールを可能にする、レガシーアクセス許可モード。

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

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

  デフォルトでは、このモードは、この台帳内の任意のテーブルで、任意の PartiQL コマンドを実行するすべてのリクエストを拒否します。PartiQL コマンドを許可するには、台帳の SendCommand API アクセス許可に加えて、特定のテーブルリソースと PartiQL アクション用の IAM アクセス許可ポリシーを作成する必要があります。詳細については、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