[適用於 JavaScript 的 AWS SDK V3 API 參考指南](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/)詳細說明 第 3 版 適用於 JavaScript 的 AWS SDK (V3) 的所有 API 操作。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 瀏覽器指令碼考量
<a name="browser-js-considerations"></a>

下列主題說明在瀏覽器指令碼 適用於 JavaScript 的 AWS SDK 中使用 的特殊考量。

**Topics**
+ [建置適用於瀏覽器的 SDK](building-sdk-for-browsers.md)
+ [跨來源資源共享 (CORS)](cors.md)
+ [使用 Webpack 綁定應用程式](webpack.md)

# 建置適用於瀏覽器的 SDK
<a name="building-sdk-for-browsers"></a>

與適用於 JavaScript 第 2 版 (V2) 的 SDK 不同，V3 不會做為 JavaScript 檔案提供，並支援預設的服務集。反之，V3 可讓您綁定並在瀏覽器中僅包含所需的適用於 JavaScript 的 SDK 檔案，從而減少額外負荷。我們建議使用 Webpack 將 JavaScript 檔案所需的開發套件，以及您所需的任何其他第三方套件，封裝成單一`Javascript`檔案，並使用`<script>`標籤將其載入瀏覽器指令碼。如需 Webpack 的詳細資訊，請參閱 [使用 Webpack 綁定應用程式](webpack.md)。

如果您在瀏覽器中強制執行 CORS 的環境之外使用軟體開發套件，並且想要存取軟體開發套件 for JavaScript 提供的所有服務，您可以透過複製儲存庫並執行建置軟體開發套件預設託管版本的相同建置工具，在本機建置軟體開發套件的自訂複本。以下區段說明使用額外服務和 API 版本來建立軟體開發套件的步驟。

## 使用 SDK Builder 建置適用於 JavaScript 的 SDK
<a name="using-the-sdk-builder"></a>

**注意**  
Amazon Web Services 第 3 版 (V3) 不再支援瀏覽器建置器。為了將瀏覽器應用程式的頻寬使用量降至最低，我們建議您匯入具名模組，並將其綁定以縮減大小。如需綁定的詳細資訊，請參閱 [使用 Webpack 綁定應用程式](webpack.md)。

# 跨來源資源共享 (CORS)
<a name="cors"></a>

跨來源資源分享 (CORS) 是現代 Web 瀏覽器的一項安全功能，其可讓 Web 瀏覽器協調能請求外部網站或服務的網域。

由於系統會將大多數資源請求傳送至外部網域 (如 Web 服務的端點)，當您使用 適用於 JavaScript 的 AWS SDK 開發瀏覽器應用程式時，CORS 是項重要的考量條件。如果 JavaScript 環境會強制執行 CORS 安全性，您就必須使用服務設定 CORS。

CORS 會根據下列項目，決定是否允許在跨來源請求中共用資源：
+ 提出請求的特定網域 
+ 提出的 HTTP 請求類型 (GET、PUT、POST、DELETE 等)

## CORS 的運作方式
<a name="how-cors-works"></a>

在最簡單的案例中，瀏覽器指令碼會從另一個網域中的伺服器發出資源 GET 請求。依據該伺服器的 CORS 組態而定，如果請求是來自有權提交 GET 請求的網域，則跨來源伺服器會透過傳回請求的資源來予以回應。

若發出請求的網域或 HTTP 請求類型皆未經授權，該請求即會遭拒。然而，CORS 能夠在實際提交請求前進行預檢。此案例中，會發出預檢請求，此請求中會一併傳送 `OPTIONS` 存取請求操作。如果跨來源伺服器的 CORS 組態將存取權限授予給提出請求的網域，伺服器就會傳回預檢回應，其中列出提出請求的網域能對請求資源所進行的 HTTP 請求類型。

![\[CORS 請求的處理流程\]](http://docs.aws.amazon.com/zh_tw/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 主控台中設定 Amazon S3 儲存貯體以使用 CORS。

如果您在 AWS Web Services 管理主控台中設定 CORS，則必須使用 JSON 來建立 CORS 組態。新的 AWS Web Services 管理主控台僅支援 JSON CORS 組態。

**重要**  
在新的 AWS Web 服務管理主控台中，CORS 組態必須是 JSON。

1. 在 AWS Web Services 管理主控台中，開啟 Amazon S3 主控台，尋找您要設定的儲存貯體，然後選取其核取方塊。

1. 在開啟的窗格中，選擇**許可**。

1. 在**許可**索引標籤上，選擇 **CORS 組態**。

1. 在 CORS 組態**編輯器中輸入 CORS 組態**，然後選擇**儲存**。

CORS 組態是一種 XML 檔案，包含 `<CORSRule>` 內的一系列規則。一個組態最多可以擁有 100 條規則，而規則是由下列其中一個標籤所定義：
+ `<AllowedOrigin>` – 指定您允許 提出跨網域請求的網域原始伺服器。
+ `<AllowedMethod>` – 指定您在跨網域請求中允許的請求類型 (GET、PUT、POST、DELETE、HEAD)。
+ `<AllowedHeader>` – 指定預檢請求中允許的標頭。

如需範例組態，請參閱《*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`標籤，如上一個範例所示。軟體開發套件僅能存取透過 CORS 組態公開的標頭。若您在物件上設定中繼資料，則傳回的值即為具有字首 `x-amz-meta-` 的標頭 (如 `x-amz-meta-my-custom-header`)；請務必以相同方式公開該標頭。

# 使用 Webpack 綁定應用程式
<a name="webpack"></a>

在瀏覽器指令碼或 Node.js 中，Web 應用程式使用程式碼模組會建立相依性。這些程式碼模組可能會擁有自己的依存項目，成為一組您的應用程式運作所需的互連模組。若要管理相依性，您可以使用模組套件，例如 `webpack`。

`webpack` 模組套件會剖析您的應用程式程式碼、搜尋 `import`或 `require`陳述式，以建立套件，其中包含應用程式所需的所有資產。如此一來，即可透過網頁輕鬆提供資產。適用於 JavaScript 的 SDK 可以包含在 中`webpack`，做為要包含在輸出套件中的其中一個相依性。

如需 的詳細資訊`webpack`，請參閱 GitHub 上的 [Webpack 模組套件](https://webpack.github.io/)。

## 安裝 Webpack
<a name="webpack-installing"></a>

若要安裝`webpack`模組套件，您必須先安裝 Node.js 套件管理員 npm。輸入下列命令來安裝 `webpack` CLI 和 JavaScript 模組。

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

若要使用 `path`模組來使用使用 Webpack 自動安裝的檔案和目錄路徑，您可能需要安裝 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 文件](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。如果進入點中指定的程式碼匯入或需要其他模組，例如適用於 JavaScript 的 SDK，則該程式碼會綁定，而不需要在組態中指定。

## 執行 Webpack
<a name="webpack-running"></a>

若要建置應用程式以使用 `webpack`，請將下列內容新增至 `package.json` 檔案中的 `scripts` 物件。

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

以下是示範新增 的範例`package.json`檔案`webpack`。

```
{
  "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>

您可以使用 在組態中指定 `node`為目標，`webpack`以產生在 Node.js 中執行的套件。

```
target: "node"
```

當您在磁碟空間有限的環境中執行 Node.js 應用程式時，這個做法十分實用。下方為 `webpack.config.js` 組態範例，而該組態會將 Node.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"}]
  }
  **/
};
```