QLDBPilote Amazon pour Node.js — Tutoriel de démarrage rapide - Base de données Amazon Quantum Ledger (AmazonQLDB)
PrérequisÉtape 1 : Configurer votre projet Étape 2 : Initialisation du piloteÉtape 3 : Création d'une table et d'un indexÉtape 4 : Insérer un documentÉtape 5 : Interrogez le documentÉtape 6 : Mettre à jour le documentExécution de l'application complète

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

QLDBPilote Amazon pour Node.js — Tutoriel de démarrage rapide

Important

Avis de fin de support : les clients existants pourront utiliser Amazon QLDB jusqu'à la fin du support le 31 juillet 2025. Pour plus de détails, consultez Migrer un Amazon QLDB Ledger vers Amazon Aurora SQL Postgre.

Dans ce didacticiel, vous apprendrez à configurer une application simple à l'aide du QLDB pilote Amazon pour Node.js. Ce guide décrit les étapes d'installation du pilote, ainsi que des exemples abrégés JavaScript et TypeScript codés d'opérations de base de création, de lecture, de mise à jour et de suppression (CRUD). Pour des exemples plus détaillés illustrant ces opérations dans un exemple complet d'application, consultez leTutoriel Node.js.

Note

Le cas échéant, certaines étapes comportent des exemples de code différents pour chaque version majeure prise en charge du QLDB pilote pour Node.js.

Prérequis

Avant de commencer, assurez-vous d'effectuer les opérations suivantes :

  1. Complétez le fichier Prérequis pour le pilote Node.js, si ce n'est déjà fait. Cela inclut l'inscription AWS, l'octroi d'un accès programmatique pour le développement et l'installation de Node.js.

  2. Créez un registre nomméquick-start.

    Pour savoir comment créer un registre, voir Opérations de base pour Amazon QLDB Ledgers ou Étape 1 : Création d'un nouveau registre dans Commencer à utiliser la console.

Si vous utilisez TypeScript, vous devez également suivre les étapes de configuration suivantes.

Pour installer TypeScript

  1. Installez le TypeScript package. Le QLDB pilote fonctionne sous TypeScript 3.8.x.

    $ npm install --global typescript@3.8.0

  2. Une fois le package installé, exécutez la commande suivante pour vous assurer que le TypeScript compilateur est installé.

    $ tsc --version

Pour exécuter le code dans les étapes suivantes, notez que vous devez d'abord transpiler votre TypeScript fichier en JavaScript code exécutable, comme suit.

$ tsc app.ts; node app.js

Étape 1 : Configurer votre projet

Configurez d'abord votre projet Node.js.

  1. Créez un dossier pour votre application.

    $ mkdir myproject
$ cd myproject

  2. Pour initialiser votre projet, entrez la npm commande suivante et répondez aux questions posées lors de la configuration. Vous pouvez utiliser les valeurs par défaut pour la plupart des questions.

    $ npm init

  3. Installez le QLDB pilote Amazon pour Node.js.

    • Utilisation de la version 3.x

      $ npm install amazon-qldb-driver-nodejs --save

    • Utilisation de la version 2.x

      $ npm install amazon-qldb-driver-nodejs@2.2.0 --save

    • Utilisation de la version 1.x

      $ npm install amazon-qldb-driver-nodejs@1.0.0 --save

  4. Installez les dépendances homologues du pilote.

    • Utilisation de la version 3.x

      $ npm install @aws-sdk/client-qldb-session --save
$ npm install ion-js --save
$ npm install jsbi --save

    • Utilisation de la version 2.x ou 1.x

      $ npm install aws-sdk --save
$ npm install ion-js@4.0.0 --save
$ npm install jsbi@3.1.1 --save

  5. Créez un nouveau fichier nommé app.js pour JavaScript ou app.ts pour TypeScript.

    Ajoutez ensuite progressivement les exemples de code dans les étapes suivantes pour essayer certaines CRUD opérations de base. Vous pouvez également ignorer le step-by-step didacticiel et exécuter l'application complète à la place.

Étape 2 : Initialisation du pilote

Initialisez une instance du pilote qui se connecte au registre nommé. quick-start Ajoutez le code suivant à votre app.ts fichier app.js or.

JavaScript
var qldb = require('amazon-qldb-driver-nodejs');
var https = require('https');

