Accès à Amazon QLDB à l'aide du shell QLDB (API de données uniquement)

Amazon QLDB fournit un shell de ligne de commande pour interagir avec l'API de données transactionnelles. Avec le shell QLDB, vous pouvez exécuter des instructions PartiQL sur des données de registre.

La dernière version de ce shell est écrite en Rust et est open source dans le GitHub référentiel awslabs/amazon-qldb-shell sur lamain branche par défaut. La version Python (v1) est également toujours disponible pour une utilisation dans le même référentiel de lamaster branche.

Note

Le shell Amazon QLDB prend uniquement en charge l'API de donnéesqldb-session transactionnelles. Cette API est uniquement utilisée pour exécuter des instructions partiQL sur un registre QLDB.

Pour interagir avec les opérations de l'APIqldb de gestion à l'aide d'une interface de ligne de commande, consultezAccès à Amazon QLDB à l'aide de (API AWS CLI de gestion uniquement).

Cet outil n'est pas destiné à être intégré à une application ou adopté à des fins de production. L'objectif de cet outil est de vous permettre d'expérimenter rapidement QLDB et PartiQL.

Les sections suivantes vous décrivent comment commencer à utiliser les shell QLDB.

Prérequis

Avant de commencer à utiliser QLDB, vous devez exécuter les opérations shell QLDB, procédez comme suit :

1. Suivez les instructions deAWS configuration dansAccès à Amazon QLDB. Cela inclut les éléments suivants :

   1. S'inscrire àAWS.

   2. Créer un utilisateur doté des autorisations QLDB appropriées.

   3. Accorder un accès par programmation à des fins de développement.

2. Configurez vosAWS informations d'identification et celles par défautRégion AWS. Pour obtenir des instructions, reportez-vous à la section Principes de base de la configuration dans le Guide deAWS Command Line Interface l'utilisateur.

   Pour obtenir la liste complète des régions disponibles, consultez les points de terminaison et les quotas Amazon QLDB dans le Références générales AWS.

3. Pour tous les registres en modeSTANDARD autorisations, créez des politiques IAM qui vous autorisent à exécuter des instructions partiQL sur les tables appropriées. Pour découvrir comment créer ces politiques, veuillez consulterCommencer à utiliser le mode d'autorisation standard dans Amazon QLDB.

Installation de la coque

Pour installer la dernière version du shell QLDB, consultez le fichier README.md sur GitHub. QLDB fournit des fichiers binaires prédéfinis pour Linux, macOS et Windows dans la section Releases du GitHub référentiel.

Pour macOS, le shell s'intègre auaws/tap Homebrew Tap. Pour installer le shell macOS à l'aide de Homebrew, exécutez les commandes suivantes.

$ xcode-select --install # Required to use Homebrew
$ brew tap aws/tap # Add AWS as a Homebrew tap
$ brew install qldbshell

Configuration

Après l'installation, le shell charge le fichier de configuration par défaut qui se trouve$XDG_CONFIG_HOME/qldbshell/config.ion lors de l'initialisation. Sous Linux et macOS, ce fichier se trouve généralement à l'adresse~/.config/qldbshell/config.ion. Si un tel fichier n'existe pas, le shell s'exécute avec les paramètres par défaut.

Vous pouvez créer unconfig.ion fichier manuellement après l'installation. Ce fichier de configuration utilise le format de données Amazon Ion. Voici un exemple deconfig.ion fichier minimal.

{
  default_ledger: "my-example-ledger"
}

S'ildefault_ledger n'est pas défini dans votre fichier de configuration, le--ledger paramètre est obligatoire lorsque vous appelez le shell. Pour obtenir la liste complète des options de configuration, consultez le fichier README.md sur GitHub.

Invoquer la coque

Pour appeler le shell QLDB sur votre terminal de ligne de commande pour un registre spécifique, exécutez la commande suivante. Remplacez my-example-ledgerpar le nom de votre registre.

$ qldb --ledger my-example-ledger

Cette commande se connecte à votre valeur par défautRégion AWS. Pour spécifier explicitement la région, vous pouvez exécuter la commande avec le--qldb-session-endpoint paramètre--region or, comme décrit dans la section suivante.

Après avoir appelé une sessionqldb shell, vous pouvez saisir les types de saisie suivants :

