QLDB シェルを使用した Amazon QLDB へのアクセス(データプレーンのみ) - Amazon Quantum Ledger Database (Amazon QLDB)

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

QLDB シェルを使用した Amazon QLDB へのアクセス(データプレーンのみ)

Amazon QLDB には、トランザクションデータプレーンとやり取りするためのコマンドラインシェルが用意されています。QLDB シェルを使用すると、PartiQL元帳データのステートメント。このシェルは Python で記述されており、GitHub リポジトリ awslabs/amazon-qldb-shell でオープンソースとして公開されています。

注記

Amazon QLDB シェルは、qldb-sessionトランザクションデータAPIです。この API は、QLDB 台帳に対して PartiQL ステートメントを実行するためにのみ使用します。

コマンドラインインターフェイスを使用して qldb コントロールプレーン API アクションとやり取りするには、「を使用して Amazon QLDB にアクセスするAWS CLI(コントロールプレーンのみ)」を参照してください。

このツールは、アプリケーションに組み込んだり、本番環境で採用したりすることを意図したものではありません。このツールの目的は、QLDB と PartiQL を迅速に試すことです。

次のセクションでは、QLDB シェルの使用を開始する方法について説明します。

Prerequisites

QLDB シェルの使用を開始する前に、次のことを行う必要があります。

  1. Amazon QLDB へのアクセス」にある AWS の設定手順に従います。これには以下が含まれます。

    1. AWS にサインアップする。

    2. を作成するAWS Identity and Access Management(IAM) ユーザーに適切な QLDB アクセス許可を付与します。

    3. 開発用の IAM アクセスキーを取得します。

  2. Python ダウンロードサイトから Python バージョン 3.4 以降をインストールします。

  3. AWS の認証情報とデフォルトの AWS リージョンを設定します。手順については、以下を参照してください。クイックスタート()AWS SDK for Python (Boto3)ドキュメント内) を参照してください。

    使用可能なリージョンの完全なリストについては、Amazon QLDB エンドポイントとクォータ()AWSの全般的なリファレンス

  4. の任意の元帳についてSTANDARD権限モード、作成AWS Identity and Access Management(IAM) ポリシーで、適切なテーブルで PartiQL ステートメントを実行するアクセス権限を付与します。

    重要

    これらのアクセス許可に加えて、特にqldb:PartiQLSelect元帳のカタログリソースに対する権限information_schema/user_tables。シェルでは、システムカタログテーブルのクエリにこのアクセスが必要ですschema.user_tables。この権限がないと、シェルは初期化に失敗します。

    これらのポリシーを作成する方法については、」Amazon QLDB の標準アクセス許可モードの使用を開始する

シェルのセットアップ

を使用して PyPI から QLDB シェルをインストールするにはpip3(Python 3 のパッケージマネージャー) を使用するには、コマンドラインターミナルで以下のコマンドを実行します。

$ pip3 install qldbshell

シェルをインストールすると、以下の必須のパッケージ依存関係もインストールされます。

  • pyqldb— バージョンまでのみ必要1.1.0シェルの場合。バージョンから開始1.2.0では、シェルは QLDB ドライバーを内部的にパッケージ化し、このパッケージを個別の依存関係としてインストールする必要はなくなりました。

  • amazon.ion

  • argparse

  • boto3

シェルは、Python用のQLDBドライバの最新バージョン(3.x)と互換性がありません(pyqldb). 最新バージョンがインストールされている場合は、ドライバの依存関係を解決する追加のセットアップ手順については、を参照してください。

シェルのアップグレード

シェルの以前のバージョンがインストールされている場合は、次のコマンドを実行して、シェルを最新バージョンにアップグレードします。

注記

QLDBシェルのバージョン1.1.0では、単一のトランザクションで複数のステートメントを実行し、複数の行にまたがるステートメントを実行するためのサポートが導入されています。

シェルの最新バージョンは下位互換性があるため、アップグレードしても以前のバージョンは壊れません。

  1. シェルを最新バージョンにアップグレードします。

    $ pip3 install --upgrade qldbshell
  2. QLDB ドライバをアンインストールします。シェルの最新バージョンでは、このパッケージを個別の依存関係としてインストールする必要はなくなりました。

    $ pip3 uninstall pyqldb
  3. シェルの現在のバージョンを確認するには、次のコマンドを実行して、インストールされているパッケージを表示します。

    $ pip3 list

    シェルは、呼び出すと、現在のバージョンも表示します。

シェルの呼び出し

コマンドラインターミナルで特定の台帳に対して QLDB シェルを呼び出すには、次のコマンドを実行します。test-ledger を台帳名に置き換えます。

$ qldbshell --ledger test-ledger

このコマンドはデフォルトの AWS リージョンに接続します。リージョンを明示的に指定するには、次のセクションで説明するように、--region パラメータを指定してコマンドを実行できます。

を呼び出した後qldbshellセッションでは、次の方法を使用して PartiQL ステートメントを入力できます。

サポートされているキーとコマンドのリストについては、コマンドリファレンス

接続パラメータ