function main() {
    const maxConcurrentTransactions = 10;
    const retryLimit = 4;

    const agentForQldb = new https.Agent({
        maxSockets: maxConcurrentTransactions
    });

    const lowLevelClientHttpOptions = {
       httpAgent: agentForQldb
    }

    const serviceConfigurationOptions = {
        region: "us-east-1"
    };

    // Use driver's default backoff function for this example (no second parameter provided to RetryConfig)
    var retryConfig = new qldb.RetryConfig(retryLimit);
    var driver = new qldb.QldbDriver("quick-start", serviceConfigurationOptions, lowlevelClientHttpOptions, maxConcurrentTransactions, retryConfig);
}

main();
TypeScript
import { Agent } from "https";
import { NodeHttpHandlerOptions } from "@aws-sdk/node-http-handler";
import { QLDBSessionClientConfig } from "@aws-sdk/client-qldb-session";
import { QldbDriver, RetryConfig } from "amazon-qldb-driver-nodejs";

function main(): void {
    const maxConcurrentTransactions: number = 10;
    const agentForQldb: Agent = new Agent({
        maxSockets: maxConcurrentTransactions
    });

    const lowLevelClientHttpOptions: NodeHttpHandlerOptions = {
      httpAgent: agentForQldb
    };

    const serviceConfigurationOptions: QLDBSessionClientConfig = {
        region: "us-east-1"
    };

    const retryLimit: number = 4;
    // Use driver's default backoff function for this example (no second parameter provided to RetryConfig)
    const retryConfig: RetryConfig = new RetryConfig(retryLimit);
    const driver: QldbDriver = new QldbDriver("quick-start", serviceConfigurationOptions, lowLevelClientHttpOptions, maxConcurrentTransactions, retryConfig);
}

if (require.main === module) {
    main();
}
Note

  • Dans cet exemple de code, remplacez us-east-1 avec l' Région AWS endroit où vous avez créé votre registre.

  • Pour des raisons de simplicité, les autres exemples de code de ce guide utilisent un pilote avec des paramètres par défaut, comme indiqué dans l'exemple suivant pour la version 1.x. Vous pouvez également utiliser votre propre instance de pilote avec une instance personnalisée à la RetryConfig place.

JavaScript
var qldb = require('amazon-qldb-driver-nodejs');
var https = require('https');

function main() {
    var maxConcurrentTransactions = 10;
    var retryLimit = 4;

    var agentForQldb = new https.Agent({
        keepAlive: true,
        maxSockets: maxConcurrentTransactions
    });

    var serviceConfigurationOptions = {
        region: "us-east-1",
        httpOptions: {
            agent: agentForQldb
        }
    };

    // Use driver's default backoff function for this example (no second parameter provided to RetryConfig)
    var retryConfig = new qldb.RetryConfig(retryLimit);
    var driver = new qldb.QldbDriver("quick-start", serviceConfigurationOptions, maxConcurrentTransactions, retryConfig);
}

main();
TypeScript
import { QldbDriver, RetryConfig } from "amazon-qldb-driver-nodejs";
import { ClientConfiguration } from "aws-sdk/clients/acm";
import { Agent } from "https";

function main(): void {
    const maxConcurrentTransactions: number = 10;
    const agentForQldb: Agent = new Agent({
        keepAlive: true,
        maxSockets: maxConcurrentTransactions
    });
    const serviceConfigurationOptions: ClientConfiguration = {
        region: "us-east-1",
        httpOptions: {
            agent: agentForQldb
        }
    };
    const retryLimit: number = 4;
    // Use driver's default backoff function for this example (no second parameter provided to RetryConfig)
    const retryConfig: RetryConfig = new RetryConfig(retryLimit);
    const driver: QldbDriver = new QldbDriver("quick-start", serviceConfigurationOptions, maxConcurrentTransactions, retryConfig);
}

if (require.main === module) {
    main();
}
Note

  • Dans cet exemple de code, remplacez us-east-1 avec l' Région AWS endroit où vous avez créé votre registre.

  • La version 2.x introduit le nouveau paramètre optionnel RetryConfig pour l'initialisationQldbDriver.

  • Pour des raisons de simplicité, les autres exemples de code de ce guide utilisent un pilote avec des paramètres par défaut, comme indiqué dans l'exemple suivant pour la version 1.x. Vous pouvez également utiliser votre propre instance de pilote avec une instance personnalisée à la RetryConfig place.

  • Cet exemple de code initialise un pilote qui réutilise les connexions existantes en définissant les options keep-alive. Pour en savoir plus, consultez Recommandations de configuration le pilote Node.js.

