Controlador Amazon QLDB para Node.js

Para trabajar con los datos de su libro de contabilidad, puede conectarse a Amazon QLDB desde su aplicación Node.js mediante un controlador proporcionado por AWS. En los siguientes temas se describe cómo empezar a usar el controlador QLDB para Node.js.

Temas

• Recursos de controladores
• Requisitos previos
• Instalación
• Recomendaciones de configuración
• Tutorial de inicio rápido
• Referencia de libro de recetas

Recursos de controladores

Para obtener más información sobre las funcionalidades compatibles con el controlador Node.js, consulte los siguientes recursos:

• Referencia de API: 3.x, 2.x, 1.x

• Código fuente del controlador (GitHub)

• Ejemplo de código fuente de aplicación (GitHub)

• Ejemplos de código de Amazon Ion

• Cree una operación CRUD sencilla y un flujo de datos en QLDB con AWS Lambda (Blog de AWS)

Requisitos previos

Antes de empezar a usar el controlador QLDB para Node.js, debe hacer lo siguiente:

1. Siga las instrucciones de configuración de AWS en Acceso a Amazon QLDB. Esta incluye lo siguiente:

   1. Regístrese en AWS.

   2. Cree un usuario con los permisos de QLDB adecuados.

   3. Conceda acceso programático de desarrollo.

2. Instalar la versión 14.x o posterior de Node.js que encontrará en el sitio de descargas de Node.js. (Las versiones anteriores del controlador son compatibles con la versión 10.x o posterior de Node.js).

3. Configurar su entorno de desarrollo para el SDK de AWS para JavaScript en Node.js:

   1. Configuración de sus credenciales de AWS Recomendamos crear un archivo de credenciales compartidas.

      Para ver las instrucciones, consulte Carga de credenciales en Node.js desde el archivo de credenciales compartidas en la Guía para desarrolladores de AWS SDK for JavaScript.

   2. Defina la Región de AWS predeterminada. Para aprender cómo, consulte Configuración de Región de AWS.

      Para obtener una lista de las regiones disponibles, consulte Puntos de conexión y cuotas de Amazon QLDB en la Referencia general de AWS.

A continuación, puede descargar la aplicación de ejemplo completa del tutorial, o bien instalar solo el controlador en un proyecto de Node.js y ejecutar ejemplos de códigos cortos.

• Para instalar el controlador QLDB y el SDK de AWS para JavaScript en Node.js en un proyecto existente, acceda a Instalación.

• Para configurar un proyecto y ejecutar ejemplos de códigos cortos que muestren las transacciones de datos básicas en un libro de contabilidad, consulte Tutorial de inicio rápido.

• Para ver ejemplos más detallados de las operaciones de la API de datos y administración en la aplicación de ejemplo completa del tutorial, consulte Tutorial de Node.js.

Instalación

QLDB es compatible con las siguientes versiones de controlador y sus dependencias de Node.js.

Versión de controlador	Node.js version	Status	Fecha de lanzamiento más reciente
1.x	10.x o posterior	Lanzamiento de producción	5 de junio de 2020
2.x	10.x o posterior	Lanzamiento de producción	6 de mayo de 2021
3.x	14.x o posterior	Lanzamiento de producción	10 de noviembre de 2023

Para instalar el controlador QLDB mediante npm (el administrador de paquetes de Node.js), introduzca el siguiente comando desde el directorio raíz del proyecto.

3.x

npm install amazon-qldb-driver-nodejs

2.x

npm install amazon-qldb-driver-nodejs@2.2.0

1.x

npm install amazon-qldb-driver-nodejs@1.0.0

El controlador tiene las siguientes dependencias de pares en los siguientes paquetes: También debe instalar estos paquetes como dependencias en su proyecto.

3.x

Cliente de QLDB agregado y modular (API de administración)

npm install @aws-sdk/client-qldb

Cliente de sesión de QLDB agregado y modular (API de datos)

npm install @aws-sdk/client-qldb-session

Formato de datos Amazon Ion

npm install ion-js

Implementación de JavaScript puro de BigInt

npm install jsbi

2.x

AWS SDK for JavaScript

npm install aws-sdk

Formato de datos Amazon Ion

npm install ion-js@4.0.0

Implementación de JavaScript puro de BigInt

npm install jsbi@3.1.1

1.x

AWS SDK for JavaScript

npm install aws-sdk

Formato de datos Amazon Ion

npm install ion-js@4.0.0

Implementación de JavaScript puro de BigInt

npm install jsbi@3.1.1

Uso del controlador para conectar a un libro de contabilidad

A continuación, puede importar el controlador y usarlo para conectar a un libro mayor. En el siguiente ejemplo de código de TypeScript se muestra cómo crear una instancia de controlador para un nombre de libro de contabilidad y Región de AWS específicos.

3.x

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

const maxConcurrentTransactions: number = 10;
const retryLimit: number = 4;

//Reuse connections with keepAlive
const lowLevelClientHttpOptions: NodeHttpHandlerOptions = {
    httpAgent: new Agent({
      maxSockets: maxConcurrentTransactions
    })
};

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

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

qldbDriver.getTableNames().then(function(tableNames: string[]) {
    console.log(tableNames);
});

2.x

import { Agent } from 'https';
import { QldbDriver, RetryConfig  } from 'amazon-qldb-driver-nodejs';

const maxConcurrentTransactions: number = 10;
const retryLimit: number = 4;

//Reuse connections with keepAlive
const agentForQldb: Agent = new Agent({
    keepAlive: true,
    maxSockets: maxConcurrentTransactions
});

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

