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

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

使用 codemod 將 JavaScript v3 SDK 的程式碼遷移至

AWS SDK for JavaScript 第 3 版 (v3) 隨附用戶端組態和公用程式的現代化介面，包括登入資料、Amazon S3 分段上傳、DynamoDB 文件用戶端、服務生等。您可以在AWS SDK for JavaScript GitHub 儲存庫的遷移指南中找到 v2 中的變更，以及每項變更的 v3 對等變更。

若要充分利用 AWS SDK for JavaScript v3，我們建議您使用如下所述的 Codemod 指令碼。

使用 Codemod 遷移現有的 v2 程式碼

中的 Codemod 指令碼集合aws-sdk-js-codemod有助於遷移現有的 AWS SDK for JavaScript (v2) 應用程式以使用 v3 APIs。您可以執行轉換，如下所示。

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

例如，假設您有下列程式碼，從 v2 和呼叫listTables操作建立 Amazon DynamoDB 用戶端。

// example.ts
import AWS from "aws-sdk";

const region = "us-west-2";
const client = new AWS.DynamoDB({ region });
await client.listTables({}).promise()
  .then(console.log)
  .catch(console.error);

您可以在 上執行v2-to-v3轉換example.ts，如下所示。

$ 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 });
await client.listTables({})
  .then(console.log)
  .catch(console.error);

我們已針對常見的使用案例實作轉換。如果您的程式碼未正確轉換，請使用範例輸入碼和觀察/預期的輸出碼建立錯誤報告或功能請求。如果您的特定使用案例已在現有問題 中報告，請利用 向上播放顯示您的支援。

第 3 版中的新功能

SDK for JavaScript (v3) 第 3 版包含下列新功能。

此外， SDK會寫入 TypeScript，其有許多優點，例如靜態輸入。

模組化套件

SDK for JavaScript (v2) 第 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-2theRegion 中所有 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";

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

try {
  const results = await dbclient.send(new ListTablesCommand);
  
  for (const item of results.TableNames) {
    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 Services 套件用戶端，並使用非同步/等待模式.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" });
const tableParams = {
  TableName: TABLE_NAME
};

try {
  const data = await dynamodb.send(new CreateTableCommand(tableParams));
  console.log("Success", data);
} catch (err) {
  console.log("Error", err);
};

使用 v2 命令

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

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();

新的中介軟體堆疊

的 v2 SDK可讓您在生命週期的多個階段修改請求，方法是將事件接聽程式連接至請求。這種方法可能會讓偵錯請求生命週期內發生錯誤的情況變得困難。

在 v3 中，您可以使用新的中介軟體堆疊來控制操作呼叫的生命週期。此方法提供幾個好處。堆疊中的每個中介軟體階段都會在對請求物件進行任何變更後呼叫下一個中介軟體階段。這也讓 堆疊中的偵錯問題更容易，因為您可以確切看到呼叫了哪些中介軟體階段，導致錯誤。

下列範例使用中介軟體將自訂標頭新增至 Amazon DynamoDB 用戶端 （我們先前建立並顯示）。第一個引數是 接受的函數next，這是堆疊中要呼叫的下一個中介軟體階段，而 context則是包含所呼叫操作的一些資訊的物件。函數會傳回接受 的函數args，該函數是包含傳遞給 操作和 請求的參數的物件。它會傳回使用 呼叫下一個中介軟體的結果args。

dbclient.middlewareStack.add(
  (next, context) => args => {
    args.request.headers["Custom-Header"] = "value";
    return next(args);
  },
  {
    name: "my-middleware",
    override: true,
    step: "build"
  }
);

dbclient.send(new PutObjectCommand(params));