• Commandes Shell

• Instructions partiQL uniques dans des transactions distinctes

• Plusieurs instructions partiQL au sein d'une transaction

Paramètres de la coque

Pour obtenir la liste complète des indicateurs et des options disponibles pour appeler un shell, exécutez laqldb commande avec l'--helpindicateur, comme suit.

$ qldb --help

Vous trouverez ci-dessous quelques indicateurs clés et options pour laqldb commande. Vous pouvez ajouter ces paramètres facultatifs pour remplacer le profil d'informations d'identificationRégion AWS, le point de terminaison, le format des résultats et d'autres options de configuration.

Utilisation

$ qldb [FLAGS] [OPTIONS]

DRAPEAUX

-h, --help

Imprime les informations d'aide.

-v, --verbose

Configure la verbosité de la journalisation. Par défaut, le shell enregistre uniquement les erreurs. Pour augmenter le niveau de verbosité, répétez cet argument (par exemple,-vv). Le niveau le plus élevé-vvv correspond à latrace verbosité.

-V, --version

Imprime les informations de version.

OPTIONS

-l,--ledger NOM DU REGISTRE

Le nom du registre auquel se connecter. Il s'agit d'un paramètre de shell obligatoire s'ildefault_ledger n'est pas défini dans votreconfig.ion fichier. Dans ce fichier, vous pouvez définir des options supplémentaires, telles que la région.

-c,--config FICHIER DE CONFIGURATION

Le fichier dans lequel vous pouvez définir toutes les options de configuration du shell. Pour plus de détails sur le formatage et une liste complète des options de configuration, consultez le fichier README.md sur GitHub.

-f, --format ion|table

Format de sortie des résultats de votre requête. La valeur par défaut est ion.

-p,--profile PROFIL

L'emplacement de votre profilAWS d'informations d'identification à utiliser pour l'authentification.

S'il n'est pas fourni, le shell utilise votreAWS profil par défaut, qui se trouve à l'adresse~/.aws/credentials.

-r,--region REGION_CODE

Région AWSCode du registre QLDB auquel se connecter. Par exemple : us-east-1.

S'il n'est pas fourni, le shell se connecte à votre configuration par défaut,Région AWS comme indiqué dans votreAWS profil.

-s,--qldb-session-endpoint QLDB_SESSION_ENDPOINT

Le point de terminaison de l'qldb-sessionAPI auquel se connecter.

Pour obtenir la liste complète des régions et points de terminaison QLDB et quotas Amazon QLDB Amazon QLDB Amazon QLDB Amazon QLDB Amazon QLDB Amazon QLDB Amazon QLDB Amazon QLDB Amazon QLDB Références générales AWS

Référence de commande

Une fois que vous avez appelé uneqldb session, le shell prend en charge les clés et les commandes de base de données suivantes :

Clés Shell
Clé	Description de la fonction
Enter	Exécute la déclaration.
Escape+Enter (macOS, Linux) Shift+Enter (Windows)	Commence une nouvelle ligne pour saisir une instruction qui s'étend sur plusieurs lignes. Vous pouvez également copier le texte d'entrée comportant plusieurs lignes et le coller dans le shell. Pour obtenir des instructions sur la configurationOption plutôt qu'enEscape tant que clé méta dans macOS, consultez le site OS X Daily.
Ctrl+C	Annule la commande en cours.
Ctrl+D	Signale la fin du fichier (EOF) et quitte le niveau actuel du shell. Si aucune transaction n'est active, quitte le shell. Dans le cas d'une transaction active, annule la transaction.

Commandes de base de données Shell
Commande	Description de la fonction
help	Affiche les informations d'aide.
begin	Commence une transaction.
start transaction
commit	Enregistre votre transaction dans le journal du registre.
abort	Arrête votre transaction et rejette toutes les modifications que vous avez apportées.
exit	Quitte la coque.
quit

Note

Toutes les commandes shell QLDB ne sont pas sensibles à la casse.

Exécuter des relevés individuels

À l'exception des commandes de base de données et des méta-commandes du shell répertoriées dans README.md, le shell interprète chaque commande que vous entrez comme une instruction PartiQL distincte. Par défaut, le shell active leauto-commit mode. Ce mode est configurable.