JavaScript
const qldb = require('amazon-qldb-driver-nodejs');

function main() {
    // Use default settings
    const driver = new qldb.QldbDriver("quick-start");
}

main();
TypeScript
import { QldbDriver } from "amazon-qldb-driver-nodejs";

function main(): void {
    // Use default settings
    const driver: QldbDriver = new QldbDriver("quick-start");
}

if (require.main === module) {
    main();
}
Note

Vous pouvez définir la variable d'AWS_REGIONenvironnement pour spécifier la région. Pour plus d'informations, consultez la section Configuration du Région AWS dans le guide du AWS SDK for JavaScript développeur.

Étape 3 : Création d'une table et d'un index

Les exemples de code suivants montrent comment exécuter CREATE TABLE des CREATE INDEX instructions.

  1. Ajoutez la fonction suivante qui crée une table nomméePeople.

    JavaScript
    async function createTable(txn) {
    await txn.execute("CREATE TABLE People");
}
    TypeScript
    async function createTable(txn: TransactionExecutor): Promise<void> {
    await txn.execute("CREATE TABLE People");
}

  2. Ajoutez la fonction suivante qui crée un index pour le firstName champ de la People table. Les index sont nécessaires pour optimiser les performances des requêtes et aider à limiter les exceptions de conflit optimistes en matière de contrôle de simultanéité (OCC).

    JavaScript
    async function createIndex(txn) {
    await txn.execute("CREATE INDEX ON People (firstName)");
}
    TypeScript
    async function createIndex(txn: TransactionExecutor): Promise<void> {
    await txn.execute("CREATE INDEX ON People (firstName)");
}

  3. Dans la main fonction, vous appelez d'abordcreateTable, puis vous appelezcreateIndex.

    JavaScript
    const qldb = require('amazon-qldb-driver-nodejs');

async function main() {
    // Use default settings
    const driver = new qldb.QldbDriver("quick-start");

    await driver.executeLambda(async (txn) => {
        console.log("Create table People");
        await createTable(txn);
        console.log("Create index on firstName");
        await createIndex(txn);
    });

    driver.close();
}

main();
    TypeScript
    import { QldbDriver, TransactionExecutor } from "amazon-qldb-driver-nodejs";

async function main(): Promise<void> {
    // Use default settings
    const driver: QldbDriver = new QldbDriver("quick-start");

    await driver.executeLambda(async (txn: TransactionExecutor) => {
        console.log("Create table People");
        await createTable(txn);
        console.log("Create index on firstName");
        await createIndex(txn);
    });

    driver.close();
}

if (require.main === module) {
    main();
}

  4. Exécutez le code pour créer la table et l'index.

    JavaScript
    $ node app.js
    TypeScript
    $ tsc app.ts; node app.js

Étape 4 : Insérer un document

L'exemple de code suivant montre comment exécuter une INSERT instruction. QLDBprend en charge le langage de requête partiQL (SQLcompatible) et le format de données Amazon Ion (surensemble de). JSON

  1. Ajoutez la fonction suivante qui insère un document dans le People tableau.

    JavaScript
    async function insertDocument(txn) {
    const person = {
        firstName: "John",
        lastName: "Doe",
        age: 42
    };
    await txn.execute("INSERT INTO People ?", person);
}
    TypeScript
    async function insertDocument(txn: TransactionExecutor): Promise<void> {
    const person: Record<string, any> = {
        firstName: "John",
        lastName: "Doe",
        age: 42
    };
    await txn.execute("INSERT INTO People ?", person);
}

    Cet exemple utilise un point d'interrogation (?) comme espace réservé aux variables pour transmettre les informations du document à l'instruction. La execute méthode prend en charge les valeurs des types Amazon Ion et des types natifs Node.js.

    Astuce

    Pour insérer plusieurs documents en utilisant une seule INSERT instruction, vous pouvez transmettre un paramètre de type list à l'instruction comme suit.

    // people is a list
txn.execute("INSERT INTO People ?", people);

    Vous ne placez pas la variable placeholder (?) entre crochets (<<...>>) lorsque vous transmettez une liste. Dans les instructions partiQL manuelles, les crochets à double angle indiquent une collection non ordonnée appelée sac.

  2. Dans la main fonction, supprimez les createIndex appels createTable et et ajoutez un appel àinsertDocument.

    JavaScript
    const qldb = require('amazon-qldb-driver-nodejs');

