AWS SDK for JavaScript v2가 지원 종료에 도달했습니다. [AWS SDK for JavaScript v3](https://docs.aws.amazon.com//sdk-for-javascript/v3/developer-guide/)로 마이그레이션하실 것을 권장합니다. 마이그레이션 방법에 대한 자세한 내용은 해당 [공지 사항](https://aws.amazon.com/blogs//developer/announcing-end-of-support-for-aws-sdk-for-javascript-v2/)을 참조하세요.
# SDK for JavaScript에서 서비스 사용
AWS SDK for JavaScript에서는 클라이언트 클래스 수집을 통해 지원하는 서비스에 액세스할 수 있습니다. 이러한 클라이언트 클래스에서는 일반적으로 *서비스 객체*라고 부르는 서비스 인터페이스 객체를 생성합니다. 지원되는 각 AWS 서비스에는 서비스 기능 및 리소스 사용을 위해 하위 수준 API를 제공하는 하나 이상의 클라이언트 클래스가 있습니다. 예를 들어 Amazon DynamoDB API는 `AWS.DynamoDB` 클래스를 통해 사용할 수 있습니다.
SDK for JavaScript를 통해 노출되는 서비스는 요청-응답 패턴에 따라 호출 애플리케이션과 메시지를 교환합니다. 이 패턴에서 서비스를 호출하는 코드는 해당 서비스의 엔트포인트에 HTTP/HTTPS 요청을 제출합니다. 이 요청에는 호출 중인 특정 기능을 성공적으로 호출하는 데 필요한 파라미터가 포함되어 있습니다. 호출된 서비스는 다시 요청자에게 보낼 응답을 생성합니다. 이 응답에는 작업에 성공에 성공한 경우에는 데이터가, 작업에 실패한 경우에는 오류 정보가 포함됩니다.
![\[AWS 요청 응답 서비스 패턴\]](http://docs.aws.amazon.com/ko_kr/sdk-for-javascript/v2/developer-guide/images/request-response.png)
AWS 서비스 호출에는 모든 시도를 비롯하여 서비스 객체에 대한 작업의 전체 요청 및 응답 수명 주기가 포함되어 있습니다. 요청은 `AWS.Request` 객체가 SDK에서 캡슐화합니다. 응답은 `AWS.Response` 객체가 SDK에서 캡슐화하고, 호출 함수 또는 JavaScript promise 등과 같은 여러 기법 중 하나를 통해 요청자에게 제공됩니다.
**Topics**
+ [서비스 객체 생성 및 호출](creating-and-calling-service-objects.md)
+ [AWS SDK for JavaScript 호출 로깅](logging-sdk-calls.md)
+ [비동기식 서비스 호출](calling-services-asynchronously.md)
+ [응답 객체 사용](the-response-object.md)
+ [JSON 작업](working-with-json.md)
+ [AWS SDK for JavaScript v2의 재시도 전략](retry-strategy.md)
# 서비스 객체 생성 및 호출
JavaScript API는 사용 가능한 AWS 서비스를 대부분 지원합니다. JavaScript API의 각 서비스 클래스는 서비스 내 모든 API 호출에 대한 액세스를 제공합니다. JavaScript API의 서비스 클래스, 작업 및 파라미터에 대한 자세한 내용은 [API 참조](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/index.html)를 참조하세요.
Node.js에서 SDK를 사용하는 경우에는 `require`를 사용하여 애플리케이션에 SDK 패키지를 추가합니다. 이 패키지는 현재 모든 서비스에 대한 지원을 제공합니다.
```
var AWS = require('aws-sdk');
```
브라우저 JavaScript와 함께 SDK를 사용하는 경우에는 AWS 호스팅 SDK 패키지를 사용하여 브라우저 스크립트에 SDK 패키지를 로드합니다. SDK 패키지를 로드하려면 다음 `
```
[AWS SDK for JavaScript API 참조 가이드](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/)의 SDK for JavaScript에 대한 API 참조 섹션에서 현재 SDK\$1VERSION\$1NUMBER를 찾을 수 있습니다.
호스팅된 기본 SDK 패키지는 사용 가능한 AWS 서비스의 하위 세트에 대한 지원을 제공합니다. 브라우저를 위해 호스팅되는 SDK 패키지의 기본 서비스 목록은 API 참조의 [지원되는 서비스](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/#Supported_Services)를 참조하세요. CORS 보안 확인이 비활성화된 경우에는 다른 서비스와 함께 SDK를 사용할 수 있습니다. 이러한 경우에는 필요한 추가 서비스를 포함하도록 사용자 지정 SDK 버전을 빌드할 수 있습니다. 사용자 지정 SDK 버전 빌드에 대한 자세한 내용은 [브라우저용 SDK 빌드](building-sdk-for-browsers.md) 섹션을 참조하세요.
## 개별 서비스 필요
이전에 설명한 것처럼 SDK for JavaScript가 필요하면 코드에 전체 SDK를 포함해야 합니다. 또는 코드에서 사용하는 개별 서비스만 필요하도록 선택할 수도 있습니다. Amazon S3 서비스 객체를 생성하려면 아래의 코드를 사용하는 것이 좋습니다.
```
// Import the AWS SDK
var AWS = require('aws-sdk');
// Set credentials and Region
// This can also be done directly on the service client
AWS.config.update({region: 'us-west-1', credentials: {YOUR_CREDENTIALS}});
var s3 = new AWS.S3({apiVersion: '2006-03-01'});
```
이전 예제에서 `require` 함수는 전체 SDK를 지정했습니다. Amazon S3 서비스에 필요한 SDK의 일부만 포함하면 네트워크를 통해 전송되는 코드의 양과 코드의 메모리 오버헤드가 크게 줄어들 수 있습니다. 개별 서비스를 필요로 하기 위해서는 표시된 것처럼 서비스 생성자를 포함해 `require` 함수를 모두 소문자로 호출합니다.
```
require('aws-sdk/clients/SERVICE');
```
SDK의 Amazon S3 부분만 포함했을 때의 이전 Amazon S3 서비스 객체를 생성하는 코드는 아래와 유사합니다.
```
// Import the Amazon S3 service client
var S3 = require('aws-sdk/clients/s3');
// Set credentials and Region
var s3 = new S3({
apiVersion: '2006-03-01',
region: 'us-west-1',
credentials: {YOUR_CREDENTIALS}
});
```
모든 서비스가 연결되지 않은 상태에서 전역 AWS 네임스페이스에 액세스할 수 있습니다.
```
require('aws-sdk/global');
```
이는 예를 들어 모든 서비스에 동일한 자격 증명을 제공하기 위해 여러 개별 서비스 간에 동일한 구성을 적용하는 경우 유용한 기법입니다. 개별 서비스만 필요하면 Node.js에서 로드 시간과 메모리 사용량이 줄어듭니다. Browserify 또는 webpack 등과 같은 번들링 도구를 사용해 수행하는 경우 개별 서비스만 필요로 하면 SDK가 전체 크기의 몇 분의 일 수준으로 줄어듭니다. 이는 IoT 디바이스 또는 Lambda 함수와 같이 메모리 또는 디스크 공간이 제한된 환경에서 유용합니다.
## 서비스 객체 생성
JavaScript API를 통해 서비스 기능에 액세스하려면 기본 클라이언트 클래스에서 제공하는 기능 세트에 액세스하기 위해 통하는 *서비스 객체*를 먼저 생성합니다. 일반적으로 각 서비스에는 클라이언트 클래스 하나가 제공되지만 일부 서비스는 여러 클라이언트 클래스 간에 기능에 대한 액세스를 나눕니다.
기능을 사용하려면 해당 기능에 대한 액세스를 제공하는 클래스의 인스턴스를 생성해야 합니다. 다음 예제에서는 `AWS.DynamoDB` 클라이언트 클래스에서 DynamoDB에 대한 서비스 객체 생성을 보여줍니다.
```
var dynamodb = new AWS.DynamoDB({apiVersion: '2012-08-10'});
```
기본적으로 서비스 객체는 SDK를 구성하는 데에도 사용된 전역 설정으로 구성됩니다. 그러나 해당 서비스 객체에 고유한 런타임 구성 데이터를 사용해 서비스 객체를 구성할 수 있습니다. 서비스별 구성 데이터는 전역 구성 설정을 적용한 다음에 적용됩니다.
다음 예제에서 Amazon EC2 서비스 객체는 특정 리전에 대한 구성 또는 전역 구성을 사용해 생성됩니다.
```
var ec2 = new AWS.EC2({region: 'us-west-2', apiVersion: '2014-10-01'});
```
개별 서비스 객체에 적용된 서비스별 구성을 지원하는 것 외에도 지정된 클래스의 새로 생성된 서비스 객체 모두에 서비스별 구성을 적용할 수도 있습니다. 예를 들어, 미국 서부(오레곤)(`us-west-2`) 리전을 사용하도록 클래스에서 생성된 모든 서비스 객체를 구성하려면 `AWS.config` 전역 구성 객체에 다음을 추가합니다.
```
AWS.config.ec2 = {region: 'us-west-2', apiVersion: '2016-04-01'};
```
## 서비스 객체의 API 버전 잠금
객체를 생성할 때 `apiVersion` 옵션을 지정하여 서비스의 특정 API 버전으로 서비스 객체를 잠글 수 있습니다. 다음 예제에서는 특정 API 버전으로 잠긴 DynamoDB 서비스 객체가 생성됩니다.
```
var dynamodb = new AWS.DynamoDB({apiVersion: '2011-12-05'});
```
서비스 객체의 API 버전 잠금에 대한 자세한 내용은 [API 버전 잠금](locking-api-versions.md) 섹션을 참조하세요.
## 서비스 객체 파라미터 지정
서비스 객체의 메서드를 호출할 때 API에서 요구하는 대로 파라미터를 JSON으로 전달합니다. 예를 들어 Amazon S3에서, 지정된 버킷 및 키에 대한 객체를 가져오려면 `getObject` 메서드에 다음 파라미터를 전달합니다. JSON 파라미터 전달에 대한 자세한 내용은 [JSON 작업](working-with-json.md) 섹션을 참조하세요.
```
s3.getObject({Bucket: 'bucketName', Key: 'keyName'});
```
Amazon S3 파라미터에 관한 자세한 내용은 API 참조의 [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html) 섹션을 참조하세요.
또한 `params` 파라미터를 사용하여 서비스 객체를 생성할 때 개별 파라미터에 값을 바인딩할 수 있습니다. 서비스 객체의 `params` 파라미터 값은 서비스 객체가 정의한 파라미터 값을 하나 이상 지정하는 맵입니다. 다음 예제에서는 `amzn-s3-demo-bucket` 버킷으로 바인딩된 Amazon S3 서비스 객체의 `Bucket` 파라미터를 보여줍니다.
```
var s3bucket = new AWS.S3({params: {Bucket: 'amzn-s3-demo-bucket'}, apiVersion: '2006-03-01' });
```
서비스 객체를 버킷으로 바인딩함으로써 `s3bucket` 서비스 객체는 `amzn-s3-demo-bucket` 파라미터 값을 후속 작업에 대해 더 이상 지정할 필요가 없는 기본값으로 취급합니다. 파라미터 값을 적용할 수 없는 작업에 객체를 사용하는 경우에는 모든 바인딩 파라미터 값이 무시됩니다. 새 값을 지정하여 서비스 객체를 호출하면 바인딩된 파라미터를 재정의할 수 있습니다.
```
var s3bucket = new AWS.S3({ params: {Bucket: 'amzn-s3-demo-bucket'}, apiVersion: '2006-03-01' });
s3bucket.getObject({Key: 'keyName'});
// ...
s3bucket.getObject({Bucket: 'amzn-s3-demo-bucket3', Key: 'keyOtherName'});
```
각 메서드에 사용 가능한 파라미터에 대한 자세한 내용은 API 참조에서 확인할 수 있습니다.
# AWS SDK for JavaScript 호출 로깅
AWS SDK for JavaScript는 기본 제공 로거가 함께 제공되므로 SDK for JavaScript로 API 직접 호출을 로깅할 수 있습니다.
콘솔에서 이 로거를 켜고 로그 항목을 인쇄하려면 코드에 다음 명령문을 추가하십시오.
```
AWS.config.logger = console;
```
다음은 로그 출력의 예입니다.
```
[AWS s3 200 0.185s 0 retries] createMultipartUpload({ Bucket: 'amzn-s3-demo-logging-bucket', Key: 'issues_1704' })
```
## 타사 로거 사용
또한 로그 파일 또는 서버에 쓰기 위한 `log()` 또는 `write()` 작업이 있는 경우에는 타사 로거를 사용할 수도 있습니다. SDK for JavaScript에서 사용자 지정 로거를 사용하려면 지침에 따라 설치 및 설정해야 합니다.
브라우저 스크립트 또는 Node.js에서 사용할 수 있는 로거 중 하나는 logplease입니다. Node.js에서는 로그 파일에 로그 항목을 쓰도록 logplease를 구성할 수 있습니다. logplease는 webpack과 함께 사용할 수도 있습니다.
타사 로거를 사용하는 경우에는 로거를 `AWS.Config.logger`에 할당하기 전에 모든 옵션을 설정합니다. 예를 들어, 다음은 외부 로그 파일을 지정하고, logplease에 대한 로그 수준을 설정합니다.
```
// Require AWS Node.js SDK
const AWS = require('aws-sdk')
// Require logplease
const logplease = require('logplease');
// Set external log file option
logplease.setLogfile('debug.log');
// Set log level
logplease.setLogLevel('DEBUG');
// Create logger
const logger = logplease.create('logger name');
// Assign logger to SDK
AWS.config.logger = logger;
```
logplease에 대한 자세한 내용은 GitHub에서 [logplease Simple JavaScript Logger](https://github.com/haadcode/logplease)를 참조하세요.
# 비동기식 서비스 호출
SDK를 통해 수행한 모든 요청은 비동기식입니다. 브라우저 스크립트를 작성할 때 이 점을 항상 주의해야 합니다. 웹 브라우저에서 실행 중인 JavaScript에는 일반적으로 실행 스레드가 하나 뿐입니다. AWS 서비스에 대한 비동기식 호출 이후에 브라우저 스크립트는 계속해서 실행되고 그 과정에서 브라우저 스크립트에서 반환하기 전에 비동기식 결과를 사용하는 코드를 실행하려고 시도할 수 있습니다.
AWS 서비스에 대한 비동기식 호출에는 이러한 호출에 대한 관리가 필요합니다. 그래야 코드가 데이터를 사용할 수 있기 전에 데이터를 사용하려고 시도하지 않습니다. 이 섹션의 주제에서는 비동기식 호출 관리의 필요성과 비동기식 호출 관리에 사용할 수 있는 다양한 기법에 대해 자세히 다룹니다.
**Topics**
+ [비동기식 호출 관리](making-asynchronous-calls.md)
+ [익명 콜백 함수 사용](using-a-callback-function.md)
+ [요청 객체 이벤트 리스너 사용](using-a-response-event-handler.md)
+ [비동기/대기 사용](using-async-await.md)
+ [JavaScript Promises 사용](using-promises.md)
# 비동기식 호출 관리
예를 들어, 전자 상거래 웹 사이트의 홈 페이지에서는 재방문 고객이 로그인할 수 있습니다. 로그인한 고객을 위한 혜택의 일부로 로그인 후 사이트에서는 고객의 특정 기본 설정에 맞춰 사이트를 맞춤화합니다. 사이트를 맞춤화하려면 다음을 수행해야 합니다.
1. 고객이 로그인하고 로그인 보안 인증으로 검증되어야 합니다.
1. 고객 데이터베이스에서 고객의 기본 설정이 요청됩니다.
1. 데이터베이스에서는 페이지 로드 전에 사이트를 맞춤화하는 데 사용되는 고객의 기본 설정을 제공합니다.
이러한 작업이 동기식으로 실행되면 다음 작업을 시작하기 전에 각 작업이 끝나야 합니다. 따라서 고객 기본 설정이 데이터베이스에서 반환될 때까지 웹 페이지 로딩을 완료할 수 없습니다. 그러나 데이터베이스 쿼리가 서버로 전송된 후 네트워크 병목 현상, 예외적으로 높은 데이터베이스 트래픽 또는 불안한 모바일 디바이스 연결 등으로 인해 고객 데이터 수신이 지연되거나 실패할 수 있습니다.
이러한 상황에서도 웹 사이트가 멈추지 않도록 하기 위해 데이터베이스를 비동기식을 호출합니다. 데이터베이스 호출을 실행한 후 비동기 요청을 보내면 코드가 계속해서 예상대로 실행됩니다. 비동기 호출의 응답을 적절하게 관리하지 못하면 데이터를 아직 사용할 수 없는데도 코드가 데이터베이스에서 다시 필요한 정보를 사용하려고 시도할 수 있습니다.
![\[동기식 실행과 비동기식 실행 간의 차이\]](http://docs.aws.amazon.com/ko_kr/sdk-for-javascript/v2/developer-guide/images/async-vs-sync.png)
# 익명 콜백 함수 사용
`AWS.Request` 객체를 생성하는 각 서비스 객체 메서드는 익명 콜백 함수를 마지막 파라미터로 수락할 수 있습니다. 이 콜백 함수의 서명은 다음과 같습니다.
```
function(error, data) {
// callback handling code
}
```
이 콜백 함수는 성공적인 응답 또는 오류 데이터 반환 시 실행됩니다. 메서드 호출에 성공하면 `data` 파라미터에서 응답 내용을 콜백 함수에 사용할 수 있습니다. 호출에 실패하면 `error` 파라미터에 자세한 실패 정보가 제공됩니다.
일반적으로 콜백 함수 내 코드는 오류가 있는지 테스트하는데, 오류가 반환되면 처리합니다. 오류가 반환되지 않으면 코드는 응답의 `data` 파라미터에서 데이터를 검색합니다. 콜백 함수의 기본 형식은 다음 예제와 같습니다.
```
function(error, data) {
if (error) {
// error handling code
console.log(error);
} else {
// data handling code
console.log(data);
}
}
```
이전 예제에서는 오류 또는 반환되는 데이터에 대한 자세한 내용이 콘솔에 로깅됩니다. 다음은 서비스 객체에 대한 메서드 호출의 일부로 전달되는 콜백 함수를 보여주는 예제입니다.
```
new AWS.EC2({apiVersion: '2014-10-01'}).describeInstances(function(error, data) {
if (error) {
console.log(error); // an error occurred
} else {
console.log(data); // request succeeded
}
});
```
## 요청 및 응답 객체에 액세스
콜백 함수 내에서 JavaScript 키워드 `this`는 대부분 서비스의 경우 기본 `AWS.Response` 객체를 가리킵니다. 다음 예제에서는 디버깅을 지원하기 위해 `httpResponse` 객체의 `AWS.Response` 속성이 콜백 함수 내에서 사용되어 원시 응답 데이터 및 헤더를 로깅합니다.
```
new AWS.EC2({apiVersion: '2014-10-01'}).describeInstances(function(error, data) {
if (error) {
console.log(error); // an error occurred
// Using this keyword to access AWS.Response object and properties
console.log("Response data and headers: " + JSON.stringify(this.httpResponse));
} else {
console.log(data); // request succeeded
}
});
```
또한 `AWS.Response` 객체에는 원래 메서드 호출에서 보낸 `Request`가 포함된 `AWS.Request` 속성이 있으므로 수행된 요청에 대한 세부 정보에 액세스할 수도 있습니다.
# 요청 객체 이벤트 리스너 사용
서비스 객체 메서드를 호출할 때 익명 콜백 함수를 파라미터로 생성해 전달하지 않으면 해당 메서드 호출은 `AWS.Request` 메서드를 사용해 수동으로 전송해야 하는 `send` 객체를 생성합니다.
응답을 처리하려면 `AWS.Request` 객체에 대한 이벤트 리스너를 생성해 메서드 호출에 대한 콜백 함수를 등록해야 합니다. 다음 예제에서는 성공적인 반환을 위해 서비스 객체 메서드 및 이벤트 리스너를 호출하기 위한 `AWS.Request` 객체를 생성하는 방법을 보여줍니다.
```
// create the AWS.Request object
var request = new AWS.EC2({apiVersion: '2014-10-01'}).describeInstances();
// register a callback event handler
request.on('success', function(response) {
// log the successful data response
console.log(response.data);
});
// send the request
request.send();
```
`send` 객체에 대한 `AWS.Request` 메서드를 호출한 후에는 서비스 객체가 `AWS.Response` 객체를 수신할 때 이벤트 핸들러가 실행됩니다.
`AWS.Request` 객체에 대한 자세한 내용은 API 참조의 [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html) 섹션을 참조하세요. `AWS.Response` 객체에 대한 자세한 내용은 [응답 객체 사용](the-response-object.md) 또는 API 참조의 [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Response.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Response.html) 섹션을 참조하세요.
## 여러 콜백 묶기
모든 요청 객체에 대해 여러 콜백을 등록할 수 있습니다. 다른 이벤트 또는 동일한 이벤트에 대해 여러 콜백을 등록할 수 있습니다. 또한 다음 예제에서처럼 콜백을 묶을 수 있습니다.
```
request.
on('success', function(response) {
console.log("Success!");
}).
on('error', function(response) {
console.log("Error!");
}).
on('complete', function() {
console.log("Always!");
}).
send();
```
## 객체 완료 이벤트 요청
`AWS.Request` 객체는 각 서비스 작업 메서드의 응답을 바탕으로 다음 완료 이벤트를 발생시킵니다.
+ `success`
+ `error`
+ `complete`
이러한 이벤트에 대한 응답으로 콜백 함수를 등록할 수 있습니다. 모든 요청 객체 이벤트의 전체 목록을 보려면 API 참조의 [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html) 클래스를 참조하세요.
### 성공 이벤트
`success` 이벤트는 서비스 객체에서 성공적인 응답을 수신하면 발생합니다. 다음은 성공 이벤트에 대한 콜백 함수를 등록하는 방법입니다.
```
request.on('success', function(response) {
// event handler code
});
```
응답은 서비스의 직렬화된 응답 데이터가 포함된 `data` 속성을 제공합니다. 예를 들어, Amazon S3 서비스 객체의 `listBuckets` 메서드에 대한 직접접 호출은 다음과 같습니다.
```
s3.listBuckets.on('success', function(response) {
console.log(response.data);
}).send();
```
이 호출은 응답을 반환한 다음 콘솔에 다음 `data`속성 내용을 출력합니다.
```
{ Owner: { ID: '...', DisplayName: '...' },
Buckets:
[ { Name: 'someBucketName', CreationDate: someCreationDate },
{ Name: 'otherBucketName', CreationDate: otherCreationDate } ],
RequestId: '...' }
```
### 오류 이벤트
`error` 이벤트는 서비스 객체에서 오류 응답을 수신하면 발생합니다. 다음은 성공 이벤트에 대한 콜백 함수를 등록하는 방법입니다.
```
request.on('error', function(error, response) {
// event handling code
});
```
`error` 이벤트가 발생하면 응답의 `data` 속성 값이 `null`이고 `error` 속성에는 오류 데이터가 포함됩니다. 연결된 `error` 객체는 등록된 콜백 함수에 첫 번째 파라미터로 전달됩니다. 예를 들어, 다음 코드에서는
```
s3.config.credentials.accessKeyId = 'invalid';
s3.listBuckets().on('error', function(error, response) {
console.log(error);
}).send();
```
오류를 반환한 다음 콘솔에 다음 오류 데이터를 출력합니다.
```
{ code: 'Forbidden', message: null }
```
### 완료 이벤트
호출 결과 성공 또는 오류인지 여부에 상관 없이 `complete` 이벤트는 서비스 객체 호출이 완료되면 발생합니다. 다음은 성공 이벤트에 대한 콜백 함수를 등록하는 방법입니다.
```
request.on('complete', function(response) {
// event handler code
});
```
`complete` 이벤트 콜백을 사용하면 성공 또는 오류 여부에 상관 없이 실행해야 하는 모든 요청 정리를 처리할 수 있습니다. `complete` 이벤트에 대한 콜백 내에서 응답 데이터를 사용하면 다음 예제에서 보여주는 것처럼 `response.data` 또는 `response.error` 속성 중 하나에 액세스하기 전에 먼저 두 속성을 확인합니다.
```
request.on('complete', function(response) {
if (response.error) {
// an error occurred, handle it
} else {
// we can use response.data here
}
}).send();
```
## 객체 HTTP 이벤트 요청
`AWS.Request` 객체는 각 서비스 작업 메서드의 응답을 바탕으로 다음 HTTP 이벤트를 발생시킵니다.
+ `httpHeaders`
+ `httpData`
+ `httpUploadProgress`
+ `httpDownloadProgress`
+ `httpError`
+ `httpDone`
이러한 이벤트에 대한 응답으로 콜백 함수를 등록할 수 있습니다. 모든 요청 객체 이벤트의 전체 목록을 보려면 API 참조의 [https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html) 클래스를 참조하세요.
### httpHeaders 이벤트
`httpHeaders` 이벤트는 원격 서버에서 헤더를 보낸 경우 발생합니다. 다음은 성공 이벤트에 대한 콜백 함수를 등록하는 방법입니다.
```
request.on('httpHeaders', function(statusCode, headers, response) {
// event handling code
});
```
콜백 함수에 대한 `statusCode` 파라미터가 HTTP 상태 코드입니다. `headers` 파라미터에는 응답 헤더가 포함되어 있습니다.
### httpData 이벤트
`httpData` 이벤트는 서버에서 응답 데이터 패킷을 스트리밍하기 위해 발생됩니다. 다음은 성공 이벤트에 대한 콜백 함수를 등록하는 방법입니다.
```
request.on('httpData', function(chunk, response) {
// event handling code
});
```
이 이벤트는 일반적으로 전체 응답을 메모리로 로드하는 것이 적절하지 않은 경우 대용량 응답을 청크로 수신하는 데 사용됩니다. 이 이벤트에는 서버의 실제 데이터 중 일부가 포함되어 있는 추가 `chunk` 파라미터가 있습니다.
`httpData` 이벤트에 대한 콜백을 등록한 경우 응답의 `data` 속성에는 요청에 대해 직렬화된 전체 출력이 포함됩니다. 기본 제공 핸들러에 대한 추가 구문 분석 및 메모리 오버헤드가 없는 경우에는 기본 `httpData` 리스너를 제거해야 합니다.
### httpUploadProgress 및 httpDownloadProgress 이벤트
`httpUploadProgress` 이벤트는 HTTP 응답이 추가 데이터를 업로드한 경우 발생합니다. 마찬가지로, `httpDownloadProgress` 이벤트는 HTTP 요청에 추가 데이터를 다운로드한 경우 발생합니다. 다음은 이러한 이벤트에 대한 콜백 함수를 등록하는 방법입니다.
```
request.on('httpUploadProgress', function(progress, response) {
// event handling code
})
.on('httpDownloadProgress', function(progress, response) {
// event handling code
});
```
콜백 함수에 대한 `progress` 파라미터에는 로드된 총 요청 바이트와 함께 객체가 포함되어 있습니다.
### httpError 이벤트
`httpError` 이벤트는 HTTP 요청에 실패한 경우 발생합니다. 다음은 성공 이벤트에 대한 콜백 함수를 등록하는 방법입니다.
```
request.on('httpError', function(error, response) {
// event handling code
});
```
콜백 함수에 대한 `error` 파라미터에는 발생한 오류가 포함되어 있습니다.
### httpDone 이벤트
`httpDone` 이벤트는 서버가 데이터 전송을 마치면 발생합니다. 다음은 성공 이벤트에 대한 콜백 함수를 등록하는 방법입니다.
```
request.on('httpDone', function(response) {
// event handling code
});
```
# 비동기/대기 사용
AWS SDK for JavaScript를 직접 호출할 때 `async/await` 패턴을 사용할 수 있습니다. 콜백을 받는 대부분의 함수는 promise를 반환하지 않습니다. promise를 반환하는 `await` 함수만 사용하므로 `async/await` 패턴을 사용하려면 `.promise()` 메서드를 호출이 끝날 때까지 연결하고 콜백을 제거해야 합니다.
다음 예에서는 async/await를 사용하여 `us-west-2`의 모든 Amazon DynamoDB 테이블을 나열합니다.
```
var AWS = require("aws-sdk");
//Create an Amazon DynamoDB client service object.
dbClient = new AWS.DynamoDB({ region: "us-west-2" });
// Call DynamoDB to list existing tables
const run = async () => {
try {
const results = await dbClient.listTables({}).promise();
console.log(results.TableNames.join("\n"));
} catch (err) {
console.error(err);
}
};
run();
```
**참고**
모든 브라우저가 async/await를 지원하는 것은 아닙니다. async/await를 지원하는 브라우저 목록은 [Async functions](https://caniuse.com/#feat=async-functions)를 참조하세요.
# JavaScript Promises 사용
`AWS.Request.promise` 메서드는 서비스 작업을 호출하고 콜백을 사용하지 않고 비동기식 흐름을 관리하는 방법을 제공합니다. Node.js 및 브라우저 스크립트에서 `AWS.Request` 객체는 콜백 함수 없이 서비스 작업이 호출된 경우 반환됩니다. 요청의 `send` 메서드를 호출하여 서비스를 호출할 수 있습니다.
그러나 `AWS.Request.promise`는 서비스 호출을 즉시 시작하고 응답 `data` 속성을 사용하여 이행되었거나 응답 `error` 속성을 사용하여 거부된 promise를 반환합니다.
```
var request = new AWS.EC2({apiVersion: '2014-10-01'}).describeInstances();
// create the promise object
var promise = request.promise();
// handle promise's fulfilled/rejected states
promise.then(
function(data) {
/* process the data */
},
function(error) {
/* handle the error */
}
);
```
다음 예제에서는 `data` 객체로 이행되었거나 `error` 객체로 거부된 promise를 반환합니다. promise를 사용하는 경우 단일 콜백이 오류 탐지를 담당하지 않습니다. 대신 요청 성공 또는 실패를 바탕으로 올바른 콜백이 호출됩니다.
```
var s3 = new AWS.S3({apiVersion: '2006-03-01', region: 'us-west-2'});
var params = {
Bucket: 'bucket',
Key: 'example2.txt',
Body: 'Uploaded text using the promise-based method!'
};
var putObjectPromise = s3.putObject(params).promise();
putObjectPromise.then(function(data) {
console.log('Success');
}).catch(function(err) {
console.log(err);
});
```
## 여러 Promise 조정
경우에 따라 코드는 여러 비동기식 호출이 모두 성공적으로 반환된 경우에만 조치가 필요한 여러 비동기식 호출을 수행해야 합니다. promise를 사용하지 않고 개별 비동기 메서드 호출을 관리하는 경우 `all` 메서드를 사용하는 추가 promise를 생성할 수 있습니다. 이 메서드는 메서드에 전달한 promise 배열이 이행되는 경우 umbrella promise를 이행합니다. 콜백 함수는 `all` 메서드에 전달되는 promises의 값 배열로 전달됩니다.
다음 예에서 AWS Lambda 함수는 Amazon DynamoDB에 대한 비동기 직접 호출을 3개 수행해야 하는데 각 직접 호출에 대한 promise를 이행한 후에만 완료할 수 있습니다.
```
Promise.all([firstPromise, secondPromise, thirdPromise]).then(function(values) {
console.log("Value 0 is " + values[0].toString);
console.log("Value 1 is " + values[1].toString);
console.log("Value 2 is " + values[2].toString);
// return the result to the caller of the Lambda function
callback(null, values);
});
```
## Promise에 대한 브라우저 및 Node.js 지원
기본 JavaScript promise(ECMAScript 2015)에 대한 지원은 모드가 실행되는 JavaScript 엔진 및 버전에 따라 달라집니다. 코드를 실행해야 하는 각 환경에서 JavaScript promise에 대한 지원을 확인하려면 GitHub에서 [ECMAScript 호환성 표](https://compat-table.github.io/compat-table/es6/)를 참조하세요.
## 기타 Promise 구현 사용
ECMAScript 2015의 기본 promise 구현 이외에 다음을 포함해 타사 promise 라이브러리도 사용할 수 있습니다.
+ [bluebird](http://bluebirdjs.com)
+ [RSVP](https://github.com/tildeio/rsvp.js/)
+ [Q](https://github.com/kriskowal/q).
이러한 선택적 promise 라이브러리는 ECMAScript 5 및 ECMAScript 2015에서 기본 promise 구현을 지원하지 않는 환경에서 코드를 실행해야 하는 경우 유용할 수 있습니다.
타사 promise 라이브러리를 사용하려면 전역 구성 객체의 `setPromisesDependency` 메서드를 호출하여 SDK에 대한 promise 종속성을 설정해야 합니다. 브라우저 스크립트에서 SDK를 로드하기 전에 타사 promise 라이브러리를 로드해야 합니다. 다음 예제에서는 bluebird promise 라이브러리에서 구현을 사용하도록 SDK가 구성되었습니다.
```
AWS.config.setPromisesDependency(require('bluebird'));
```
JavaScript 엔진의 기본 promise 구현을 사용하기 위해 반환하려면 `setPromisesDependency`를 다시 호출하여 라이브러리 이름 대신 `null`을 전달합니다.
# 응답 객체 사용
서비스 객체 메서드가 호출되면 해당 메서드는 콜백 함수에 자신을 전달해 `AWS.Response` 객체를 반환합니다. `AWS.Response` 객체의 속성을 통해 응답 내용에 액세스합니다. 응답 내용에 액세스하는 데 사용할 수 있는 `AWS.Response` 객체의 속성은 다음과 같이 두 가지가 있습니다.
+ `data` 속성
+ `error` 속성
표준 콜백 메커니즘을 사용하는 경우 이러한 두 가지 속성은 다음 예에서처럼 익명 콜백 함수에 대한 파라미터로 제공됩니다.
```
function(error, data) {
if (error) {
// error handling code
console.log(error);
} else {
// data handling code
console.log(data);
}
}
```
## 응답 객체에서 반환된 데이터에 액세스
`data` 객체의 `AWS.Response` 속성에는 서비스 요청에서 반환되는 직렬화된 데이터가 포함되어 있습니다. 요청에 성공하면 `data` 속성에는 반환되는 데이터에 대한 맵을 포함하는 객체가 들어 있습니다. 오류가 발생하면 `data` 속성이 null일 수 있습니다.
다음은 게임의 일부로 사용할 이미지 파일의 이름을 검색하기 위해 DynamoDB 테이블의 `getItem` 메서드를 호출하는 예제입니다.
```
// Initialize parameters needed to call DynamoDB
var slotParams = {
Key : {'slotPosition' : {N: '0'}},
TableName : 'slotWheels',
ProjectionExpression: 'imageFile'
};
// prepare request object for call to DynamoDB
var request = new AWS.DynamoDB({region: 'us-west-2', apiVersion: '2012-08-10'}).getItem(slotParams);
// log the name of the image file to load in the slot machine
request.on('success', function(response) {
// logs a value like "cherries.jpg" returned from DynamoDB
console.log(response.data.Item.imageFile.S);
});
// submit DynamoDB request
request.send();
```
이 예제의 경우 DynamoDB 테이블은 슬롯 머신을 당긴 결과를 `slotParams`의 파라미터가 지정한 대로 보여주는 이미지 조회 테이블입니다.
`getItem` 메서드 호출에 성공하면 `AWS.Response` 객체의 `data` 속성에는 DynamoDB에서 반환한 `Item` 객체가 포함되어 있습니다. 반환된 데이터는 요청의 `ProjectionExpression` 파라미터에 따라 액세스되는데, 이번 경우에서 이 파라미터는 `imageFile` 객체의 `Item` 멤버입니다. `imageFile` 멤버가 문자열 값을 가지고 있기 때문에 `S`의 `imageFile` 하위 멤버 값을 통해 이미지의 파일 이름에 액세스합니다.
## 반환된 데이터를 통해 페이징
경우에 따라 서비스 요청에서 반환하는 `data` 속성의 내용이 여러 페이지에 걸쳐 있을 수 있습니다. `response.nextPage` 메서드를 호출하여 데이터의 다음 페이지에 액세스할 수 있습니다. 이 메서드는 새 요청을 보냅니다. 이 요청에 대한 응답은 콜백 또는 성공 및 오류 리스너를 사용해 캡처할 수 있습니다.
`response.hasNextPage` 메서드를 호출하여 서비스 요청에서 반환한 데이터에 추가 페이지가 있는지 확인할 수 있습니다. 이 메서드는 부울을 반환하여 `response.nextPage` 호출 시 추가 데이터를 반환하는지 여부를 나타냅니다.
```
s3.listObjects({Bucket: 'bucket'}).on('success', function handlePage(response) {
// do something with response.data
if (response.hasNextPage()) {
response.nextPage().on('success', handlePage).send();
}
}).send();
```
## 응답 객체에서 오류 정보에 액세스
`error` 객체의 `AWS.Response` 속성에는 서비스 오류 또는 전송 오류 이벤트 발생 시 확인 가능한 오류 데이터가 포함되어 있습니다. 오류는 다음과 같은 양식으로 반환됩니다.
```
{ code: 'SHORT_UNIQUE_ERROR_CODE', message: 'a descriptive error message' }
```
오류 발생 시 `data` 속성의 값은 `null`입니다. 실패 상태일 수 있는 이벤트를 처리하는 경우에는 `error` 속성 값에 액세스하려고 시도하기 전에 `data` 속성을 설정했는지 항상 확인하십시오.
## 발신 요청 객체에 액세스
`request` 속성은 발신 `AWS.Request` 객체에 대한 액세스를 제공합니다. 이는 원래 `AWS.Request` 객체가 보낸 원래 파라미터에 액세스하기 위해 해당 객체를 참조하는 경우 유용합니다. 다음 예제에서 `request` 속성은 원래 서비스 요청의 `Key` 파라미터에 액세스하는 데 사용됩니다.
```
s3.getObject({Bucket: 'bucket', Key: 'key'}).on('success', function(response) {
console.log("Key was", response.request.params.Key);
}).send();
```
# JSON 작업
JSON은 인간 및 머신 둘 다 판독 가능한 데이터를 교환하기 위한 형식입니다. JSON이라는 이름이 *JavaScript Object Notation*의 약어이긴 하지만 JSON의 형식은 프로그래밍 언어와 관련이 없습니다.
SDK for JavaScript에서는 JSON을 사용하여 요청 시 서비스 객체에 데이터를 전송하고 서비스 객체에서 데이터를 JSON으로 수신합니다. JSON에 대한 자세한 내용은 [json.org](https://json.org)를 참조하세요.
![\[JSON의 일반적인 형식 및 부분 표시\]](http://docs.aws.amazon.com/ko_kr/sdk-for-javascript/v2/developer-guide/images/json-format.png)
JSON은 다음 두 가지 방식으로 데이터를 나타냅니다.
+ *객체*: 순서가 지정되지 안은 이름-값 쌍 모음. 객체는 여는 중괄호(`{`)와 닫는 중괄호(`}`) 내에서 정의됩니다. 각 이름-값 쌍은 이름으로 시작하고 뒤에 콜론과 값이 옵니다. 이름-값 페어는 쉼표로 구분됩니다.
+ *배열*: 순서가 지정된 값 모음. 배열은 여는 대괄호(`[`)와 닫는 대괄호(`]`) 안에 정의됩니다. 배열의 항목들은 쉼표로 구분됩니다.
다음은 객체가 카드 게임의 카드로 표현되는 객체 배열이 포함된 JSON 객체의 예입니다. 각 카드는 두 개의 이름-값 페어로 정의되는데, 하나는 하드를 식별하기 위한 고유한 값을 지정하고, 다른 하나는 해당하는 카드 이미지를 가리키는 URL을 지정합니다.
```
var cards = [{"CardID":"defaultname", "Image":"defaulturl"},
{"CardID":"defaultname", "Image":"defaulturl"},
{"CardID":"defaultname", "Image":"defaulturl"},
{"CardID":"defaultname", "Image":"defaulturl"},
{"CardID":"defaultname", "Image":"defaulturl"}];
```
## 서비스 객체 파라미터로서 JSON
다음은 Lambda 서비스 객체에 대한 호출의 파라미터를 정의하는 데 사용되는 간단한 JSON의 예입니다.
```
var pullParams = {
FunctionName : 'slotPull',
InvocationType : 'RequestResponse',
LogType : 'None'
};
```
`pullParams` 객체는 여는 중괄호와 닫는 중괄호 내에서 쉼표로 구분된 이름-값 페어 3개로 정의됩니다. 서비스 객체 메서드에 파라미터를 제공하는 경우 이름은 호출하려는 서비스 객체 메서드에 대한 파라미터 이름으로 결정됩니다. Lambda 함수를 간접 호출할 때 `FunctionName`, `InvocationType`, `LogType`은 Lambda 서비스 객체에서 `invoke` 메서드를 직접 호출하는 데 사용되는 파라미터입니다.
서비스 객체 메서드 호출에 파라미터를 전달할 때 Lambda 함수를 호출하는 다음 예와 같이 메서드 호출에 JSON 객체를 제공합니다.
```
lambda = new AWS.Lambda({region: 'us-west-2', apiVersion: '2015-03-31'});
// create JSON object for service call parameters
var pullParams = {
FunctionName : 'slotPull',
InvocationType : 'RequestResponse',
LogType : 'None'
};
// invoke Lambda function, passing JSON object
lambda.invoke(pullParams, function(err, data) {
if (err) {
console.log(err);
} else {
console.log(data);
}
});
```
## JSON으로 데이터 반환
JSON에서는 동시에 여러 값을 전송해야 하는 애플리케이션의 부분 간에 데이터를 전달하는 표준 방식을 제공합니다. API 내 클라이언트 클래스의 메서드는 일반적으로 콜백 함수로 전달되는 `data` 파라미터에 JSON을 반환합니다. 예를 들어, 다음은 Amazon S3 클라이언트 클래스의 `getBucketCors` 메서드에 대한 호출입니다.
```
// call S3 to retrieve CORS configuration for selected bucket
s3.getBucketCors(bucketParams, function(err, data) {
if (err) {
console.log(err);
} else if (data) {
console.log(JSON.stringify(data));
}
});
```
`data`의 값은 JSON 객체이며 이 예에서는 지정된 Amazon S3 버킷에 대한 현재 CORS 구성을 설명하는 JSON입니다.
```
{
"CORSRules": [
{
"AllowedHeaders":["*"],
"AllowedMethods":["POST","GET","PUT","DELETE","HEAD"],
"AllowedOrigins":["*"],
"ExposeHeaders":[],
"MaxAgeSeconds":3000
}
]
}
```
# AWS SDK for JavaScript v2의 재시도 전략
DNS 서버, 스위치, 로드 밸런서 등 수많은 네트워크 구성 요소들은 요청이 이루어지는 모든 단계에서 오류를 일으킬 수 있습니다. 네트워크 환경에서는 클라이언트 애플리케이션의 재시도 기술이 이러한 오류 응답을 처리하는 데 가장 많이 사용되고 있습니다. 이 기술은 애플리케이션의 신뢰성을 높일 뿐만 아니라 개발자의 운영 비용을 절감합니다. AWS SDK는 AWS 요청에 대한 자동 재시도 로직을 구현합니다.
## 지수 백오프 기반 재시도 동작
AWS SDK for JavaScript v2는 흐름 제어를 개선하기 위해 [전체 지터(jitter)와 함께 지수 백오프](https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/#Jitter)를 사용하여 재시도 로직을 구현합니다. 지수 백오프의 기본 개념은 오류 응답이 연이어 나올 때마다 재시도 간 대기 시간을 점진적으로 늘리는 것입니다. 지터(무작위 지연)는 연속 충돌을 방지하는 데 사용됩니다.
### v2에서 재시도 지연 테스트
v2에서 재시도 지연을 테스트하기 위해 [node\$1modules/aws-sdk/lib/event\$1listeners.js](https://github.com/aws/aws-sdk-js/blob/master/lib/event_listeners.js#L588)의 코드가 다음과 같이 가변 지연에 있는 `console.log` 값으로 업데이트되었습니다.
```
// delay < 0 is a signal from customBackoff to skip retries
if (willRetry && delay >= 0) {
resp.error = null;
console.log('retry delay: ' + delay);
setTimeout(done, delay);
} else {
done();
}
```
#### 기본 구성으로 지연 재시도
AWS SDK 클라이언트에서 모든 작업에 대한 지연을 테스트할 수 있습니다. 다음 코드를 사용하여 DynamoDB 클라이언트에서 `listTables` 작업을 호출합니다.
```
import AWS from "aws-sdk";
const region = "us-east-1";
const client = new AWS.DynamoDB({ region });
await client.listTables({}).promise();
```
재시도를 테스트하기 위해 테스트 코드를 실행하는 디바이스에서 인터넷 연결을 해제하여 `NetworkingError`를 시뮬레이션합니다. 또한 사용자 지정 오류를 반환하도록 프록시를 설정할 수 있습니다.
코드를 실행할 때 다음과 같이 지터와 함께 지수 백오프를 사용하여 재시도 지연을 확인할 수 있습니다.
```
retry delay: 7.39361151766359
retry delay: 9.0672860785882
retry delay: 134.89340825668168
retry delay: 398.53559817403965
retry delay: 523.8076165896343
retry delay: 1323.8789643058465
```
재시도는 지터를 사용하므로 예제 코드를 실행할 때 다른 값을 얻을 수 있습니다.
#### 사용자 지정 기본으로 지연 재시도
AWS SDK for JavaScript v2를 사용하면 작업 재시도에 대한 지수 백오프에 사용할 사용자 지정 기본 밀리초를 전달할 수 있습니다. DynamoDB를 제외한 모든 서비스의 기본값은 100ms이며, 여기서 기본값은 50ms입니다.
다음과 같이 사용자 지정 기본값이 1,000ms인 재시도를 테스트합니다.
```
...
const client = new AWS.DynamoDB({ region, retryDelayOptions: { base: 1000 } });
...
```
테스트 코드를 실행하는 디바이스에서 인터넷 연결을 해제하여 `NetworkingError`를 시뮬레이션합니다. 기본값이 50ms 또는 100ms인 이전 실행에 비해 재시도 지연 값이 더 높다는 것을 알 수 있습니다.
```
retry delay: 356.2841549924913
retry delay: 1183.5216495444615
retry delay: 2266.997988094194
retry delay: 1244.6948354966453
retry delay: 4200.323030066383
```
재시도는 지터를 사용하므로 예제 코드를 실행할 때 다른 값을 얻을 수 있습니다.
#### 사용자 지정 백오프 알고리즘을 사용하여 지연 재시도
또한 AWS SDK for JavaScript v2를 사용하면 재시도 횟수와 오류를 수락하고 지연 시간을 밀리초 단위로 반환하는 사용자 지정 백오프 함수를 전달할 수 있습니다. 결과가 0이 아닌 음수 값이면 더 이상 재시도하지 않습니다.
다음과 같이 기본값이 200ms인 선형 백오프를 사용하는 사용자 지정 백오프 함수를 테스트합니다.
```
...
const client = new AWS.DynamoDB({
region,
retryDelayOptions: { customBackoff: (count, error) => (count + 1) * 200 },
});
...
```
테스트 코드를 실행하는 디바이스에서 인터넷 연결을 해제하여 `NetworkingError`를 시뮬레이션합니다. 재시도 지연 값은 200의 배수입니다.
```
retry delay: 200
retry delay: 400
retry delay: 600
retry delay: 800
retry delay: 1000
```