버전 2.x에서 3.x 버전으로 마이그레이션 AWS SDK for JavaScript

AWS SDK for JavaScript 버전 3은 버전 2를 대대적으로 재작성한 것입니다. 이 섹션에서는 두 버전 간의 차이점을 설명하고 SDK의 버전 2에서 버전 3으로 마이그레이션하는 방법을 설명합니다. JavaScript

codemod를 사용하여 코드를 JavaScript v3용 SDK로 마이그레이션하십시오.

AWS SDK for JavaScript 버전 3 (v3) 에는 자격 증명, Amazon S3 멀티파트 업로드, DynamoDB 문서 클라이언트, 웨이터 등을 포함하는 클라이언트 구성 및 유틸리티를 위한 현대화된 인터페이스가 함께 제공됩니다. 리포지토리의 마이그레이션 가이드에서 각 변경 사항에 대한 v2 및 v3의 해당 변경 내용을 확인할 수 있습니다. AWS SDK for JavaScript GitHub

AWS SDK for JavaScript v3를 최대한 활용하려면 아래에 설명된 codemod 스크립트를 사용하는 것이 좋습니다.

codemod를 사용하여 기존 v2 코드를 마이그레이션하십시오.

의 codemod 스크립트 컬렉션은 기존 AWS SDK for JavaScript (v2) 애플리케이션을 v3 API를 사용하도록 마이그레이션하는 aws-sdk-js-codemod데 도움이 됩니다. 다음과 같이 변환을 실행할 수 있습니다.

$ npx aws-sdk-js-codemod -t v2-to-v3 PATH...

예를 들어 v2에서 Amazon DynamoDB 클라이언트를 생성하고 listTables 작업을 직접적으로 호출하는 다음 코드가 있다고 가정해 보겠습니다.

// example.ts
import AWS from "aws-sdk";

const region = "us-west-2";
const client = new AWS.DynamoDB({ region });
await client.listTables({}).promise()
  .then(console.log)
  .catch(console.error);

다음과 같이 example.ts에서 v2-to-v3 변환을 실행할 수 있습니다.

$ npx aws-sdk-js-codemod -t v2-to-v3 example.ts

이 변환은 DynamoDB import를 v3로 변환하고 v3 클라이언트를 생성하며 다음과 같이 listTables 작업을 직접적으로 호출합니다.

// example.ts
import { DynamoDB } from "@aws-sdk/client-dynamodb";

const region = "us-west-2";
const client = new DynamoDB({ region });
await client.listTables()
  .then(console.log)
  .catch(console.error);

일반적인 사용 사례에 대한 변환을 구현했습니다. 코드가 올바르게 변환되지 않는 경우 입력 코드 예와 관찰/예상된 출력 코드가 포함된 bug report 또는 feature request를 작성하세요. 특정 사용 사례가 existing issue에서 이미 보고된 경우 공감을 표시하여 지지를 보여주세요.

버전 3의 새 기능

JavaScript (v3) 용 SDK 버전 3에는 다음과 같은 새로운 기능이 포함되어 있습니다.

또한 SDK가 내장되어 있어 정적 TypeScript 타이핑과 같은 많은 장점이 있습니다.

모듈화된 패키지

JavaScript (v2) 용 SDK 버전 2에서는 다음과 같이 전체 AWS SDK를 사용해야 합니다.

var AWS = require("aws-sdk");

애플리케이션에서 여러 서비스를 사용하는 경우 전체 SDK를 로드해도 문제가 되지 않습니다. AWS 하지만 몇 가지 AWS 서비스만 사용해야 한다면 필요하거나 사용하지 않는 코드로 애플리케이션 크기를 늘려야 합니다.

v3에서는 필요한 개별 AWS 서비스만 로드하여 사용할 수 있습니다. 이는 다음 예에 나와 있는데, 이렇게 하면 Amazon DynamoDB(DynamoDB)에 액세스할 수 있습니다.

import { DynamoDB } from "@aws-sdk/client-dynamodb";

개별 AWS 서비스를 로드하여 사용할 수 있을 뿐만 아니라 필요한 서비스 명령만 로드하여 사용할 수 있습니다. 이는 DynamoDB 클라이언트 및 ListTablesCommand 명령에 액세스할 수 있는 다음 예에 나와 있습니다.

import {
  DynamoDBClient,
  ListTablesCommand
} from "@aws-sdk/client-dynamodb";

import { CognitoIdentity } from "@aws-sdk/client-cognito-identity/CognitoIdentity";

import { CognitoIdentity } from "@aws-sdk/client-cognito-identity";

코드 크기 비교

버전 2 (v2) 에서는 리전의 모든 Amazon DynamoDB 테이블을 나열하는 간단한 코드 예제가 다음과 us-west-2 같을 수 있습니다.

var AWS = require("aws-sdk");
// Set the Region
AWS.config.update({ region: "us-west-2" });
// Create DynamoDB service object
var ddb = new AWS.DynamoDB({ apiVersion: "2012-08-10" });

// Call DynamoDB to retrieve the list of tables
ddb.listTables({ Limit: 10 }, function (err, data) {
  if (err) {
    console.log("Error", err.code);
  } else {
    console.log("Tables names are ", data.TableNames);
  }
});

v3은 다음과 같습니다.

import {
  DynamoDBClient,
  ListTablesCommand
} from "@aws-sdk/client-dynamodb";

const dbclient = new DynamoDBClient({ region: "us-west-2" });

try {
  const results = await dbclient.send(new ListTablesCommand);
  
  for (const item of results.TableNames) {
    console.log(item);
  }
} catch (err) {
  console.error(err)
}

