Node.js용 Amazon QLDB 드라이버

원장의 데이터를 사용하려면 AWS가 제공하는 드라이버를 사용하여 Node.js 애플리케이션에서 Amazon QLDB에 연결할 수 있습니다. 다음 주제에서는 Node.js용 QLDB 드라이버를 시작하는 방법에 대해 설명합니다.

주제

• 드라이버 리소스
• 사전 조건
• 설치
• 설정 권장 사항
• 빠른 시작 자습서
• Cookbook 참조

드라이버 리소스

Node.js 드라이버에서 지원하는 기능에 대한 자세한 정보는 다음 리소스를 참조하십시오.

• API 참조: 3.x, 2.x, 1.x

• 드라이버 소스 코드(GitHub)

• 샘플 애플리케이션 소스 코드(GitHub)

• Amazon Ion 코드 예제

• AWS Lambda(AWS 블로그)를 사용하여 QLDB에 간단한 CRUD 작업 및 데이터 스트림 구축하기

사전 조건

Node.js용 QLDB 드라이버를 시작하기 전에 다음을 진행해야 합니다.

1. Amazon QLDB 액세스의 AWS 설정 지침을 따르십시오. 다음 내용이 포함됩니다:

   1. AWS에 가입합니다.

   2. 적절한 QLDB 권한을 가진 사용자를 생성합니다.

   3. 개발을 위한 프로그래밍 방식 액세스 권한을 부여합니다.

2. Node.js 다운로드 사이트에서 Node.js 버전 14.x 이상을 설치하십시오. (이전 버전의 드라이버는 Node.js 버전 10.x 이상을 지원합니다.)

3. Node.js의 JavaScript용 AWS SDK에 대한 개발 환경을 구성합니다.

   1. AWS 보안 인증을 설정합니다. 공유 보안 인증 파일을 생성할 것을 권장합니다.

      지침은 AWS SDK for JavaScript 개발자 안내서의 공유 보안 인증 파일에서 Node.js 보안 인증 로드를 참조하십시오.

   2. 기본 AWS 리전을 설정하십시오. 사용 방법을 배우려면 AWS 리전 설정을 참조하십시오.

      사용 가능한 리전의 전체 목록은 AWS 일반 참조에서 Amazon QLDB 엔드포인트 및 할당량을 참조하십시오.

다음으로 전체 자습서 샘플 애플리케이션을 다운로드하거나 Node.js 프로젝트에 드라이버만 설치하고 단축 코드 예제를 실행할 수 있습니다.

• 기존 프로젝트에서 QLDB 드라이버와 Node.js의 JavaScript용 AWS SDK를 설치하려면 설치로 진행하십시오.

• 프로젝트를 설정하고 원장에 대한 기본 데이터 트랜잭션을 보여주는 단축 코드 예제를 실행하려면 빠른 시작 자습서를 참조하십시오.

• 전체 자습서 샘플 애플리케이션에서 데이터 및 관리 API 작업에 대한 보다 심층적인 예제를 실행하려면 Node.js 자습서를 참조하십시오.

설치

QLDB는 다음 드라이버 버전과 해당 Node.js 종속성을 지원합니다.

드라이버 버전	Node.js 버전	상태 표시기	최근 릴리스 날짜
1.x	10.x 이상	프로덕션 릴리스	2020년 6월 5일
2.x	10.x 이상	프로덕션 릴리스	2021년 5월 6일
3.x	14.x 이상	프로덕션 릴리스	2023년 11월 10일

npm(Node.js 패키지 관리자)을 사용하여 QLDB 드라이버를 설치하려면 프로젝트 루트 디렉터리에서 다음 명령을 입력합니다.

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

드라이버는 다음 패키지에 대한 피어 종속성을 가집니다. 또한 이러한 패키지를 프로젝트에 종속성으로 설치해야 합니다.

3.x

모듈식 집계 QLDB 클라이언트(관리 API)

npm install @aws-sdk/client-qldb

모듈식 집계 QLDB 세션 클라이언트(데이터 API)

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

Amazon Ion 데이터 형식

npm install ion-js

BigInt의 순수 JavaScript 구현

npm install jsbi

2.x

AWS SDK for JavaScript

npm install aws-sdk

Amazon Ion 데이터 형식

npm install ion-js@4.0.0

BigInt의 순수 JavaScript 구현

npm install jsbi@3.1.1

1.x

AWS SDK for JavaScript

npm install aws-sdk

Amazon Ion 데이터 형식

npm install ion-js@4.0.0

BigInt의 순수 JavaScript 구현

npm install jsbi@3.1.1

드라이버를 사용하여 원장에 연결

그런 다음 드라이버를 가져와서 원장에 연결하는 데 사용할 수 있습니다. 다음 TypeScript 코드 예제에서는 지정된 원장 이름 및 AWS 리전에 대한 드라이버 인스턴스를 생성하는 방법을 보여줍니다.

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

원장에서 기본 데이터 트랜잭션을 실행하는 방법에 대한 단축 코드 예제는 Cookbook 참조를 참조하십시오.

설정 권장 사항

연결 유지를 통한 연결 재사용

QLDB Node.js 드라이버 v3

기본 Node.js HTTP/HTTPS 에이전트는 모든 새 요청에 대해 새로운 TCP 연결을 생성합니다. 새 연결을 설정하는 데 드는 비용을 피하기 위해 AWS SDK for JavaScript v3에서는 기본적으로 TCP 연결을 재사용합니다. 자세한 내용과 연결 재사용을 비활성화하는 방법을 알아보려면 AWS SDK for JavaScript 개발자 안내서의 Node.js에서 연결 유지를 이용해 연결 재사용을 참조하십시오.

Node.js용 QLDB 드라이버의 연결을 재사용하려면 기본 설정을 사용할 것을 권장합니다. 드라이버 초기화 중에 하위 수준 클라이언트 HTTP 옵션 maxSockets을 maxConcurrentTransactions에 설정한 값과 동일하게 설정합니다.

예를 들어, 다음 JavaScript 또는 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);

QLDB Node.js 드라이버 v2

기본 Node.js HTTP/HTTPS 에이전트는 모든 새 요청에 대해 새로운 TCP 연결을 생성합니다. 새 연결 설정 비용이 발생하지 않게 하려면 기존 연결을 재사용할 것을 권장합니다.

Node.js용 QLDB 드라이버의 연결을 재사용하려면 다음 옵션 중 하나를 사용십시오.

• 드라이버 초기화 중에 다음과 같은 하위 수준 클라이언트 HTTP 옵션을 설정하십시오.

  • keepAlive – true

  • maxSockets - maxConcurrentTransactions에 설정한 것과 동일한 값

  예를 들어, 다음 JavaScript 또는 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);

• 또는 AWS_NODEJS_CONNECTION_REUSE_ENABLED 환경 변수를 1로 설정할 수 있습니다. 자세한 정보는 AWS SDK for JavaScript 개발자 안내서의 Node.js에서 연결 유지를 통한 연결 재사용을 참조하십시오.

  참고

  이 환경 변수를 설정하면 AWS SDK for JavaScript를 사용하는 모든 AWS 서비스에게 영향을 줍니다.