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 con el controlador de Amazon QLDB para Node.js. Esta guía incluye los pasos para instalar el controlador y ejemplos breves JavaScript y de TypeScript código de las operaciones básicas de creación, lectura, actualización y eliminación (CRUD). Para obtener ejemplos más detallados que demuestren estas operaciones en una aplicación de muestra completa, consulte laTutorial de Node.js de.
Cuando corresponda, algunos pasos tienen diferentes ejemplos de código para cada versión principal compatible del controlador QLDB para Node.js.
Requisitos previos
Antes de comenzar, asegúrese de que hace lo siguiente:
Si lo está utilizando TypeScript, también debe realizar los siguientes pasos de configuración.
Para instalar TypeScript
-
Instale el TypeScript paquete. El controlador QLDB se ejecuta en TypeScript 3.8.x.
$
npm install --global typescript@3.8.0
-
Una vez instalado el paquete, ejecute el comando siguiente para asegurarse de que el TypeScript compilador está instalado.
$
tsc --version
Para ejecutar el código en los pasos siguientes, tenga en cuenta que primero debe transpilar el TypeScript archivo a JavaScript código ejecutable, 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.
-
Cree una carpeta para la aplicación.
$
mkdir myproject
$
cd myproject
-
Para inicializar el proyecto, introduzca el siguientenpm
comando y responda a las preguntas que se formulen durante la configuración. Puede utilizar los valores predeterminados para la mayoría de las preguntas.
$
npm init
-
Instale el controlador Amazon QLDB para Node.js.
-
Uso de la versión 3.x
$
npm install amazon-qldb-driver-nodejs --save
-
Uso de la versión 2.x
$
npm install amazon-qldb-driver-nodejs@2.2.0 --save
-
Uso de la versión 1.x
$
npm install amazon-qldb-driver-nodejs@1.0.0 --save
-
Instale las dependencias homólogas del controlador.
-
Uso de la versión 3.x
$
npm install @aws-sdk/client-qldb-session --save
$
npm install ion-js --save
$
npm install jsbi --save
-
Uso de la versión 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
-
Cree un archivo nuevo con el nombreapp.js
JavaScript de, oapp.ts
para TypeScript.
A continuación, añada de forma incremental los ejemplos de código en los siguientes pasos para probar algunas operaciones básicas de CRUD. O bien, puede omitir el step-by-step tutorial y, en su lugar, ejecutar la aplicación completa.
Paso 2: inicializar el controlador
Inicialice una instancia del controlador que se conecta al registro nombradoquick-start
. Añada el siguiente código a suapp.ts
archivoapp.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();
}
-
En este ejemplo de código, reemplaza us-east-1
por elRegión de AWS lugar donde creaste tu libro mayor.
-
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 puedes usar tu propia instancia de controlador con una instancia personalizadaRetryConfig
en su lugar.
- 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();
}
-
En este ejemplo de código, reemplaza us-east-1
por elRegión de AWS lugar donde creaste tu libro mayor.
-
La versión 2.x introduce el nuevo parámetro opcionalRetryConfig
para la inicializaciónQldbDriver
.
-
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 puedes usar tu propia instancia de controlador con una instancia personalizadaRetryConfig
en su lugar.
-
Este ejemplo de código inicializa un controlador que reutiliza las conexiones existentes mediante la configuración de las opciones de mantenimiento activo. Para obtener más información,Recomendaciones de configuración consulte el controlador 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();
}
Puede configurar la variable deAWS_REGION
entorno para especificar la región. Para obtener más información, consulte Configurar elRegión de AWS en la Guía paraAWS SDK for JavaScript desarrolladores.
Paso 3: crear una tabla y un índice
En los ejemplos de código siguientes se muestra cómo ejecutarCREATE TABLE
yCREATE
INDEX
las instrucciones.
-
Añada la siguiente función que crea una tabla denominadaPeople
.
- 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");
}
-
Añada la siguiente función que crea un índice para elfirstName
campo de laPeople
tabla. Los índices son necesarios para optimizar el rendimiento de las consultas y ayudar a limitar las excepciones optimistas a los conflictos en el control de concurrencia (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)");
}
-
En lamain
función, primero se llama ycreateTable
, a continuación, se llamacreateIndex
.
- 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();
}
-
Ejecute el código para crear la tabla y el índice.
- JavaScript
-
$
node app.js
- TypeScript
-
$
tsc app.ts; node app.js
Paso 4: Insertar un documento
En el ejemplo de código siguiente se muestra cómo ejecutar unaINSERT
instrucción. QLDB admite el lenguaje de consulta PartiQL (compatible con SQL) y el formato de datos Amazon Ion (superconjunto de JSON).
-
Añada la siguiente función que inserta un documento en laPeople
tabla.
- 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 sentencia. Elexecute
método admite valores tanto en los tipos Amazon Ion como en los tipos nativos de Node.js.
Para insertar varios documentos mediante una solaINSERT sentencia, puede pasar un parámetro de tipo lista a la sentencia de la siguiente manera.
// people is a list
txn.execute("INSERT INTO People ?", people);
No se incluye el marcador de posición de la variable (?
) entre corchetes de doble ángulo (<<...>>
) al pasar una lista. En las sentencias PartiQL manuales, los corchetes de doble ángulo indican una colección desordenada conocida como bolsa.
-
En lamain
función, elimine lascreateIndex
llamadascreateTable
y y añada 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 ejemplo de código siguiente se muestra cómo ejecutar unaSELECT
instrucción.
-
Añada la siguiente función que consulta un documento de laPeople
tabla.
- 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();
}
-
En lamain
función, añada la siguiente llamada afetchDocuments
despué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: actualice el documento
En el ejemplo de código siguiente se muestra cómo ejecutar unaUPDATE
instrucción.
-
Añada la siguiente función que actualiza un documento de laPeople
tabla cambiandolastName
a"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");
}
-
En lamain
función, añada la siguiente llamada aupdateDocuments
después de la llamada afetchDocuments
. A continuación,fetchDocuments
vuelva a llamar 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();
}
-
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.js
yapp.ts
. En lugar de realizar los pasos anteriores de forma individual, también puedes ejecutar este código de principio a fin. Esta aplicación muestra algunas operaciones básicas de CRUD en el libro mayor denominadoquick-start
.
Antes de ejecutar este código, asegúrese de que no tiene ya ninguna tabla activa nombradaPeople
en elquick-start
libro 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 comando siguiente:
- JavaScript
-
$
node app.js
- TypeScript
-
$
tsc app.ts; node app.js