使用可能な入力引数のリストを表示するには、qldbshell セッションを呼び出す前に以下のコマンドを実行します。

$ qldbshell --help

以下の接続パラメータは、qldbshell コマンドで使用できます。オプションの引数を追加して、シェルが使用する AWS リージョン、認証情報プロファイル、エンドポイントを上書きできます。

使用構文:

$ qldbshell -l LEDGER_NAME [-v] [-p PROFILE] [-r REGION_CODE] [-s QLDB_SESSION_ENDPOINT]

必須の引数

-l LEDGER_NAME
--ledger LEDGER_NAME

シェルが接続する台帳の名前を指定します。台帳名はすでに存在し、アクティブであることが必要です。

オプションの引数

-v
--verbose

シェルセッションの出力の詳細度を上げます。

-p PROFILE
--profile PROFILE

シェルが認証に使用する AWS 認証情報プロファイルの場所を指定します。

指定しない場合、シェルは、~/.aws/credentials にあるデフォルトの AWS プロファイルを使用します。

-r REGION_CODE
--r region REGION_CODE

を指定します。AWSシェルが接続する QLDB 台帳のリージョンコード。例: us-east-1

指定しない場合、シェルは、AWS プロファイルで指定されたデフォルトの AWS リージョンに接続します。

-s QLDB_SESSION_ENDPOINT
--qldb-session-endpoint QLDB_SESSION_ENDPOINT

シェルが接続する qldb-session API エンドポイントを指定します。

利用可能な QLDB リージョンとエンドポイントの全リストについては、Amazon QLDB エンドポイントとクォータ()AWSの全般的なリファレンス

パラメータファイル

コマンドラインで引数を渡す代わりに、入力パラメータをファイルに保存することもできます。各パラメータは別々の行に配置します。次に、以下のようにファイル名を qldbshell に渡します。置換params.confをファイル名に置き換えます。

$ qldbshell @params.conf

コマンドリファレンス

あなたが呼び出した後qldbshellセッションでは、シェルは次のキーとコマンドをサポートします。

QLDB シェルのキー
キー 関数の説明
Enter 文を実行します。

Option+Enter(macOS)

Escape+Enter(Windows)

複数の行にまたがる文を入力するために、新しい行を開始します。セットアップ手順については、Optionキーを macOS のメタキーとして使用する方法については、OS X デイリーサイト.

複数行の入力テキストをコピーしてシェルに貼り付けることもできます。

Tab 部分的な単語をオートコンプリートし、QLDB PartiQLを提案する予約語現在の元帳内のアクティブなテーブル名が表示されます。
Ctrl+C 現在のコマンドをキャンセルします。
Ctrl+D 現在のを終了します。qldbshellセッション。
QLDB シェルのコマンド
コマンド 関数の説明
help ヘルプセクションを表示します。
start トランザクションを開始します。
commit 取引を元帳の仕訳にコミットします。
abort トランザクションをキャンセルし、行った変更を拒否します。
clear 画面をクリアします。
exit 現在のを終了します。qldbshellセッション。
quit
注記

すべての QLDB シェルのコマンドでは大文字と小文字が区別されません。

個々のステートメントの実行

QLDB シェルコマンドは、コマンドリファレンスシェルは、入力する各コマンドを個別の PartiQL ステートメントとして解釈します。デフォルトでは、シェルは暗黙的に独自のトランザクション内の各ステートメントを実行し、エラーが見つからなかった場合は自動的にトランザクションをコミットします。

トランザクションの管理

または、QLDB シェルでは、トランザクションを手動で制御できます。トランザクション内で複数のステートメントを対話的に実行することも、コマンドとステートメントを連続してバッチ処理して非対話的に実行することもできます。

対話型のトランザクション

インタラクティブトランザクションを実行するには、次のステップを実行します。

  1. トランザクションを開始するには、startコマンド。

    qldbshell > start

    トランザクションを開始すると、コマンドプロンプトに現在のシステムで割り当てられているトランザクション ID が表示されます。たとえば、トランザクション ID がFMovDwupxJG3k466iz4i75、シェルは、次のコマンドプロンプトを表示します。

    qldbshell (tx:FMoVdWuPxJg3k466Iz4i75) >
  2. 次に、入力した各ステートメントは、同じトランザクションで実行されます。

    • たとえば、次のように 1 つのステートメントを実行できます。

      qldbshell (tx:FMoVdWuPxJg3k466Iz4i75) > SELECT * FROM Vehicle WHERE VIN = '1N4AL11D75C109151'

      を押した後Enterの場合、シェルはステートメントの結果を表示します。

    • 次のように、複数のステートメントまたはコマンドをセミコロンで区切って入力することもできます。

      qldbshell (tx:FMoVdWuPxJg3k466Iz4i75) > SELECT * FROM Vehicle WHERE VIN = '1N4AL11D75C109151'; commit
  3. トランザクションを終了するには、次のコマンドのいずれかを入力します。

    • 「」と入力します。commitコマンドを使用して、トランザクションを元帳の仕訳帳にコミットします。

      qldbshell (tx:FMoVdWuPxJg3k466Iz4i75) > commit Transaction with transaction ID FMoVdWuPxJg3k466Iz4i75 committed
    • 「」と入力します。abortコマンドを使用すると、トランザクションをキャンセルし、行った変更を拒否できます。

      qldbshell (tx:FMoVdWuPxJg3k466Iz4i75) > abort Transaction with transaction ID FMoVdWuPxJg3k466Iz4i75 aborted