//Use driver's default backoff function for this example (no second parameter provided to RetryConfig)
const retryConfig: RetryConfig = new RetryConfig(retryLimit);
const qldbDriver: QldbDriver = new QldbDriver("testLedger", serviceConfigurationOptions, maxConcurrentTransactions, retryConfig);

qldbDriver.getTableNames().then(function(tableNames: string[]) {
    console.log(tableNames);
});

1.x

import { Agent } from 'https';
import { QldbDriver } from 'amazon-qldb-driver-nodejs';

const poolLimit: number = 10;
const retryLimit: number = 4;

//Reuse connections with keepAlive
const agentForQldb: Agent = new Agent({
    keepAlive: true,
    maxSockets: poolLimit
});

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

const qldbDriver: QldbDriver = new QldbDriver("testLedger", serviceConfigurationOptions, retryLimit, poolLimit);
qldbDriver.getTableNames().then(function(tableNames: string[]) {
    console.log(tableNames);
});

Para ver ejemplos de códigos cortos sobre cómo ejecutar transacciones de datos básicos en un libro de contabilidad, consulte la Referencia de libro de recetas.

Recomendaciones de configuración

Reutilización de conexiones con keep-alive

Controlador QLDB Node.js v3

El agente HTTP o HTTPS predeterminado de Node.js crea una nueva conexión TCP para cada nueva solicitud. Para evitar el coste de establecer una nueva conexión, la versión 3 de AWS SDK for JavaScript reutiliza las conexiones TCP de forma predeterminada. Para obtener más información y aprender a deshabilitar la reutilización de conexiones, consulte Reutilizar conexiones con keep-alive en Node.js en la Guía para desarrolladores de AWS SDK for JavaScript.

Recomendamos usar la configuración predeterminada para reutilizar conexiones del controlador QLDB para Node.js. Durante la inicialización del controlador, defina la opción HTTP maxSockets del cliente de bajo nivel en el mismo valor que estableció para maxConcurrentTransactions.

Para ver un ejemplo, consulte el siguiente código de JavaScript o TypeScript.

JavaScript

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

//Replace this value as appropriate for your application
const maxConcurrentTransactions = 50;

const agentForQldb = new https.Agent({
    //Set this to the same value as `maxConcurrentTransactions`(previously called `poolLimit`)
    //Do not rely on the default value of `Infinity`
    "maxSockets": maxConcurrentTransactions
});

const lowLevelClientHttpOptions = {
    httpAgent: agentForQldb
}

let driver = new qldb.QldbDriver("testLedger", undefined, lowLevelClientHttpOptions, maxConcurrentTransactions);

TypeScript

import { Agent } from 'https';
import { NodeHttpHandlerOptions } from "@aws-sdk/node-http-handler";
import { QldbDriver } from 'amazon-qldb-driver-nodejs';

//Replace this value as appropriate for your application
const maxConcurrentTransactions: number = 50;

const agentForQldb: Agent = new Agent({
    //Set this to the same value as `maxConcurrentTransactions`(previously called `poolLimit`)
    //Do not rely on the default value of `Infinity`
    maxSockets: maxConcurrentTransactions
});

const lowLevelClientHttpOptions: NodeHttpHandlerOptions = {
    httpAgent: agentForQldb
};

let driver = new QldbDriver("testLedger", undefined, lowLevelClientHttpOptions, maxConcurrentTransactions);

Controlador QLDB Node.js v2

El agente HTTP o HTTPS predeterminado de Node.js crea una nueva conexión TCP para cada nueva solicitud. Para evitar el costo que supone establecer una nueva conexión, recomendamos reutilizar una conexión existente.

Para reutilizar las conexiones del controlador QLDB para Node.js, use una de las siguientes opciones:

• Durante la inicialización del controlador, configure las siguientes opciones HTTP del cliente de bajo nivel:

  • keepAlive – true

  • maxSockets: el mismo valor que estableció para maxConcurrentTransactions

  Para ver un ejemplo, consulte el siguiente código de JavaScript o TypeScript.

  JavaScript

  const qldb = require('amazon-qldb-driver-nodejs');
  const https = require('https');
  
  //Replace this value as appropriate for your application
  const maxConcurrentTransactions = 50;
  
  const agentForQldb = new https.Agent({
      "keepAlive": true,
      //Set this to the same value as `maxConcurrentTransactions`(previously called `poolLimit`)
      //Do not rely on the default value of `Infinity`
      "maxSockets": maxConcurrentTransactions
  });
  
  const serviceConfiguration = { "httpOptions": {
      "agent": agentForQldb
  }};
  
  let driver = new qldb.QldbDriver("testLedger", serviceConfiguration, maxConcurrentTransactions);

  TypeScript

  import { Agent } from 'https';
  import { ClientConfiguration } from 'aws-sdk/clients/acm';
  import { QldbDriver } from 'amazon-qldb-driver-nodejs';
  
  //Replace this value as appropriate for your application
  const maxConcurrentTransactions: number = 50;
  
  const agentForQldb: Agent = new Agent({
      keepAlive: true,
      //Set this to the same value as `maxConcurrentTransactions`(previously called `poolLimit`)
      //Do not rely on the default value of `Infinity`
      maxSockets: maxConcurrentTransactions
  });
  
  const serviceConfiguration: ClientConfiguration = { httpOptions: {
      agent: agentForQldb
  }};
  
  let driver = new QldbDriver("testLedger", serviceConfiguration, maxConcurrentTransactions);

• Otra opción consiste en establecer la variable del entorno AWS_NODEJS_CONNECTION_REUSE_ENABLED en 1. Para obtener más información, consulte Reutilización de conexiones con KeepAlive en Node.js en la Guía para desarrolladores de AWS SDK for JavaScript.

  nota

  Si define esta variable de entorno, afectará a todos los Servicios de AWS que usen AWS SDK for JavaScript.