Amazon QLDB 台帳の基本操作 - Amazon Quantum Ledger Database (Amazon QLDB)

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

Amazon QLDB 台帳の基本操作

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

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

これらのオペレーションを完全なサンプルアプリケーションで実行するコード例については、以下のドライバーの使用方法チュートリアルと GitHub リポジトリを以下に示します。

台帳の作成

を使用するCreateLedgerオペレーションを使用して、AWSアカウント. 以下の情報を指定する必要があります。

  • 台帳名— アカウントに作成する台帳の名前。名前は、現在のすべての台帳間で一意である必要があります。AWSリージョン。

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

  • アクセス許可モード— 台帳に割り当てるアクセス許可モード。次のいずれかのオプションを選択します。

    • すべて許可— 元帳の API レベルの細分性によるアクセス制御を可能にするレガシー権限モード。

      このモードでは、SendCommandこの元帳がすべてのPartiQLコマンドを実行するためのAPI権限(したがって、ALLOW_ALL) を、指定された元帳内の任意のテーブルに適用します。このモードでは、元帳に対して作成するテーブルレベルまたはコマンドレベルの IAM アクセス権限ポリシーは無視されます。

    • Standard— (推奨) 元帳、テーブル、および PartiQL コマンドの細かいアクセス制御を可能にするパーミッションモード。元帳データのセキュリティを最大化するために、この権限モードを使用することを強くお勧めします。

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

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

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

  • AWS KMS key—(オプション)AWS Key Management Service(AWS KMS) を使用して、保管時のデータの暗号化を行います。以下のいずれかを選択します。AWS KMS keys:

    • AWS所有の KMS キー— によって所有、管理されます。AWSユーザーに代わって処理します。

      元帳の作成時にこのパラメータを定義しない場合、元帳では既定でこのタイプのキーが使用されます。また、文字列AWS_OWNED_KMS_KEYこのキーのタイプを指定します。このオプションでは、追加の設定は必要ありません。

    • お客様が管理する KMS キー— 作成、所有、管理しているアカウントに対称 KMS キーを使用します。QLDB では、非対称キー

      このオプションを使用するには、KMS キーを作成するか、アカウント内の既存のキーを使用する必要があります。カスタマー管理型キーを作成する手順については、対称 KMS キーの作成AWS Key Management Serviceデベロッパーガイド

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

      注記

      クロスリージョンキーはサポートされていません。指定した KMS キーは同じAWS台帳としてのリージョン。

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

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

QLDB によって作成され、そのステータスがに設定されるまでは、台帳を使用できません。ACTIVE

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);

という名前の新しい台帳を作成します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::QLDB::LedgerリソースのAWS CloudFormationユーザーガイド

台帳の説明

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

  • 台帳名— 説明する台帳の名前。

  • ARN— 台帳の Amazon リソースネーム (ARN)。形式は以下のとおりです。

    arn:aws:qldb:aws-region:account-id:ledger/ledger-name
  • 削除保護— 削除保護機能が有効になっているかどうかを示すフラグ。

  • 作成日時— 台帳が作成された日時(エポック時刻形式)。

  • 州/地域— 台帳の現在のステータス。これには、次のいずれかの値を指定できます。

    • CREATING

    • ACTIVE

    • DELETING

    • DELETED

  • アクセス許可モード— 台帳に割り当てられているアクセス許可モードです。これには、次のいずれかの値を指定できます。

    • ALLOW_ALL— 元帳の API レベルの細分性によるアクセス制御を可能にするレガシー権限モード。

    • STANDARD— 元帳、テーブル、および PartiQL コマンドの細かいアクセス制御を可能にするパーミッションモード。

  • 暗号化の説明— 台帳内の保管時のデータの暗号化に関する情報。これには、次の項目が含まれます。

    • AWS KMS keyARN— 顧客管理の KMS キーの ARN で、元帳が保管時の暗号化に使用します。これが未定義の場合は、台帳はAWS暗号化用の KMS キーの所有です。

    • 暗号化ステータス— 台帳の保管時の暗号化の現在のステータス。これには、次のいずれかの値を指定できます。

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

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

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

      • KMS_KEY_INACCESSIBLE— 指定された顧客管理の KMS キーにアクセスできず、元帳に障害があります。キーが無効になっているか、削除されているか、またはキーの許可が取り消されました。元帳に障害がある場合、その元帳にアクセスできず、読取り要求または書込み要求を受け付けません。

        障害のある元帳は、キーの許可を復元した後、または無効になったキーを再度有効にすると、自動的に有効な状態に戻ります。ただし、お客様が管理する KMS キーを削除することは元に戻せません。キーを削除すると、そのキーで保護されている台帳にアクセスできなくなります。これは、そのデータが永続不能になることを意味します。

    • アクセス不能AWS KMS key— エラー時に KMS キーが最初にアクセス不能になった日時 (エポック時刻形式)。

      KMS キーにアクセスできる場合、これは未定義です。

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