トランザクションタイムアウト制限

対話型トランザクションは、QLDBのトランザクションタイムアウト制限。トランザクションをコミットしない場合30 秒を起動すると、QLDB は自動的にトランザクションを期限切れにし、トランザクション中に行われた変更を拒否します。

次に、ステートメントの結果を表示する代わりに、シェルは有効期限エラーメッセージを表示し、通常のコマンドプロンプトに戻ります。入力する必要がありますstartコマンドを再度実行して、新しいトランザクションを開始します。

Transaction with ID FMoVdWuPxJg3k466Iz4i75 expired. Aborting transaction.

非対話型のトランザクション

コマンドとステートメントを次のように順番にバッチ処理することで、複数のステートメントで完全なトランザクションを実行できます。

qldbshell > start; SELECT * FROM Vehicle WHERE VIN = '1N4AL11D75C109151'; SELECT * FROM Person p, DriversLicense l WHERE p.GovId = l.LicenseNumber; commit

各コマンドとステートメントは、セミコロン (;). トランザクション内のステートメントが有効でない場合、シェルは自動的にトランザクションを拒否します。シェルは、入力した後続のステートメントを続行しません。

複数のトランザクションを設定することもできます。

qldbshell > start; statement1; commit; start; statement2; statement3; commit

前の例と同様に、トランザクションが失敗した場合、シェルは入力した後続のトランザクションまたはステートメントを続行しません。

トランザクションを終了しない場合、シェルは対話モードに切り替わり、次のコマンドまたはステートメントの入力を求めるプロンプトを表示します。

qldbshell > start; statement1; commit; start qldbshell (tx:FMoVdWuPxJg3k466Iz4i75) >

シェルの終了

カレントを終了するにはqldbshellセッションを終了して現在の台帳データベース接続を閉じるには、exitまたはquitコマンド。

qldbshell > exit $
qldbshell > quit $

Example

QLDB での PartiQL ステートメントの記述については、Amazon QLDB PartiQL リファレンス

以下の例では、基本的なコマンドの一般的なシーケンスを示しています。

注記

QLDB シェルは、この例の各 PartiQL ステートメントを独自のトランザクションで実行します。

この例では、台帳 test-ledger がすでに存在し、アクティブであると想定しています。

$ qldbshell --ledger test-ledger --region us-east-1 qldbshell > CREATE TABLE TestTable qldbshell > INSERT INTO TestTable `{"Name": "John Doe"}` qldbshell > SELECT * FROM TestTable qldbshell > DROP TABLE TestTable qldbshell > exit

一般的なエラー

このセクションでは、QLDB シェルの使用中に発生する可能性のある一般的なエラーを解決する手順を説明します。

ドライバの依存関係を解決する

QLDBシェル(バージョンまで1.1.0) には、Python バージョン 2.x 用の QLDB ドライバ (2.0.0,2.0.1, または2.0.2) を別個の依存関係としてインストールする必要があります。互換性のないバージョンのドライバがインストールされている場合は、次のいずれかのエラーメッセージが表示されることがあります。

ModuleNotFoundError: No module named 'pyqldb.driver.pooled_qldb_driver'
ERROR: pyqldb 3.0.0rc1 has requirement amazon.ion<0.6,>=0.5.0, but you'll have amazon-ion 0.6.0 which is incompatible.

このドライバの依存関係の問題を解決するには、以前のバージョンにダウングレードできます。または、古いバージョンのドライバをインストールする仮想環境でシェルを実行することもできます。

ドライバをバージョン 2.x にダウングレードするには

  1. 最新バージョンのドライバーをアンインストールします。

    $ pip3 uninstall pyqldb
  2. バージョンのインストール2.0.2ドライバーの。

    注記

    バージョンを使用している場合は、このステップを省略できます1.2.0またはそれ以降のシェルです。最新バージョンのシェルは QLDB ドライバーを内部的にパッケージ化し、このパッケージを個別にインストールする必要はなくなりました。

    $ pip3 install pyqldb==2.0.2

仮想環境でシェルを実行するには

  1. のインストールvirtualenv.

    $ pip3 install virtualenv
  2. 仮想環境を作成します。置き換えることができますベンブを独自の環境名に置き換えます。

    $ virtualenv venv
  3. 仮想環境をアクティブ化します。置換ベンブ前のステップで作成した環境名に置き換えます。

    $ source venv/bin/activate
  4. QLDB シェルをインストールします。

    $ pip3 install qldbshell
  5. に進みます。シェルの呼び出し仮想環境でシェルを実行します。

  6. シェルの使用が終了したら、仮想環境を非アクティブ化できます。

    $ deactivate