Dans ceauto-commit mode, le shell exécute implicitement chaque instruction dans sa propre transaction et valide automatiquement la transaction si aucune erreur n'est détectée. Cela signifie que vous n'avez pas à exécuterstart transaction (oubegin)commit manuellement chaque fois que vous exécutez une instruction.

Gestion des transactions

Le shell QLDB vous permet également de contrôler manuellement les transactions. Vous pouvez exécuter plusieurs instructions au sein d'une transaction de manière interactive ou non interactive en regroupant les commandes et les instructions de manière séquentielle.

Transactions interactives

Pour exécuter une transaction interactive, procédez comme suit.

1. Pour commencer une transaction, entrez labegin commande.

   qldb> begin

   Une fois que vous avez commencé une transaction, le shell affiche l'invite de commande suivante.

   qldb *>  

2. Ensuite, chaque relevé que vous saisissez s'inscrit dans la même transaction.

   • Par exemple, vous pouvez exécuter une instruction unique comme suit.

     qldb *> SELECT * FROM Vehicle WHERE VIN = '1N4AL11D75C109151'

     Une fois que vous avez appuyéEnter, le shell affiche les résultats de l'instruction.

   • Vous pouvez également saisir plusieurs instructions ou commandes séparées par un point-virgule (;) comme suit.

     qldb *> SELECT * FROM Vehicle WHERE VIN = '1N4AL11D75C109151'; commit

3. Pour terminer la transaction, saisissez l'une des commandes suivantes.

   • Entrez lacommit commande pour valider votre transaction dans le journal du registre.

     qldb *> commit

   • Entrez laabort commande pour arrêter votre transaction et rejeter toutes les modifications que vous avez apportées.

     qldb *> abort
     transaction was aborted

Limite du délai d'expiration des transactions

Une transaction interactive respecte le délai d'expiration des transactions de QLDB. Si vous ne validez pas de transaction dans les 30 secondes suivant son démarrage, QLDB fait automatiquement expirer la transaction et rejette toutes les modifications apportées au cours de la transaction.

Ensuite, au lieu d'afficher les résultats de l'instruction, le shell affiche un message d'erreur d'expiration et revient à l'invite de commande normale. Pour réessayer, vous devez saisir à nouveau labegin commande pour démarrer une nouvelle transaction.

transaction failed after 1 attempts, last error: communication failure: Transaction 2UMpiJ5hh7WLjVgEiMLOoO has expired

Transactions non interactives

Vous pouvez exécuter une transaction complète avec plusieurs instructions en regroupant les commandes et les instructions de manière séquentielle comme suit.

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

Vous devez séparer chaque commande et chaque instruction par un séparateur point-virgule (;). Si une instruction de la transaction n'est pas valide, le shell rejette automatiquement la transaction. Le shell ne passe pas à l'exécution des instructions suivantes que vous avez saisies.

Vous pouvez également configurer plusieurs transactions.

qldb> begin; statement1; commit; begin; statement2; statement3; commit

Comme dans l'exemple précédent, si une transaction échoue, le shell ne procède à aucune transaction ou déclaration ultérieure que vous avez saisie.

Si vous ne mettez pas fin à une transaction, le shell passe en mode interactif et vous invite à entrer la commande ou l'instruction suivante.

qldb> begin; statement1; commit; begin
qldb *>  

Sortir de la coque

Pour quitter la sessionqldb shell en cours, entrez laquit commandeexit or, ou utilisez le raccourci clavierCtrl +D lorsque le shell ne figure pas dans une transaction.

qldb> exit
$ 

qldb> quit
$ 

Exemple

Pour plus d'informations sur l'écriture d'instructions PartiQL dans QLDB, consultez leRéférence Amazon QLDB.

L'exemple suivant montre une séquence courante de commandes de base.

Note

Le shell QLDB exécute chaque instruction PartiQL de cet exemple dans sa propre transaction.

Cet exemple suppose que le registre existetest-ledger déjà et qu'il est actif.

$ qldb --ledger test-ledger --region us-east-1

qldb> CREATE TABLE TestTable
qldb> INSERT INTO TestTable `{"Name": "John Doe"}`
qldb> SELECT * FROM TestTable
qldb> DROP TABLE TestTable
qldb> exit