async function main() {
    // Use default settings
    const driver = new qldb.QldbDriver("quick-start");

    await driver.executeLambda(async (txn) => {
        console.log("Insert document");
        await insertDocument(txn);
    });

    driver.close();
}

main();
    TypeScript
    import { QldbDriver, TransactionExecutor } from "amazon-qldb-driver-nodejs";

async function main(): Promise<void> {
    // Use default settings
    const driver: QldbDriver = new QldbDriver("quick-start");

    await driver.executeLambda(async (txn: TransactionExecutor) => {
        console.log("Insert document");
        await insertDocument(txn);
    });

    driver.close();
}

if (require.main === module) {
    main();
}

Étape 5 : Interrogez le document

L'exemple de code suivant montre comment exécuter une SELECT instruction.

  1. Ajoutez la fonction suivante qui interroge un document à partir de la People table.

    JavaScript
    async function fetchDocuments(txn) {
    return await txn.execute("SELECT firstName, age, lastName FROM People WHERE firstName = ?", "John");
}
    TypeScript
    async function fetchDocuments(txn: TransactionExecutor): Promise<dom.Value[]> {
    return (await txn.execute("SELECT firstName, age, lastName FROM People WHERE firstName = ?", "John")).getResultList();
}

  2. Dans la main fonction, ajoutez l'appel suivant à fetchDocuments après l'appel àinsertDocument.

    JavaScript
    const qldb = require('amazon-qldb-driver-nodejs');

async function main() {
    // Use default settings
    const driver = new qldb.QldbDriver("quick-start");

    var resultList = await driver.executeLambda(async (txn) => {
        console.log("Insert document");
        await insertDocument(txn);
        console.log("Fetch document");
        var result = await fetchDocuments(txn);
        return result.getResultList();
    });

    // Pretty print the result list
    console.log("The result List is ", JSON.stringify(resultList, null, 2));
    driver.close();
}

