[AWS SDK for JavaScript V3 API 참조 안내서](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/)는 AWS SDK for JavaScript 버전 3(V3)의 모든 API 작업을 자세히 설명합니다.

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# 브라우저 스크립트 고려 사항
<a name="browser-js-considerations"></a>

다음 주제에서는 브라우저 스크립트 AWS SDK for JavaScript 에서를 사용하기 위한 특별한 고려 사항을 설명합니다.

**Topics**
+ [브라우저용 SDK 빌드](building-sdk-for-browsers.md)
+ [교차 오리진 리소스 공유(CORS)](cors.md)
+ [Webpack으로 애플리케이션 번들링](webpack.md)

# 브라우저용 SDK 빌드
<a name="building-sdk-for-browsers"></a>

SDK for JavaScript 버전 2(V2)와 달리 V3는 기본 서비스 집합에 대한 지원이 포함된 JavaScript 파일로 제공됩니다. 대신 V3를 사용하면 필요한 SDK for JavaScript 파일만 번들로 제공하고 브라우저에 포함할 수 있으므로 오버헤드가 줄어듭니다. Webpack을 사용하여 필수 SDK for JavaScript 파일과 필요한 추가 타사 패키지를 단일 `Javascript` 파일로 번들링하고 `<script>` 태그를 사용하여 브라우저 스크립트에 이 파일을 로드하는 것이 좋습니다. Webpack에 관한 자세한 내용은 [Webpack으로 애플리케이션 번들링](webpack.md) 단원을 참조하세요.

브라우저에서 CORS를 적용하는 환경 외부에서 SDK를 사용하며 SDK for JavaScript에서 제공하는 모든 서비스에 액세스하려는 경우 리포지토리를 복제하고 기본 호스팅 버전의 SDK를 빌드하는 동일한 빌드 도구를 실행하여 SDK의 사용자 지정 사본을 로컬에서 빌드할 수 있습니다. 다음 섹션에서는 추가 서비스 및 API 버전으로 SDK를 빌드하는 단계를 설명합니다.

## SDK 빌더를 사용하여 SDK for JavaScript 빌드
<a name="using-the-sdk-builder"></a>

**참고**  
Amazon Web Services 버전 3(V3)는 더 이상 브라우저 빌더를 지원하지 않습니다. 브라우저 애플리케이션의 대역폭 사용량을 최소화하려면 명명된 모듈을 가져와서 번들링하여 크기를 줄이는 것이 좋습니다. 번들링에 관한 자세한 내용은 [Webpack으로 애플리케이션 번들링](webpack.md) 단원을 참조하세요.

# 교차 오리진 리소스 공유(CORS)
<a name="cors"></a>

CORS(Cross-origin 리소스 공유)는 최신 웹 브라우저의 보안 기능입니다. 이 기능을 사용하면 웹 브라우저가 어떤 도메인이 외부 웹 사이트 또는 서비스를 요청할 수 있을지 협상할 수 있습니다.

대부분의 리소스 요청이 외부 도메인(예: 웹 서비스용 엔드포인트)으로 전송되기 때문에 AWS SDK for JavaScript를 사용해 브라우저 애플리케이션을 개발하는 경우 CORS는 중요한 고려 대상입니다. JavaScript 환경에서 CORS 보안을 적용하는 경우 이 서비스와 함께 CORS를 구성해야 합니다.

CORS는 다음을 기반으로 교차 오리진 요청 시 리소스 공유 허용 여부를 결정합니다.
+ 요청을 수행한 특정 도메인 
+ 수행 중인 HTTP 요청 유형(GET, PUT, POST, DELETE 등)

## CORS 작동 방식
<a name="how-cors-works"></a>

가장 간단한 경우 브라우저 스크립트는 다른 도메인 내 서버의 리소스에 대해 GET 요청을 수행합니다. 요청이 GET 요청을 제출하도록 승인된 도메인에서 전송된 경우 해당 서버의 CORS 구성에 따라 cross-origin 서버는 요청된 리소스를 반환하여 응답합니다.

