Driver Amazon QLDB per Node.js — Tutorial di avvio rapido - Database Amazon Quantum Ledger (Amazon QLDB)
PrerequisitiFase 1: Configurazione del progetto Fase 2: Inizializzare il driverFase 3: Creare una tabella e un indiceFase 4: Inserimento di un documentoFase 5: Interroga il documentoFase 6: Aggiornare il documentoEsecuzione dell'applicazione completa

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Driver Amazon QLDB per Node.js — Tutorial di avvio rapido

Importante

Avviso di fine del supporto: i clienti esistenti potranno utilizzare Amazon QLDB fino alla fine del supporto, il 31/07/2025. Per ulteriori dettagli, consulta Migrare un registro Amazon QLDB su Amazon Aurora PostgreSQL.

In questo tutorial, imparerai come configurare una semplice applicazione utilizzando il driver Amazon QLDB per Node.js. Questa guida include i passaggi per l'installazione del driver ed esempi brevi JavaScript e in TypeScript codice delle operazioni di base di creazione, lettura, aggiornamento ed eliminazione (CRUD). Per esempi più approfonditi che illustrano queste operazioni in un'applicazione di esempio completa, consulta la. Tutorial su Node.js

Nota

Ove applicabile, alcuni passaggi contengono esempi di codice diversi per ogni versione principale supportata del driver QLDB per Node.js.

Prerequisiti

Prima di iniziare, assicurati di fare quanto segue:

  1. Completa il driver Prerequisiti per il Node.js, se non l'hai già fatto. Ciò include la registrazione AWS, la concessione dell'accesso programmatico per lo sviluppo e l'installazione di Node.js.

  2. Crea un libro mastro denominato. quick-start

    Per informazioni su come creare un registro, consulta Operazioni di base per i registri Amazon QLDB o Fase 1: Creare un nuovo libro contabile in Guida introduttiva alla console.

Se lo utilizzi TypeScript, devi anche eseguire i seguenti passaggi di configurazione.

Per installare TypeScript

  1. Installa il TypeScript pacchetto. Il driver QLDB funziona sulla versione 3.8.x. TypeScript 

    $ npm install --global typescript@3.8.0

  2. Dopo aver installato il pacchetto, esegui il comando seguente per assicurarti che il TypeScript compilatore sia installato.

    $ tsc --version

Per eseguire il codice nei passaggi seguenti, tenete presente che dovete prima trasporre il TypeScript file in JavaScript codice eseguibile, come segue.

$ tsc app.ts; node app.js

Fase 1: Configurazione del progetto

Innanzitutto, configurate il progetto Node.js.

  1. Crea una cartella per la tua applicazione.

    $ mkdir myproject
$ cd myproject

  2. Per inizializzare il progetto, immettete il seguente npm comando e rispondete alle domande che vi vengono poste durante la configurazione. Puoi usare i valori predefiniti per la maggior parte delle domande.

    $ npm init

  3. Installa il driver Amazon QLDB per Node.js.

    • Utilizzando la versione 3.x

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

    • Utilizzando la versione 2.x

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

    • Utilizzando la versione 1.x

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

  4. Installa le dipendenze peer del driver.

    • Utilizzando la versione 3.x

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

    • Utilizzando la versione 2.x o 1.x

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

  5. Crea un nuovo file denominato app.js for JavaScript o app.ts for. TypeScript

    Quindi, aggiungi in modo incrementale gli esempi di codice nei passaggi seguenti per provare alcune operazioni CRUD di base. In alternativa, puoi saltare il step-by-step tutorial ed eseguire invece l'applicazione completa.

Fase 2: Inizializzare il driver

