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

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

# 設定適用於 JavaScript 的 SDK
<a name="configuring-the-jssdk"></a>

使用適用於 JavaScript 的 SDK 來使用 API 叫用 Web 服務之前，您必須設定 SDK。您至少必須設定：
+ 您要請求服務 AWS 的區域
+ 您的程式碼如何向 進行身分驗證 AWS

除了這些設定之外，您可能還必須設定 資源的 AWS 許可。例如，您可以限制對 Amazon S3 儲存貯體的存取，或限制 Amazon DynamoDB 資料表進行唯讀存取。

[AWS SDKs和工具參考指南](https://docs.aws.amazon.com/sdkref/latest/guide/)也包含許多 AWS SDKs 中常見的設定、功能和其他基本概念。

本節中的主題說明設定適用於 Node.js 的 JavaScript 開發套件以及在 Web 瀏覽器中執行的 JavaScript 的方法。

**Topics**
+ [每個服務的組態](global-config-object.md)
+ [設定 AWS 區域](setting-region.md)
+ [設定登入資料](setting-credentials.md)
+ [Node.js 考量事項](node-js-considerations.md)
+ [瀏覽器指令碼考量](browser-js-considerations.md)

# 每個服務的組態
<a name="global-config-object"></a>

您可以透過將組態資訊傳遞至服務物件來設定 SDK。

服務層級組態可大幅控制個別服務，讓您在需求與預設組態不同時更新個別服務物件的組態。

**注意**  
在 2.x 版 適用於 JavaScript 的 AWS SDK 的服務組態中，可以傳遞給個別用戶端建構函式。不過，這些組態會先自動合併到全域 SDK 組態 的副本`AWS.config`。  
此外，`AWS.config.update({/* params *})`僅針對進行更新呼叫後執行個體化的服務用戶端呼叫更新組態，而不是任何現有的用戶端。  
這種行為經常造成混淆，使得將組態新增至全域物件變得困難，而這些組態只會以向前相容的方式影響服務用戶端的子集。在版本 3 中，不再有由 SDK 管理的全域組態。組態必須傳遞給執行個體化的每個服務用戶端。仍然可以在多個用戶端之間共用相同的組態，但該組態不會自動與全域狀態合併。

## 設定每個服務的組態
<a name="service-specific-configuration"></a>

您在適用於 JavaScript 的 SDK 中使用的每個服務，都會透過屬於該服務 API 一部分的服務物件存取。例如，若要存取 Amazon S3 服務，您可以建立 Amazon S3 服務物件。您可以指定組態設定，該設定是專屬於該服務物件之建構子的服務。

例如，如果您需要存取多個區域中 AWS 的 Amazon EC2 物件，請為每個區域建立 Amazon EC2 服務物件，然後相應地設定每個服務物件的區域組態。

```
var ec2_regionA = new EC2({region: 'ap-southeast-2', maxAttempts: 15});
var ec2_regionB = new EC2({region: 'us-west-2', maxAttempts: 15});
```

# 設定 AWS 區域
<a name="setting-region"></a>

 AWS 區域是相同地理區域中的一組具名 AWS 資源。區域的範例為 `us-east-1`，即美國東部 （維吉尼亞北部） 區域。您可以在適用於 JavaScript 的 SDK 中建立服務用戶端時指定區域，以便 SDK 存取該區域中的服務。某些 服務僅在特定區域提供。

適用於 JavaScript 的 SDK 預設不會選取區域。不過，您可以使用環境變數或共用組態`config`檔案來設定 AWS 區域。

## 在用戶端類別建構函數中
<a name="setting-region-constructor"></a>

當您執行個體化服務物件時，您可以將該資源 AWS 的區域指定為用戶端類別建構函數的一部分，如下所示。

```
const s3Client = new S3.S3Client({region: 'us-west-2'});
```

## 使用環境變數
<a name="setting-region-environment-variable"></a>

您可以使用 `AWS_REGION` 環境變數來設定區域。如果您定義此變數，適用於 JavaScript 的 SDK 會讀取並使用它。

## 使用共用組態檔案
<a name="setting-region-config-file"></a>

就像共用登入資料檔案可讓您存放登入資料以供軟體開發套件使用一樣，您可以將 AWS 區域和其他組態設定保留在名為 `config` 的共用檔案中，供軟體開發套件使用。如果`AWS_SDK_LOAD_CONFIG`環境變數設定為真實值，適用於 JavaScript 的 SDK 會在載入時自動搜尋`config`檔案。`config` 檔案的儲存位置取決於您的作業系統：
+ Linux、macOS 或 Unix 使用者 - `~/.aws/config`
+ Windows 使用者 - `C:\Users\USER_NAME\.aws\config`

如果您還沒有共用 `config` 檔案，您可以在指定的目錄中建立一個。在下列範例中，`config` 檔案會同時設定區域和輸出格式。

```
[default]
   region=us-west-2
   output=json
```

如需使用共用`config`和`credentials`檔案的詳細資訊，請參閱 *AWS SDKs * [和工具參考指南中的共用組態和登入資料檔案](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)。

## 設定區域的優先順序
<a name="setting-region-order-of-precedence"></a>

以下是區域設定的優先順序：

1. 如將某區域傳遞至用戶端類別建構子，則會使用該區域。

1. 如果在環境變數中設定區域，則會使用該區域。

1. 否則，會使用共用組態檔案中定義的區域。

# 設定登入資料
<a name="setting-credentials"></a>

AWS 使用登入資料來識別誰正在呼叫 服務，以及是否允許存取請求的資源。

不論是在 web 瀏覽器或 Node.js 伺服器上執行，JavaScript 程式碼必須包含有效的登入資料，才能透過 API 存取服務。您可以將登入資料直接傳遞至服務物件，以為每個服務設定登入資料。

有幾個方式可以來設定在 web 瀏覽器中 Node.js 和 JavaScript 之間不同的登入資料。本節的主題說明如何在 Node.js 或 Web 瀏覽器設定登入資料。在每個案例中，選項會以建議的順序呈現。

## 登入資料的最佳實務
<a name="credentials-best-practices"></a>

適當設定登入資料可確保您的應用程式或瀏覽器指令碼可以存取所需的服務與資源，同時將可能影響關鍵任務應用程式或洩漏敏感資料的安全性問題的接觸降到最低。

在特定登入資料時要套用的重要原則，即是一律授予任務所需的最低權限。提供資源的最低許可並視需要新增進一步許可是較安全的作法，而不是提供超過最低權限的許可，而造成您必須修復在稍後可能發現的安全性問題。例如，除非您需要讀取和寫入個別資源，例如 Amazon S3 儲存貯體或 DynamoDB 資料表中的物件，否則請將這些許可設定為唯讀。

如需授予最低權限的詳細資訊，請參閱《*IAM 使用者指南*》中最佳實務主題的[授予最低權限](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege)一節。

**Topics**
+ [登入資料的最佳實務](#credentials-best-practices)
+ [在 Node.js 中設定登入資料](setting-credentials-node.md)
+ [在 Web 瀏覽器中設定登入資料](setting-credentials-browser.md)

# 在 Node.js 中設定登入資料
<a name="setting-credentials-node"></a>

我們建議在本機開發 的新使用者，而不是由其雇主提供身分驗證方法來設定 AWS IAM Identity Center。如需詳細資訊，請參閱[使用 進行 SDK 身分驗證 AWS](getting-your-credentials.md)。

在 Node.js 中將登入資料提供給軟體開發套件有幾種方法。有些方法比較安全，有些在開發應用程式時更方便。在 Node.js 中取得登入資料時，請小心依賴多個來源，例如環境變數和您載入的 JSON 檔案。您可以變更程式碼執行所用的許可，而不需了解發生的變更。

適用於 JavaScript 的 AWS SDK V3 在 Node.js 中提供預設登入資料提供者鏈結，因此您不需要明確提供登入資料提供者。預設[登入資料提供者鏈結](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html#credentialProviderChain)會嘗試在指定優先順序中從各種不同來源解析登入資料，直到其中一個來源傳回登入資料為止。您可以在[此處](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromnodeproviderchain)找到適用於 JavaScript V3 的 SDK 的登入資料提供者鏈結。

## 登入資料提供者鏈結
<a name="credchain"></a>

所有 SDKs 都有一系列位置 （或來源） 可供他們檢查，以取得可用於向 提出請求的有效登入資料 AWS 服務。找到有效的憑證後，系統就會停止搜尋。此系統化搜尋稱為預設登入資料提供者鏈結。

對於鏈結中的每個步驟，有不同的方法來設定值。直接在程式碼中設定值一律優先，接著設定為環境變數，然後在共用 AWS `config`檔案中設定。如需詳細資訊，請參閱 *AWS SDKs 和工具參考指南*中的[設定優先順序](https://docs.aws.amazon.com/sdkref/latest/guide/settings-reference.html#precedenceOfSettings)。

*AWS SDKs和工具參考指南*提供 AWS SDKs和 所使用的開發套件組態設定資訊 AWS CLI。若要進一步了解如何透過共用 AWS `config`檔案設定 SDK，請參閱[共用組態和登入資料檔案](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)。若要進一步了解如何透過設定環境變數來設定 SDK，請參閱[環境變數支援](https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html)。

若要使用 驗證 AWS， 會依照下表列出的順序 適用於 JavaScript 的 AWS SDK 檢查登入資料提供者。

[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html)

如果您遵循建議的方法讓新使用者開始使用，您可以在開始使用主題[使用 進行 SDK 身分驗證 AWS](getting-your-credentials.md)期間設定 AWS IAM Identity Center 身分驗證。其他身分驗證方法適用於不同的情況。為了避免安全風險，我們建議您一律使用短期登入資料。如需其他身分驗證方法程序，請參閱*AWS SDKs和工具參考指南》中的身分*[驗證和存取](https://docs.aws.amazon.com/sdkref/latest/guide/access.html)。

本節的主題說明如何在 Node.js 中載入登入資料。

**Topics**
+ [登入資料提供者鏈結](#credchain)
+ [從 Amazon EC2 的 IAM 角色載入 Node.js 中的登入資料](loading-node-credentials-iam.md)
+ [載入 Node.js Lambda 函數的登入資料](loading-node-credentials-lambda.md)

# 從 Amazon EC2 的 IAM 角色載入 Node.js 中的登入資料
<a name="loading-node-credentials-iam"></a>

如果您在 Amazon EC2 執行個體上執行 Node.js 應用程式，您可以利用 Amazon EC2 的 IAM 角色自動提供登入資料給執行個體。如果您將執行個體設定為使用 IAM 角色，開發套件會自動選取應用程式的 IAM 登入資料，無需手動提供登入資料。

如需將 IAM 角色新增至 Amazon EC2 執行個體的詳細資訊，請參閱 [Amazon EC2 的 IAM 角色](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html)。

# 載入 Node.js Lambda 函數的登入資料
<a name="loading-node-credentials-lambda"></a>

建立 AWS Lambda 函數時，您必須建立具有執行函數許可的特殊 IAM 角色。此角色稱為*執行角色*。設定 Lambda 函數時，您必須指定您建立的 IAM 角色做為對應的執行角色。

執行角色會提供 Lambda 函數執行 和 呼叫其他 Web 服務所需的登入資料。因此，您不需要提供登入資料給在 Lambda 函數中寫入的 Node.js 程式碼。

如需建立 Lambda 執行角色的詳細資訊，請參閱《 *AWS Lambda 開發人員指南*》中的[管理許可：使用 IAM 角色 （執行角色）](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html#lambda-intro-execution-role)。

# 在 Web 瀏覽器中設定登入資料
<a name="setting-credentials-browser"></a>

透過瀏覽器指令碼將登入資料提供給軟體開發套件有幾種方法。有些方法比較安全，有些在開發指令碼時更方便。

 以下是您可以依建議順序提供登入資料的方式：

1. 使用 Amazon Cognito Identity 驗證使用者並提供登入資料

1. 使用 Web 聯合身分

**警告**  
我們不建議硬式編碼指令碼中的 AWS 登入資料。將登入資料寫死會造成存取金鑰 ID 和私密存取金鑰遭暴露的風險。

**Topics**
+ [使用 Amazon Cognito Identity 來驗證使用者](loading-browser-credentials-cognito.md)

# 使用 Amazon Cognito Identity 來驗證使用者
<a name="loading-browser-credentials-cognito"></a>

為瀏覽器指令碼取得 AWS 登入資料的建議方法是使用 Amazon Cognito Identity 登入資料用戶端 `CognitoIdentityClient`。Amazon Cognito 可透過第三方身分提供者對使用者進行身分驗證。

若要使用 Amazon Cognito Identity，您必須先在 Amazon Cognito 主控台中建立身分集區。身分集區代表應用程式提供給使用者的身分群組。提供給使用者的身分可唯一識別每個使用者帳戶。Amazon Cognito 身分不是憑證。在 AWS Security Token Service () 中使用 Web 聯合身分支援交換憑證AWS STS。

Amazon Cognito 可協助您管理多個身分提供者的身分抽象。接著，會將載入的身分交換為在 AWS STS中的登入資料。

## 設定 Amazon Cognito Identity 登入資料物件
<a name="browser-cognito-configuration"></a>

如果您尚未建立身分集區，請先在 [Amazon Cognito 主控台](https://console.aws.amazon.com/cognito)中建立身分集區，以與瀏覽器指令碼搭配使用，再設定 Amazon Cognito 用戶端。建立身分集區的已驗證和未驗證 IAM 角色，並將其建立關聯。如需詳細資訊，請參閱《*Amazon Cognito 開發人員指南*》中的[教學課程：建立身分集](https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-identity-pool.html)區。

未驗證的使用者未驗證其身分，因此此角色適合應用程式的訪客使用者，或在使用者是否驗證其身分無關緊要的情況下。已驗證使用者透過驗證其身分的第三方身分提供者來登入應用程式。請務必適當地限制資源許可範圍，以避免從未經授權的使用者授與資源的存取權。

設定身分集區之後，請使用 中的 `fromCognitoIdentityPool`方法`@aws-sdk/credential-providers`，從身分集區擷取登入資料。在建立 Amazon S3 用戶端的下列範例中，將 *AWS\$1REGION* 取代為區域，並將 *IDENTITY\$1POOL\$1ID* 取代為身分集區 ID。

```
// Import required AWS SDK clients and command for Node.js
import {S3Client} from "@aws-sdk/client-s3";
import {fromCognitoIdentityPool} from "@aws-sdk/credential-providers";

const REGION = AWS_REGION;

const s3Client = new S3Client({
  region: REGION,
  credentials: fromCognitoIdentityPool({
    clientConfig: { region: REGION }, // Configure the underlying CognitoIdentityClient.
    identityPoolId: 'IDENTITY_POOL_ID',
    logins: {
            // Optional tokens, used for authenticated login.
        },
  })
});
```

選用的 `logins` 屬性是身分提供者名稱與這些身分提供者的身分權杖的對應。您從身分提供者取得權杖的方式，取決於您使用的供應商。例如，如果您使用 Amazon Cognito 使用者集區做為身分驗證提供者，您可以使用類似以下的方法。

```
// Get the Amazon Cognito ID token for the user. 'getToken()' below.
let idToken = getToken();
let COGNITO_ID = "COGNITO_ID"; // 'COGNITO_ID' has the format 'cognito-idp.REGION.amazonaws.com/COGNITO_USER_POOL_ID'
let loginData = {
  [COGNITO_ID]: idToken,
};
const s3Client = new S3Client({
    region: REGION,
    credentials: fromCognitoIdentityPool({
    clientConfig: { region: REGION }, // Configure the underlying CognitoIdentityClient.
    identityPoolId: 'IDENTITY_POOL_ID',
    logins: loginData
  })
});

// Strips the token ID from the URL after authentication.
window.getToken = function () {
  var idtoken = window.location.href;
  var idtoken1 = idtoken.split("=")[1];
  var idtoken2 = idtoken1.split("&")[0];
  var idtoken3 = idtoken2.split("&")[0];
  return idtoken3;
};
```

## 將未驗證的使用者切換為已驗證的使用者
<a name="browser-switching-unauthenticated-users"></a>

Amazon Cognito 支援已驗證和未驗證的使用者。未驗證的使用者即使沒有以任何身分提供者登入，也能存取您的資源。這個程度的存取能在使用者登入前就顯示內容，非常有用。每個未驗證的使用者在 Amazon Cognito 中都有唯一的身分，即使他們尚未個別登入和驗證。

### 最初未驗證的使用者
<a name="browser-initially-unauthenticated-user"></a>

使用者通常會以未經驗證的角色開始，您會為該角色設定組態物件的登入資料屬性，而不使用 `logins` 屬性。在這種情況下，您的預設登入資料可能如下所示：

```
// Import the required 適用於 JavaScript 的 AWS SDK v3 modules.                   
import {fromCognitoIdentityPool} from "@aws-sdk/credential-providers";
// Set the default credentials.
const creds = fromCognitoIdentityPool({
  identityPoolId: 'IDENTITY_POOL_ID',
  clientConfig: { region: REGION } // Configure the underlying CognitoIdentityClient.
});
```

### 切換到已驗證使用者
<a name="switch-to-authenticated"></a>

當未驗證的使用者登入身分提供者且您擁有權杖時，您可以呼叫更新憑證物件並新增`logins`權杖的自訂函數，將使用者從未驗證切換到已驗證。

```
// Called when an identity provider has a token for a logged in user
function userLoggedIn(providerName, token) {
  creds.params.Logins = creds.params.logins || {};
  creds.params.Logins[providerName] = token;
                    
  // Expire credentials to refresh them on the next request
  creds.expired = true;
}
```

# Node.js 考量事項
<a name="node-js-considerations"></a>

雖然 Node.js 程式碼是 JavaScript，但在 Node.js 適用於 JavaScript 的 AWS SDK 中使用 可能會與在瀏覽器指令碼中使用 SDK 不同。有些在 Node.js 中可運作的 API 方法無法在瀏覽器指令碼中運作，反之亦然。是否能成功使用某些 API，取決於您對常見 Node.js 程式碼編寫方式的熟悉程度，例如匯入及使用 `File System (fs)` 模組之類的其他 Node.js 模組。

**注意**  
AWS 建議使用 Node.js 的 Active LTS 版本進行開發。

## 使用內建 Node.js 模組
<a name="node-common-modules"></a>

Node.js 會提供您可以使用而不需安裝的內建模組集合。若要使用這些模組，請使用 `require` 方法建立物件來指定模組名稱。例如，若要包含內建 HTTP 模組，請使用以下資訊。

```
import http from 'http';
```

呼叫模組方法 (就好像是該物件的方法)。例如，這裡是讀取 HTML 檔案的程式碼。

```
// include File System module
import fs from "fs"; 
// Invoke readFile method 
fs.readFile('index.html', function(err, data) {
  if (err) {
    throw err;
  } else {
    // Successful file read
  }
});
```

如需 Node.js 提供的所有內建模組的完整清單，請參閱 [Node.js 網站上的 Node.js 文件](https://nodejs.org/api/modules.html)。

## 使用 npm 套件
<a name="node-npm-packages"></a>

除了內建模組之外，您還可以包含和整合來自 Node`npm`.js 套件管理員 的第三方程式碼。這是開放原始碼 Node.js 套件的儲存庫以及用來安裝那些套件的命令列界面。如需 `npm`和目前可用套件清單的詳細資訊，請參閱 [ https：//https://www.npmjs.com](https://www.npmjs.com)。您也可以了解您可以在 [ GitHub 上在此處](https://github.com/sindresorhus/awesome-nodejs)使用的其他 Node.js 套件。

# 在 Node.js 中設定 maxSockets
<a name="node-configuring-maxsockets"></a>

您可以在 Node.js 中，依來源設定連線數量上限。如果已設定 ` maxSockets`，低階 HTTP 用戶端會在請求可供使用時將它們排入佇列並指派至通訊端。

這可讓您隨時為指定來源的並行請求數設定上限。降低此值可能會減少調節量或接收的逾時錯誤數。然而，這也可能增加記憶體使用量，因為請求在通訊端可用前都會排在佇列中。

下列範例示範如何`maxSockets`設定 DynamoDB 用戶端。

```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { NodeHttpHandler } from "@smithy/node-http-handler";
import https from "https";    
let agent = new https.Agent({
  maxSockets: 25
});

let dynamodbClient = new DynamoDBClient({
  requestHandler: new NodeHttpHandler({
    requestTimeout: 3_000,
    httpsAgent: agent
  });
});
```

如果您未提供`maxSockets`值或`Agent`物件，適用於 JavaScript 的 SDK 會使用 50 的值。如果您提供`Agent`物件，則會使用其`maxSockets`值。如需在 Node.js `maxSockets`中設定 的詳細資訊，請參閱 [Node.js 文件](https://nodejs.org/dist/latest/docs/api/http.html#http_agent_maxsockets)。

從 的 v3.521.0 開始 適用於 JavaScript 的 AWS SDK，您可以使用下列[速記語法](https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/CLIENTS.md#new-in-v35210)來設定 `requestHandler`。

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

const client = new DynamoDBClient({
  requestHandler: {
    requestTimeout: 3_000,
    httpsAgent: { maxSockets: 25 },
  },
});
```

# 在 Node.js 中使用保持連線
<a name="node-reusing-connections"></a>

預設 Node.js HTTP/HTTPS 代理程式會為每個新的請求建立新的 TCP 連線。為了避免建立新連線的成本， *預設*會 適用於 JavaScript 的 AWS SDK 重複使用 TCP 連線。

對於短期操作，例如 Amazon DynamoDB 查詢，設定 TCP 連線的延遲額外負荷可能大於操作本身。此外，由於 DynamoDB [靜態加密](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/encryption.howitworks.html)已與 整合[AWS KMS](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/encryption.howitworks.html)，因此資料庫可能會遇到延遲，您必須為每個操作重新建立新的 AWS KMS 快取項目。

如果您不想重複使用 TCP 連線，您可以停用`keepAlive`以每個服務用戶端為基礎與 即時重複使用這些連線，如下列 DynamoDB 用戶端範例所示。

```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { NodeHttpHandler } from "@smithy/node-http-handler";
import { Agent } from "https";

const dynamodbClient = new DynamoDBClient({
    requestHandler: new NodeHttpHandler({
        httpsAgent: new Agent({ keepAlive: false })
    })
});
```

如果`keepAlive`已啟用 ，您也可以使用 設定 TCP Keep-Alive 封包的初始延遲`keepAliveMsecs`，預設為 1000 毫秒。請參閱 [Node.js 文件](https://nodejs.org/api/http.html#new-agentoptions)了解詳細資訊。

# 設定 Node.js 的代理
<a name="node-configuring-proxies"></a>

如果您無法直接連線至網際網路，適用於 JavaScript 的 SDK 支援透過第三方 HTTP 代理程式使用 HTTP 或 HTTPS 代理。

若要尋找第三方 HTTP 代理程式，請在 [npm](https://www.npmjs.com/) 搜尋「HTTP 代理」。

若要安裝第三方 HTTP 代理程式代理，請在命令提示中輸入以下內容，其中 *PROXY* 是`npm`套件的名稱。

```
npm install PROXY --save
```

若要在應用程式中使用代理，請使用 `httpAgent`和 ` httpsAgent` 屬性，如下列 DynamoDB 用戶端範例所示。

```
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { NodeHttpHandler } from "@smithy/node-http-handler";
import { HttpsProxyAgent } from "hpagent";
const agent = new HttpsProxyAgent({ proxy: "http://internal.proxy.com" });
const dynamodbClient = new DynamoDBClient({
    requestHandler: new NodeHttpHandler({
        httpAgent: agent,
        httpsAgent: agent
    }),
});
```

**注意**  
`httpAgent` 與 不同`httpsAgent`，由於來自用戶端的大多數呼叫將是 `https`，因此應同時設定兩者。

# 在 Node.js 中註冊憑證套件
<a name="node-registering-certs"></a>

Node.js 的預設信任存放區包含存取 AWS 服務所需的憑證。在某些案例中，建議您僅包含特定一組憑證。

在此範例中，磁碟上特定憑證會用來建立拒絕連線的 ` https.Agent` (除非提供指定的憑證)。`https.Agent` 然後DynamoDB 用戶端會使用新建立的 。

```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { NodeHttpHandler } from "@smithy/node-http-handler";
import { Agent } from "https";
import { readFileSync } from "fs";
const certs = [readFileSync("/path/to/cert.pem")];
const agent = new Agent({
  rejectUnauthorized: true,
  ca: certs
});
const dynamodbClient = new DynamoDBClient({
  requestHandler: new NodeHttpHandler({
    httpAgent: agent,
    httpsAgent: agent
  })
});
```

# 瀏覽器指令碼考量
<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"}]
  }
  **/
};
```