요청하는 도메인 또는 HTTP 요청 유형이 승인되지 않은 경우에는 요청이 거부됩니다. 그러나 CORS는 요청을 실제로 제출하기 전에 요청을 사전에 보낼 수 있습니다. 이 경우 preflight 요청은 `OPTIONS` 액세스 요청 작업을 전송하는 방식으로 이루어집니다. cross-origin 서버의 CORS 구성이 요청하는 도메인에 대한 액세스 권한을 부여하는 경우 서버에서는 요청하는 도메인이 요청한 리소스에 대해 수행 가능한 HTTP 요청 유형을 모두 나열하는 preflight 응답으로 회신합니다.

![\[CORS 요청의 프로세스 흐름\]](http://docs.aws.amazon.com/ko_kr/sdk-for-javascript/v3/developer-guide/images/cors-overview.png)


## CORS 구성이 필요합니까?
<a name="the-need-for-cors-configuration"></a>

Amazon S3 버킷에서 작업을 수행하려면 먼저 해당 버킷에 CORS 구성이 필요합니다. 일부 JavaScript 환경에서는 CORS가 적용되지 않을 수 있으므로 CORS를 구성할 필요가 없습니다. 예를 들어 Amazon S3 버킷에서 애플리케이션을 호스팅하고 `*.s3.amazonaws.com` 또는 일부 다른 특정 엔드포인트에서 리소스에 액세스하는 경우에는 요청이 외부 도메인에 액세스하지 않습니다. 따라서 이 구성에는 CORS가 필요하지 않습니다. 이 경우에도 CORS는 Amazon S3 이외의 서비스에는 여전히 사용됩니다.

## Amazon S3 버킷에 대한 CORS 구성
<a name="configuring-cors-s3-bucket"></a>

Amazon S3 콘솔에서 CORS를 사용하도록 Amazon S3 버킷을 구성할 수 있습니다.

AWS Web Services Management Console에서 CORS를 구성하는 경우 JSON을 사용하여 CORS 구성을 생성해야 합니다. 새로운 AWS Web Services Management Console은 JSON CORS 구성만 지원합니다.

**중요**  
새 AWS Web Services Management Console에서 CORS 구성은 JSON이어야 합니다.

1. AWS Web Services Management Console에서 Amazon S3 콘솔을 열고, 구성하려는 버킷을 찾아 해당 확인란을 선택합니다.

1. 열리는 창에서 **권한**을 선택합니다.

1. **권한** 탭에서 **CORS 구성**을 선택합니다.

1. **CORS 구성 편집기**에 CORS 구성을 입력한 다음, **저장**을 선택합니다.

CORS 구성은 `<CORSRule>` 내에 일련의 규칙이 포함된 XML 파일입니다. 구성에는 규칙이 최대 100개까지 있을 수 있습니다. 규칙은 다음 태그 중 하나로 정의합니다.
+ `<AllowedOrigin>` - 교차 도메인 요청을 수행하도록 허용하는 도메인 오리진을 지정합니다.
+ `<AllowedMethod>` - 교차 도메인 요청에서 허용하는 요청 유형(GET, PUT, POST, DELETE, HEAD)을 지정합니다.
+ `<AllowedHeader>` - preflight 요청에서 허용되는 헤더를 지정합니다.

구성의 예는 *Amazon Simple Storage Service 사용 설명서*의 [교차 오리진 리소스 공유(CORS) 사용](https://docs.aws.amazon.com/AmazonS3/latest/userguide/cors.html#how-do-i-enable-cors) 단원을 참조하세요.

## CORS 구성의 예
<a name="cors-configuration-example"></a>

다음 CORS 구성 예를 통해 사용자는 `example.org` 도메인에서 버킷 내부의 객체를 보거나 추가하거나 제거하거나 업데이트할 수 있습니다. 그러나 웹 사이트의 도메인으로 `<AllowedOrigin>` 범위를 지정하는 것이 좋습니다. 모든 도메인을 허용하려면 `"*"`를 지정할 수 있습니다.

**중요**  
새 S3 콘솔에서 CORS 구성은 JSON이어야 합니다.

------
#### [ XML ]

```
<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <CORSRule>
    <AllowedOrigin>https://example.org</AllowedOrigin>
    <AllowedMethod>HEAD</AllowedMethod>
    <AllowedMethod>GET</AllowedMethod>
    <AllowedMethod>PUT</AllowedMethod>
    <AllowedMethod>POST</AllowedMethod>
    <AllowedMethod>DELETE</AllowedMethod>
    <AllowedHeader>*</AllowedHeader>
    <ExposeHeader>ETag</ExposeHeader>
    <ExposeHeader>x-amz-meta-custom-header</ExposeHeader>
  </CORSRule>
</CORSConfiguration>
```

------
#### [ JSON ]

```
[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "HEAD",
            "GET",
            "PUT",
            "POST",
            "DELETE"
        ],
        "AllowedOrigins": [
            "https://www.example.org"
        ],
        "ExposeHeaders": [
             "ETag",
             "x-amz-meta-custom-header"]
    }
]
```

------

이 구성은 사용자가 버킷에 대해 작업을 수행하도록 허용하지 않고, 브라우저의 보안 모델이 Amazon S3에 대한 요청을 허용하도록 합니다. 권한은 버킷 권한 또는 IAM 역할 권한을 통해 구성해야 합니다.

`ExposeHeader`를 사용하면 SDK가 Amazon S3에서 반환된 응답 헤더를 읽도록 할 수 있습니다. 예를 들어 `PUT` 또는 멀티파트 업로드에서 `ETag` 헤더를 읽으려면 이전 예와 같이 구성에 `ExposeHeader` 태그를 포함해야 합니다. SDK는 CORS 구성을 통해 노출된 헤더에만 액세스할 수 있습니다. 객체에 대해 메타데이터를 설정한 경우 값은 접두사 `x-amz-meta-`가 붙은 헤더(예: `x-amz-meta-my-custom-header`)로 반환되며 동일한 방식으로 노출되어야 합니다.

# Webpack으로 애플리케이션 번들링
<a name="webpack"></a>

브라우저 스크립트 또는 Node.js에서 웹 애플리케이션이 코드 모듈을 사용하면 종속성이 생성됩니다. 이러한 코드 모듈에는 자체 종속성이 있을 수 있어 애플리케이션 작동에 필요한 상호 연결된 모듈 모음이 생깁니다. 종속성을 관리하려면 `webpack`과 같은 모듈 번들러를 사용하면 됩니다.

`webpack` 모듈 번들러는 애플리케이션 코드를 구문 분석하여 `import` 또는 `require` 문을 검색해 애플리케이션에 필요한 모든 자산이 포함된 번들을 생성합니다. 이렇게 하면 웹 페이지를 통해 자산을 쉽게 제공할 수 있습니다. SDK for JavaScript는 출력 번들에 포함할 종속성 중 하나로 `webpack`에 포함될 수 있습니다.

`webpack`에 관한 자세한 내용은 GitHub의 [webpack module bundler](https://webpack.github.io/)를​ 참조하세요.

## Webpack 설치
<a name="webpack-installing"></a>

`webpack` 모듈 번들러를 설치하려면 먼저, Node.js 패키지 관리자인 npm이 설치되어 있어야 합니다. 다음 명령을 입력하여 `webpack` CLI 및 JavaScript 모듈을 설치합니다.

```
npm install --save-dev webpack
```

webpack과 함께 자동으로 설치되는 파일 및 디렉터리 경로 작업을 위해 `path` 모듈을 사용하려면 Node.js `path-browserify` 패키지를 설치해야 할 수도 있습니다.

```
npm install --save-dev path-browserify
```

## Webpack 구성
<a name="webpack-configuring"></a>

기본적으로 webpack은 프로젝트의 루트 디렉터리에서 `webpack.config.js`라는 JavaScript 파일을 검색합니다. 이 파일은 구성 옵션을 지정합니다. 다음은 WebPack 버전 5.0.0 이상에 대한 `webpack.config.js` 구성 파일의 예입니다.

**참고**  
Webpack 구성 요구 사항은 설치하는 Webpack 버전에 따라 다릅니다. 자세한 내용은 [Webpack documentation](https://webpack.js.org/configuration/)을 참조하세요.

```
// Import path for resolving file paths
var path = require("path");
module.exports = {
  // Specify the entry point for our app.
  entry: [path.join(__dirname, "browser.js")],
  // Specify the output file containing our bundled code.
  output: {
    path: __dirname,
    filename: 'bundle.js'
  },
   // Enable WebPack to use the 'path' package.
   resolve:{
  fallback: { path: require.resolve("path-browserify")}
  }
  /**
  * In Webpack version v2.0.0 and earlier, you must tell 
  * webpack how to use "json-loader" to load 'json' files.
  * To do this Enter 'npm --save-dev install json-loader' at the 
  * command line to install the "json-loader' package, and include the 
  * following entry in your webpack.config.js.
  * module: {
    rules: [{test: /\.json$/, use: use: "json-loader"}]
  }
  **/
};
```

이 예에서는 `browser.js`가 *진입점*으로 지정됩니다. 이 *진입점*은 `webpack`이 가져온 모듈 검색을 시작하는 데 사용하는 파일입니다. 출력의 파일 이름은 `bundle.js`로 지정합니다. 출력 파일에는 애플리케이션에서 실행해야 하는 JavaScript가 모두 포함되어 있습니다. 진입점에 지정된 코드가 SDK for JavaScript와 같은 다른 모듈을 가져오거나 필요로 하는 경우 해당 코드는 구성에서 이를 지정할 필요 없이 번들링됩니다.

## Webpack 실행
<a name="webpack-running"></a>

`webpack`을 사용하는 애플리케이션을 빌드하려면 `package.json` 파일의 `scripts` 객체에 다음을 추가합니다.

```
"build": "webpack"
```

다음은 `webpack` 추가를 보여주는 `package.json` 파일의 예입니다.

```
{
  "name": "aws-webpack",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "build": "webpack"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {
    "@aws-sdk/client-iam": "^3.32.0",
    "@aws-sdk/client-s3": "^3.32.0"
  },
  "devDependencies": {
    "webpack": "^5.0.0"
  }
}
```

애플리케이션을 빌드하려면 다음 명령을 입력합니다.

```
npm run build
```

그러면 `webpack` 모듈 번들러가 프로젝트의 루트 디렉터리에 지정한 JavaScript 파일을 생성합니다.

## Webpack 번들 사용
<a name="webpack-using-bundle"></a>

브라우저 스크립트에서 번들을 사용하려면 다음 예와 같이 `<script>` 태그를 사용해 번들을 포함하면 됩니다.

```
<!DOCTYPE html>
<html>
    <head>
        <title>Amazon SDK with webpack</title>
    </head> 
    <body>
        <div id="list"></div>
        <script src="bundle.js"></script>
    </body>
</html>
```

## Node.js에 대한 번들링
<a name="webpack-nodejs-bundles"></a>

`webpack`을 사용하면 구성에서 `node`를 대상으로 지정하여 Node.js에서 실행되는 번들을 생성할 수 있습니다.

```
target: "node"
```

이는 디스크 공간이 제한된 환경에서 Node.js 애플리케이션을 실행하는 경우 유용합니다. 다음은 출력 대상으로 Node.js가 지정된 `webpack.config.js` 구성의 예입니다.

```
// Import path for resolving file paths
var path = require("path");
module.exports = {
  // Specify the entry point for our app.
  entry: [path.join(__dirname, "browser.js")],
  // Specify the output file containing our bundled code.
  output: {
    path: __dirname,
    filename: 'bundle.js'
  },
  // Let webpack know to generate a Node.js bundle.
  target: "node",
   // Enable WebPack to use the 'path' package.
   resolve:{
  fallback: { path: require.resolve("path-browserify")}
   /**
   * In Webpack version v2.0.0 and earlier, you must tell 
   * webpack how to use "json-loader" to load 'json' files.
   * To do this Enter 'npm --save-dev install json-loader' at the 
   * command line to install the "json-loader' package, and include the 
   * following entry in your webpack.config.js.
   module: {
    rules: [{test: /\.json$/, use: use: "json-loader"}]
  }
  **/
};
```