[AWS SDK for JavaScript V3 API 참조 안내서](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/)는 AWS SDK for JavaScript 버전 3(V3)의 모든 API 작업을 자세히 설명합니다.
기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 버전 2.x에서 3.x로 마이그레이션 AWS SDK for JavaScript
AWS SDK for JavaScript 버전 3은 버전 2의 주요 재작성입니다. 이 섹션에서는 두 버전의 차이점을 설명하고 SDK for JavaScript 버전 2에서 버전 3으로 마이그레이션하는 방법을 설명합니다.
## codemod를 사용하여 SDK for JavaScript v3로 코드 마이그레이션
AWS SDK for JavaScript 버전 3(v3)에는 자격 증명, Amazon S3 멀티파트 업로드, DynamoDB 문서 클라이언트, 웨이터 등을 포함하는 클라이언트 구성 및 유틸리티를 위한 현대화된 인터페이스가 함께 제공됩니다. v2에서 변경된 내용과 각 변경 사항에 대한 v3는 [AWS SDK for JavaScript GitHub 리포지토리의 마이그레이션 가이드에서 확인할 수 있습니다](https://github.com/aws/aws-sdk-js-v3/blob/main/UPGRADING.md).
AWS SDK for JavaScript v3를 최대한 활용하려면 아래 설명된 codemod 스크립트를 사용하는 것이 좋습니다.
### codemod를 사용하여 기존 v2 코드 마이그레이션
[aws-sdk-js-codemod](https://www.npmjs.com/package/aws-sdk-js-codemod)의 codemod 스크립트 모음은 v3 APIs를 사용하도록 기존 AWS SDK for JavaScript (v2) 애플리케이션을 마이그레이션하는 데 도움이 됩니다. 다음과 같이 변환을 실행할 수 있습니다.
```
$ 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](https://github.com/awslabs/aws-sdk-js-codemod/issues/new?assignees=&labels=bug%2Ctriage&template=bug_report.yml&title=%5BBug%3F%5D%3A+) 또는 [feature request](https://github.com/awslabs/aws-sdk-js-codemod/issues/new?assignees=&labels=enhancement&template=feature_request.yml&title=%5BFeature%5D%3A+)를 작성하세요. 특정 사용 사례가 [existing issue](https://github.com/awslabs/aws-sdk-js-codemod/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc)에서 이미 보고된 경우 공감을 표시하여 지지를 보여주세요.
## 버전 3의 새 기능
SDK for JavaScript 버전 3(v3)에는 다음과 같은 새로운 기능이 포함되어 있습니다.
모듈화된 패키지
이제 사용자는 각 서비스에 대해 별도의 패키지를 사용할 수 있습니다.
새 미들웨어 스택
이제 사용자는 미들웨어 스택을 사용하여 작업 호출의 수명 주기를 제어할 수 있습니다.
또한 SDK는 TypeScript로 작성되어 정적 형식 지정 등 많은 장점이 있습니다.
**중요**
이 안내서의 v3에 대한 코드 예는 ECMAScript 6(ES6)로 작성되었습니다. ES6는 코드를 더 현대적이고 읽기 쉽게 만들고 더 많은 작업을 수행할 수 있도록 새로운 구문과 새로운 기능을 제공합니다. ES6에서는 Node.js 버전 13.x 이상을 사용해야 합니다. 최신 버전의 Node.js를 다운로드하여 설치하려면 [Node.js downloads](https://nodejs.org/en/download/)를 참조하세요. 자세한 내용은 [JavaScript ES6/CommonJS 구문](sdk-example-javascript-syntax.md) 단원을 참조하십시오.
## 모듈화된 패키지
JavaScript용 SDK(v2) 버전 2에서는 다음과 같이 전체 AWS SDK를 사용해야 했습니다.
```
var AWS = require("aws-sdk");
```
애플리케이션이 많은 AWS 서비스를 사용하는 경우 전체 SDK를 로드하는 것은 문제가 되지 않습니다. 그러나 몇 가지 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)에서 `us-west-2` 리전의 모든 Amazon DynamoDB 테이블을 나열하는 간단한 코드 예는 다음과 같을 수 있습니다.
```
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에서 명령 직접 호출
v3에서 v2 또는 v3 명령을 사용하여 작업을 수행할 수 있습니다. v3 명령을 사용하려면 명령과 필요한 AWS 서비스 패키지 클라이언트를 가져오고 async/await 패턴을 사용하는 `.send` 메서드를 사용하여 명령을 실행합니다.
v2 명령을 사용하려면 필요한 AWS 서비스 패키지를 가져오고 콜백 또는 비동기/대기 패턴을 사용하여 패키지에서 직접 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 {{XXX}}Command);
```
예를 들어 다음 예에서는 권장되는 async/await 패턴을 사용하여 DynamoDB 테이블을 생성합니다.
```
import { DynamoDB, CreateTableCommand } from "@aws-sdk/client-dynamodb";
const dynamodb = new DynamoDB({ region: "us-west-2" });
const tableParams = {
TableName: {{TABLE_NAME}}
};
try {
const data = await dynamodb.send(new CreateTableCommand(tableParams));
console.log("Success", data);
} catch (err) {
console.log("Error", err);
};
```
#### v2 명령 사용
SDK for JavaScript에서 v2 명령을 사용하려면 다음 코드와 같이 전체 AWS 서비스 패키지를 가져옵니다.
```
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));
```