Inizializza un'istanza del driver che si connette al registro denominato. quick-start Aggiungi il codice seguente al tuo file app.js orapp.ts.

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

  • In questo esempio di codice, sostituiscilo us-east-1 con il Regione AWS punto in cui hai creato il libro mastro.

  • Per semplicità, i restanti esempi di codice di questa guida utilizzano un driver con impostazioni predefinite, come specificato nell'esempio seguente per la versione 1.x. In RetryConfig alternativa, è possibile utilizzare un'istanza di driver personalizzata anche con un'istanza personalizzata.

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

  • In questo esempio di codice, sostituiscilo us-east-1 con il Regione AWS punto in cui hai creato il libro mastro.

  • La versione 2.x introduce il nuovo parametro RetryConfig opzionale per l'inizializzazione. QldbDriver

  • Per semplicità, gli altri esempi di codice in questa guida utilizzano un driver con impostazioni predefinite, come specificato nell'esempio seguente per la versione 1.x. In RetryConfig alternativa, è possibile utilizzare un'istanza di driver personalizzata anche con un'istanza personalizzata.

  • Questo esempio di codice inizializza un driver che riutilizza le connessioni esistenti impostando le opzioni keep-alive. Per ulteriori informazioni, Consigli di configurazione consultate il driver 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();
}
Nota

È possibile impostare la variabile di AWS_REGION ambiente per specificare la regione. Per ulteriori informazioni, consulta Impostazione di Regione AWS nella Guida per gli AWS SDK for JavaScript sviluppatori.

Fase 3: Creare una tabella e un indice

I seguenti esempi di codice mostrano come eseguire le CREATE INDEX istruzioni CREATE TABLE e le istruzioni.

  1. Aggiungete la seguente funzione che crea una tabella denominataPeople.

    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. Aggiungete la seguente funzione che crea un indice per il firstName campo della People tabella. Gli indici sono necessari per ottimizzare le prestazioni delle query e aiutano a limitare le eccezioni ai conflitti OCC (Optimistic Concurrency Control).

    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. Nella main funzione, si chiama prima e poi si chiama. createTable createIndex

    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. Esegui il codice per creare la tabella e l'indice.

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

Fase 4: Inserimento di un documento

Il seguente esempio di codice mostra come eseguire un'INSERTistruzione. QLDB supporta il linguaggio di interrogazione PartiQL (compatibile con SQL) e il formato dati Amazon Ion (superset di JSON).

  1. Aggiungi la seguente funzione che inserisce un documento nella tabella. People

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

    Questo esempio utilizza un punto interrogativo (?) come segnaposto variabile per passare le informazioni del documento all'istruzione. Il execute metodo supporta valori sia nei tipi Amazon Ion che nei tipi nativi Node.js.

    Suggerimento

    Per inserire più documenti utilizzando una singola INSERT istruzione, puoi passare un parametro di tipo elenco all'istruzione come segue.

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

    Non racchiudete la variabile placeholder (?) tra parentesi angolari doppie (<<...>>) quando passate un elenco. Nelle istruzioni PartiQL manuali, le parentesi doppie angolari indicano una raccolta non ordinata nota come borsa.

  2. Nella main funzione, rimuovi le createIndex chiamate createTable and e aggiungi una chiamata a. 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();
}

Fase 5: Interroga il documento

Il seguente esempio di codice mostra come eseguire un'SELECTistruzione.

  1. Aggiungete la seguente funzione che interroga un documento dalla People tabella.

    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. Nella main funzione, aggiungi la seguente chiamata a fetchDocuments dopo la chiamata ainsertDocument.

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

Fase 6: Aggiornare il documento

Il seguente esempio di codice mostra come eseguire un'UPDATEistruzione.

  1. Aggiungere la seguente funzione che aggiorna un documento nella People tabella modificandolo lastName in"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. Nella main funzione, aggiungi la seguente chiamata a updateDocuments dopo la chiamata afetchDocuments. Quindi, chiama fetchDocuments di nuovo per vedere i risultati aggiornati.

    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. Esegui il codice per inserire, interrogare e aggiornare un documento.

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

Esecuzione dell'applicazione completa

I seguenti esempi di codice sono le versioni complete di app.js andapp.ts. Invece di eseguire i passaggi precedenti singolarmente, puoi anche eseguire questo codice dall'inizio alla fine. Questa applicazione dimostra alcune operazioni CRUD di base sul registro denominato. quick-start

Nota

Prima di eseguire questo codice, assicuratevi di non avere già una tabella attiva denominata People nel registro. quick-start

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

Per eseguire l'applicazione completa, immettete il seguente comando.

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