Controlador Amazon QLDB para Node.js — Tutorial de inicio rápido - Amazon Quantum Ledger Database (Amazon QLDB)

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Controlador Amazon QLDB para Node.js — Tutorial de inicio rápido

En este tutorial, aprenderá a configurar una aplicación sencilla de mediante el controlador de Amazon QLDB para Node.js. Esta guía incluye pasos para instalar el controlador y abreviarJavaScriptyTypeScriptejemplos de código de básicosCrear, leer, actualizar y eliminar(CRUD). Para obtener ejemplos más detallados que demuestran estas operaciones en una aplicación de muestra completa, consulte laTutorial Node.js.

nota

En su caso, algunos pasos tienen ejemplos de código diferentes para cada versión principal compatible del controlador QLDB para Node.js.

Requisitos previos

Antes de comenzar, asegúrese de que hace lo siguiente:

  1. Complete elRequisitos previospara el controlador de Node.js, si aún no lo ha hecho. Esto incluye inscribirse enAWS, obtención de unAWSclave de acceso para desarrollo e instalación de Node.js.

  2. Crear un libro mayor llamadoquick-start.

    Para obtener información acerca de cómo crear un libro mayor, consulteOperaciones básicas para los libros mayores de Amazon QLDBoPaso 1: Creación de un libro de contabilidad nuevoenIntroducción a la consola.

Si utilizaTypeScript, también debe realizar los siguientes pasos de configuración.

Para instalar TypeScript

  1. Instale el paquete TypeScript. El controlador QLDB se ejecuta enTypeScript3.5.x.

    $ npm install --global typescript@3.5.1
  2. Después de instalar el paquete, ejecute el siguiente comando para asegurarse de queTypeScriptcompilador está instalado.

    $ tsc --version

Para ejecutar el código en los siguientes pasos, tenga en cuenta que primero debe transportar suTypeScriptarchivo a ejecutableJavaScriptcódigo, de la siguiente manera.

$ tsc app.ts; node app.js

Paso 1: Configuración del proyecto

En primer lugar, configure el proyecto de Node.js.

  1. Cree una carpeta para la aplicación.

    $ mkdir myproject $ cd myproject
  2. Para inicializar el proyecto, introduzca lo siguiente:npmy responde a las preguntas que se hacen durante la configuración. Puede utilizar los valores predeterminados para la mayoría de las preguntas.

    $ npm init
  3. Instale el controlador Amazon QLDB para Node.js.

    • Uso de la versión 2.x

      $ npm install amazon-qldb-driver-nodejs --save
    • Uso de la versión 1.x

      $ npm install amazon-qldb-driver-nodejs@1.0.0 --save
  4. Instale las dependencias de pares del controlador.

    $ npm install aws-sdk --save $ npm install ion-js@4.0.0 --save $ npm install jsbi@3.1.2 --save
  5. Crear un archivo nuevo llamadoapp.jsparaJavaScript, o bienapp.tsparaTypeScript.

    A continuación, agregue de forma incremental los ejemplos de código en los siguientes pasos para probar algunas operaciones CRUD básicas. O bien, puede omitir elstep-by-steptutorial y ejecute elsolicitud completa.

Paso 2: Initializar el controlador

Inicializar una instancia del controlador que se conecta al libro mayor denominadoquick-start. Añada el siguiente código a suapp.jsoapp.tsfile.

Uso de la versión 2.x

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
  • En este ejemplo de código, reemplaceus-east-1conAWSRegión en la que se ha creado el libro mayor.

  • La versión 2.x presenta el nuevo parámetro opcionalRetryConfigpara inicializarQldbDriver.

  • Para simplificar, los ejemplos de código restantes de esta guía utilizan un controlador con la configuración predeterminada, tal como se especifica en el siguiente ejemplo para la versión 1.x. También puede utilizar su propia instancia de controlador con un controlador personalizadoRetryConfigen lugar de.

  • En este ejemplo de código se inicializa un controlador que reutiliza las conexiones existentes estableciendo las opciones Keep-Alive. Para obtener más información, consulteRecomendaciones de configuraciónpara el controlador de Node.js.

Uso de la versión 1.x

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

Puede fijar laAWS_REGIONvariable de entorno para especificar la región. Para obtener más información, consulteConfiguración delAWSRegiónen laAWS SDK for JavaScriptGuía para desarrolladores.

Paso 3: Crear una tabla y un índice

En los siguientes ejemplos de código, se muestra cómo ejecutarCREATE TABLEyCREATE INDEXInstrucciones

  1. Añada la siguiente función que crea una tabla llamadaPeople.

    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. Agregue la siguiente función que crea un índice para elfirstNameen elPeopletable. Índicesson necesarios para optimizar el rendimiento de las consultas y ayudar a limitarcontrol de concurrencia optimista (OCC)excepciones de conflicto.

    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. En el navegadormainfunción, primero llamacreateTabley, a continuación, llamecreateIndex.

    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. Ejecute el código para crear la tabla y el índice.

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

Paso 4: Inserción de un documento

En el siguiente ejemplo de código, se muestra cómo ejecutar unINSERTstatement. QLDB admite laPartiQLlenguaje de consulta (compatible con SQL) y elAmazon Ionformato de datos (superconjunto de JSON).

  1. Agregue la siguiente función que inserta un documento en elPeopletable.

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

    En este ejemplo, se utiliza un signo de interrogación (?) como marcador de posición variable para pasar la información del documento a la declaración. Laexecuteadmite valores tanto de tipos Amazon Ion como de tipos nativos Node.js.

    sugerencia

    Para insertar varios documentos mediante un soloINSERT, puede pasar un parámetro de tipolistaa la declaración de la siguiente manera.

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

    No incluye el marcador de posición variable (?) en soportes de doble ángulo (<<...>>) al pasar una lista. En las instrucciones manuales PartiQL, los corchetes angulares dobles indican una colección no ordenada conocida comobolsa.

  2. En el navegadormain, elimine la funcióncreateTableycreateIndexllamadas y añadir una llamada ainsertDocument.

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

Paso 5: Consultar el documento

En el siguiente ejemplo de código, se muestra cómo ejecutar unSELECTstatement.

  1. Agregue la siguiente función que consulta un documento delPeopletable.

    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. En el navegadormain, añada la siguiente llamada afetchDocumentsdespués de la llamada 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(); }

Paso 6: Actualización del documento

En el siguiente ejemplo de código, se muestra cómo ejecutar unUPDATEstatement.

  1. Agregue la siguiente función que actualiza un documento en elPeoplemesa cambiandolastNamea"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. En el navegadormain, añada la siguiente llamada aupdateDocumentsdespués de la llamada afetchDocuments. Luego, llamefetchDocumentsde nuevo para ver los resultados actualizados.

    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. Ejecute el código para insertar, consultar y actualizar un documento.

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

Ejecución de la aplicación completa

Los siguientes ejemplos de código son las versiones completas deapp.jsyapp.ts. En lugar de realizar los pasos anteriores individualmente, también puede ejecutar este código de extremo a extremo. Esta aplicación muestra algunas operaciones CRUD básicas en el libro mayor denominadoquick-start.

nota

Antes de ejecutar este código, asegúrese de que aún no tiene una tabla activa denominadaPeopleen laquick-startlibro mayor.

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

Para ejecutar la aplicación completa, introduzca el siguiente comando.

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