注記

QLDB 台帳を作成した後、そのステータスがCREATINGACTIVE

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());

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

aws qldb describe-ledger --name vehicle-registration

台帳の更新

-UpdateLedger操作では、現在のところ、既存の元帳の次の構成設定を変更できます。

  • 削除保護— ユーザーが台帳を削除できないようにするフラグ。この機能が有効になっている場合は、まず無効にする必要があります。これは、フラグをfalse元帳を削除する前に。

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

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

    注記

    Amazon QLDB は、カスタマーマネージドのサポートを開始しましたAWS KMS keys2021年7月22日。起動前に作成された元帳は、AWS 所有のキーに設定されていますが、現在、カスタマー管理キーを使用した保存時の暗号化には適していません。

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

    • AWS所有の KMS キー— によって所有、管理されます。AWSユーザーに代わって処理します。このタイプのキーを使用するには、文字列AWS_OWNED_KMS_KEYこのパラメーターの場合。このオプションでは、追加の設定は必要ありません。

    • お客様が管理する KMS キー— 作成、所有、管理しているアカウントに対称 KMS キーを使用します。QLDB では、非対称キー

      このオプションを使用するには、KMS キーを作成するか、アカウント内の既存のキーを使用する必要があります。カスタマー管理型キーを作成する手順については、対称 KMS キーの作成AWS Key Management Serviceデベロッパーガイド

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

      注記

      クロスリージョンキーはサポートされていません。指定した KMS キーは同じAWS台帳としてのリージョン。

    QLDB の主な変更は非同期です。キーの変更が処理されている間、元帳はパフォーマンスに影響を及ぼすことなく、完全にアクセス可能です。

    キーは必要なだけ頻繁に切り替えることができますが、キーの更新にかかる時間は、元帳のサイズによって異なります。♪DescribeLedger操作を使用して、静止時の暗号化の状態をチェックします。

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

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

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);

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 レベルの細分性によるアクセス制御を可能にするレガシー権限モード。

    このモードでは、SendCommandこの元帳がすべてのPartiQLコマンドを実行するためのAPI権限(したがって、ALLOW_ALL) を、指定された元帳内の任意のテーブルに適用します。このモードでは、元帳に対して作成するテーブルレベルまたはコマンドレベルの IAM アクセス権限ポリシーは無視されます。

  • Standard— (推奨) 元帳、テーブル、および PartiQL コマンドの細かいアクセス制御を可能にするパーミッションモード。元帳データのセキュリティを最大化するために、この権限モードを使用することを強くお勧めします。

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

重要

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

を使用して台帳アクセス許可モードを更新するには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);

割り当てるSTANDARD権限モードをvehicle-registration台帳です。

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権限モードを使用します。詳細については、「AWSAmazon QLDB の管理ポリシー」を参照してください。

台帳の削除

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

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

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

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);

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

aws qldb delete-ledger --name vehicle-registration

台帳の一覧表示

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

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アカウントとリージョン。

aws qldb list-ledgers