aws-sdk 패키지는 애플리케이션에 약 40MB를 추가합니다. var AWS = require("aws-sdk")를 import {DynamoDB} from "@aws-sdk/client-dynamodb"로 바꾸면 오버헤드가 약 3MB로 줄어듭니다. 가져오기를 DynamoDB 클라이언트 및 ListTablesCommand 명령으로만 제한하면 오버헤드가 100KB 미만으로 줄어듭니다.

// Load the DynamoDB client and ListTablesCommand command for Node.js
import {
  DynamoDBClient,
  ListTablesCommand
} from "@aws-sdk/client-dynamodb";
const dbclient = new DynamoDBClient({});

v3에서 커맨드 호출하기

v2 또는 v3 명령을 사용하여 v3에서 작업을 수행할 수 있습니다. v3 명령을 사용하려면 명령과 필수 AWS 서비스 패키지 클라이언트를 가져온 다음 async/await 패턴을 사용하는 .send 메서드를 사용하여 명령을 실행합니다.

v2 명령을 사용하려면 필요한 AWS 서비스 패키지를 가져와서 콜백 또는 async/await 패턴을 사용하여 패키지에서 직접 v2 명령을 실행합니다.

v3 명령 사용

v3은 각 AWS 서비스 패키지에 대한 명령 세트를 제공하여 해당 서비스에 대한 작업을 수행할 수 있도록 합니다. AWS AWS 서비스를 설치한 후 프로젝트의 node-modules/@aws-sdk/client-PACKAGE_NAME/commands folder.에서 사용 가능한 명령을 찾아볼 수 있습니다.

사용하려는 명령을 가져와야 합니다. 예를 들어 다음 코드는 DynamoDB 서비스와 CreateTableCommand 명령을 로드합니다.

import { DynamoDB, CreateTableCommand } from "@aws-sdk/client-dynamodb";

권장되는 async/await 패턴으로 이러한 명령을 직접적으로 호출하려면 다음 구문을 사용합니다.

CLIENT.send(new XXXCommand);

예를 들어 다음 예에서는 권장되는 async/await 패턴을 사용하여 DynamoDB 테이블을 생성합니다.

import { DynamoDB, CreateTableCommand } from "@aws-sdk/client-dynamodb";
const dynamodb = new DynamoDB({ region: "us-west-2" });
const tableParams = {
  Table: TABLE_NAME
};

try {
  const data = await dynamodb.send(new CreateTableCommand(tableParams));
  console.log("Success", data);
} catch (err) {
  console.log("Error", err);
};

v2 명령어 사용

SDK에서 v2 명령어를 사용하려면 다음 코드에 나와 있는 것처럼 전체 AWS 서비스 패키지를 가져와야 합니다. JavaScript

const { DynamoDB } = require('@aws-sdk/client-dynamodb');

권장되는 async/await 패턴으로 v2 명령을 호출하려면 다음 구문을 사용하십시오.

client.command(parameters);

다음 예제에서는 v2 createTable 명령을 사용하여 권장 async/await 패턴을 사용하여 DynamoDB 테이블을 생성합니다.

const { DynamoDB } = require('@aws-sdk/client-dynamodb');
const dynamoDB = new DynamoDB({ region: 'us-west-2' });
var tableParams = {
  TableName: TABLE_NAME
};
async function run() => {
  try {
    const data = await dynamoDB.createTable(tableParams);
    console.log("Success", data);
  }
  catch (err) {
    console.log("Error", err);
  }
};
run();

다음 예제에서는 v2 createBucket 명령을 사용하여 콜백 패턴을 사용하여 Amazon S3 버킷을 생성합니다.

const { S3 } = require('@aws-sdk/client-s3');
const s3 = new S3({ region: 'us-west-2' });
var bucketParams = {
  Bucket : BUCKET_NAME
};
function run() {
  s3.createBucket(bucketParams, function (err, data) {
    if (err) {
      console.log("Error", err);
    } else {
      console.log("Success", data.Location);
    }
  })
};
run();

새 미들웨어 스택

SDK v2를 사용하면 요청에 이벤트 리스너를 연결하여 수명 주기의 여러 단계에서 요청을 수정할 수 있습니다. 이 접근 방식을 사용하면 요청의 수명 주기 동안 무엇이 잘못되었는지 디버깅하기가 어려울 수 있습니다.

v3에서는 새 미들웨어 스택을 사용하여 작업 호출의 수명 주기를 제어할 수 있습니다. 이 접근 방식은 몇 가지 이점을 제공합니다. 스택의 각 미들웨어 단계는 요청 객체를 변경한 후 다음 미들웨어 단계를 직접적으로 호출합니다. 이렇게 하면 어떤 미들웨어 단계가 호출되어 오류가 발생했는지 정확하게 확인할 수 있으므로 스택의 문제를 디버깅하는 것도 훨씬 쉬워집니다.

다음 예에서는 미들웨어를 사용하여 Amazon DynamoDB 클라이언트(앞서 생성하고 보여준)에 사용자 지정 헤더를 추가합니다. 첫 번째 인수는 직접적으로 호출할 스택의 다음 미들웨어 단계인 next와 직접적으로 호출되는 작업에 관한 일부 정보가 포함된 객체인 context를 받는 함수입니다. 이 함수는 작업 및 요청에 전달되는 파라미터가 포함된 객체인 args를 받는 함수를 반환합니다. args를 사용하여 다음 미들웨어를 호출한 결과를 반환합니다.

dbclient.middlewareStack.add(
  (next, context) => args => {
    args.request.headers["Custom-Header"] = "value";
    return next(args);
  },
  {
    name: "my-middleware",
    override: true,
    step: "build"
  }
);

dbclient.send(new PutObjectCommand(params));