main();
    TypeScript
    import { QldbDriver, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { dom } from "ion-js";

async function main(): Promise<void> {
    // Use default settings
    const driver: QldbDriver = new QldbDriver("quick-start");

    const resultList: dom.Value[] = await driver.executeLambda(async (txn: TransactionExecutor) => {
        console.log("Insert document");
        await insertDocument(txn);
        console.log("Fetch document");
        return await fetchDocuments(txn);
    });

    // Pretty print the result list
    console.log("The result List is ", JSON.stringify(resultList, null, 2));
    driver.close();
}

if (require.main === module) {
    main();
}

Étape 6 : Mettre à jour le document

L'exemple de code suivant montre comment exécuter une UPDATE instruction.

  1. Ajoutez la fonction suivante qui met à jour un document dans le People tableau en le remplaçant lastName par"Stiles".

    JavaScript
    async function updateDocuments(txn) {
    await txn.execute("UPDATE People SET lastName = ? WHERE firstName = ?", "Stiles", "John");
}
    TypeScript
    async function updateDocuments(txn: TransactionExecutor): Promise<void> {
    await txn.execute("UPDATE People SET lastName = ? WHERE firstName = ?", "Stiles", "John");
}

  2. Dans la main fonction, ajoutez l'appel suivant à updateDocuments après l'appel àfetchDocuments. Ensuite, appelez à fetchDocuments nouveau pour voir les résultats mis à jour.

    JavaScript
    const qldb = require('amazon-qldb-driver-nodejs');

async function main() {
    // Use default settings
    const driver = new qldb.QldbDriver("quick-start");

    var resultList = await driver.executeLambda(async (txn) => {
        console.log("Insert document");
        await insertDocument(txn);
        console.log("Fetch document");
        await fetchDocuments(txn);
        console.log("Update document");
        await updateDocuments(txn);
        console.log("Fetch document after update");
        var result = await fetchDocuments(txn);
        return result.getResultList();
    });

    // Pretty print the result list
    console.log("The result List is ", JSON.stringify(resultList, null, 2));
    driver.close();
}

main();
    TypeScript
    import { QldbDriver, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { dom } from "ion-js";

async function main(): Promise<void> {
    // Use default settings
    const driver: QldbDriver = new QldbDriver("quick-start");

    const resultList: dom.Value[] = await driver.executeLambda(async (txn: TransactionExecutor) => {
        console.log("Insert document");
        await insertDocument(txn);
        console.log("Fetch document");
        await fetchDocuments(txn);
        console.log("Update document");
        await updateDocuments(txn);
        console.log("Fetch document after update");
        return await fetchDocuments(txn);
    });

    // Pretty print the result list
    console.log("The result List is ", JSON.stringify(resultList, null, 2));
    driver.close();
}

if (require.main === module) {
    main();
}

  3. Exécutez le code pour insérer, interroger et mettre à jour un document.

    JavaScript
    $ node app.js
    TypeScript
    $ tsc app.ts; node app.js

Exécution de l'application complète

Les exemples de code suivants sont les versions complètes de app.js etapp.ts. Au lieu d'effectuer les étapes précédentes individuellement, vous pouvez également exécuter ce code du début à la fin. Cette application montre certaines CRUD opérations de base sur le registre nomméquick-start.

Note

Avant d'exécuter ce code, assurez-vous qu'aucune table active n'est déjà nommée People dans le quick-start registre.

JavaScript
const qldb = require('amazon-qldb-driver-nodejs');

async function createTable(txn) {
    await txn.execute("CREATE TABLE People");
}

async function createIndex(txn) {
    await txn.execute("CREATE INDEX ON People (firstName)");
}

async function insertDocument(txn) {
    const person = {
        firstName: "John",
        lastName: "Doe",
        age: 42
    };
    await txn.execute("INSERT INTO People ?", person);
}

async function fetchDocuments(txn) {
    return await txn.execute("SELECT firstName, age, lastName FROM People WHERE firstName = ?", "John");
}

async function updateDocuments(txn) {
    await txn.execute("UPDATE People SET lastName = ? WHERE firstName = ?", "Stiles", "John");
}

async function main() {
    // Use default settings
    const driver = new qldb.QldbDriver("quick-start");

    var resultList = await driver.executeLambda(async (txn) => {
        console.log("Create table People");
        await createTable(txn);
        console.log("Create index on firstName");
        await createIndex(txn);
        console.log("Insert document");
        await insertDocument(txn);
        console.log("Fetch document");
        await fetchDocuments(txn);
        console.log("Update document");
        await updateDocuments(txn);
        console.log("Fetch document after update");
        var result = await fetchDocuments(txn);
        return result.getResultList();
    });

    // Pretty print the result list
    console.log("The result List is ", JSON.stringify(resultList, null, 2));
    driver.close();
}

main();
TypeScript
import { QldbDriver, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { dom } from "ion-js";

async function createTable(txn: TransactionExecutor): Promise<void> {
    await txn.execute("CREATE TABLE People");
}

async function createIndex(txn: TransactionExecutor): Promise<void> {
    await txn.execute("CREATE INDEX ON People (firstName)");
}

async function insertDocument(txn: TransactionExecutor): Promise<void> {
    const person: Record<string, any> = {
        firstName: "John",
        lastName: "Doe",
        age: 42
    };
    await txn.execute("INSERT INTO People ?", person);
}

async function fetchDocuments(txn: TransactionExecutor): Promise<dom.Value[]> {
    return (await txn.execute("SELECT firstName, age, lastName FROM People WHERE firstName = ?", "John")).getResultList();
}

async function updateDocuments(txn: TransactionExecutor): Promise<void> {
    await txn.execute("UPDATE People SET lastName = ? WHERE firstName = ?", "Stiles", "John");
};

async function main(): Promise<void> {
    // Use default settings
    const driver: QldbDriver = new QldbDriver("quick-start");

    const resultList: dom.Value[] = await driver.executeLambda(async (txn: TransactionExecutor) => {
        console.log("Create table People");
        await createTable(txn);
        console.log("Create index on firstName");
        await createIndex(txn);
        console.log("Insert document");
        await insertDocument(txn);
        console.log("Fetch document");
        await fetchDocuments(txn);
        console.log("Update document");
        await updateDocuments(txn);
        console.log("Fetch document after update");
        return await fetchDocuments(txn);
    });

    // Pretty print the result list
    console.log("The result List is ", JSON.stringify(resultList, null, 2));
    driver.close();
}

if (require.main === module) {
    main();
}

Pour exécuter l'application complète, entrez la commande suivante.

JavaScript
$ node app.js
TypeScript
$ tsc app.ts; node app.js