從第 2.x 版移轉至第 3.x 版 AWS SDK for JavaScript

AWS SDK for JavaScript 版本 3 是版本 2 的主要重寫。本節說明兩個版本之間的差異，並說明如何從 SDK 的版本 2 遷移至第 3 版 JavaScript。

使用代碼模式將您的代碼遷移到 SDK 以獲取 JavaScript v3

AWS SDK for JavaScript 版本 3 (v3) 隨附用戶端組態和公用程式的現代化界面，包括登入資料、Amazon S3 多部分上傳、DynamoDB 文件用戶端、服務員等。您可以在AWS SDK for JavaScript GitHub 存儲庫的遷移指南中找到 v2 中的每個更改的內容和 v3 等價物。

為了充分利用 AWS SDK for JavaScript v3，我們建議您使用下面描述的 codemod 腳本。

使用代碼模式遷移現有的 v2 代碼

在 aws-sdk-JS-代碼模組中的代碼模式腳本的集合有助於遷移您現有的 AWS SDK for JavaScript （v2）應用程序以使用 v3 API。您可以按如下方式運行轉換。

$ 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 });
client.listTables({}, (err, data) => {
  if (err) 
    console.log(err, err.stack);
  else
    console.log(data);
});

您可以如下運行我們example.ts的v2-to-v3變換。

$ npx aws-sdk-js-codemod -t v2-to-v3 example.ts

轉換會將 DynamoDB 匯入轉換為 v3、建立 v3 用戶端，並依照下列方式呼叫listTables作業。

// example.ts
import { DynamoDB } from "@aws-sdk/client-dynamodb";

const region = "us-west-2";
const client = new DynamoDB({ region });
client.listTables({}, (err, data) => {
  if (err)
    console.log(err, err.stack);
  else
    console.log(data);
});

我們已針對常見使用案例實作轉換。如果您的代碼無法正確轉換，請創建錯誤報告或功能請求，其中包含示例輸入代碼和觀察/預期的輸出代碼。如果您的特定使用案例已在現有問題中回報，請透過 upvote 展示您的支援。

第 3 版中的新功能

適用於 JavaScript (v3) 的 SDK 版本 3 包含下列新功能。

此外，SDK 是用來編寫的 TypeScript，它具有許多優點，例如靜態類型。

模塊化軟件包

JavaScript (v2) SDK 的第 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";

(async function () {
  const dbclient = new DynamoDBClient({ region: 'us-west-2' });

  try {
    const results = await dbclient.send(new ListTablesCommand);
    results.TableNames.forEach(function (item, index) {
      console.log(item);
    });
  } catch (err) {
    console.error(err)
  }
})();

該aws-sdk軟件包增加了大約 40 MB 到您的應用程序。替換var AWS = require("aws-sdk")為可將該開銷import {DynamoDB} from "@aws-sdk/client-dynamodb"減少到大約 3 MB。將匯入限制為只有 DynamoDB 用戶端和ListTablesCommand命令，可將額外負荷降低到 100 KB 以下。

// Load the DynamoDB client and ListTablesCommand command for Node.js
import {
  DynamoDBClient,
  ListTablesCommand
} from "@aws-sdk/client-dynamodb";
const dbclient = new DynamoDBClient({});

在 v3 中調用命令

您可以使用 v2 或 v3 命令在 v3 中執行操作。若要使用 v3 命令，請匯入命令和所需的 AWS 服務套件用戶端，並使用使用異步/等待模式的.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";

若要以建議的異步/等待模式呼叫這些命令，請使用下列語法。

CLIENT.send(new XXXCommand);

例如，下列範例會使用建議的異步/等待模式建立 DynamoDB 資料表。

import { DynamoDB, CreateTableCommand } from "@aws-sdk/client-dynamodb";
const dynamodb = new DynamoDB({ region: 'us-west-2' });
var tableParams = {
  Table: TABLE_NAME
};
(async function () => {
  try {
    const data = await dynamodb.send(new CreateTableCommand(tableParams));
    console.log("Success", data);
  }
  catch (err) {
    console.log("Error", err);
  }
}) ();

使用 v2 命令

若要在 SDK 中使用 v2 命令 JavaScript，請匯入完整的 AWS Service 套件，如下列程式碼所示。

const { DynamoDB } = require('@aws-sdk/client-dynamodb');

若要以建議的異步/等待模式呼叫 v2 命令，請使用下列語法。

client.command(parameters);

下列範例會使用 v2 命createTable令，使用建議的異步/等待模式來建立 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);
  },
  {
    step: "build"
  }
);  

dbclient.send(new PutObjectCommand(params));