AWS SDK for JavaScript のバージョン 2.x から 3.x に移行する

AWS SDK for JavaScript バージョン 3 はバージョン 2 の大幅な書き換えです。このセクションでは、2 つのバージョンの相違点と、SDK for JavaScript のバージョン 2 からバージョン 3 に移行する方法について説明します。

codemod を使用してコードを SDK for JavaScript v3 に移行する

AWS SDK for JavaScript バージョン 3 (v3) は、クライアント設定およびユーティリティ用の最新インターフェイスが付属していて、認証情報、Amazon S3 マルチパートアップロード、DynamoDB ドキュメントクライアント、ウェイターなどが含まれます。AWS SDK for JavaScriptGitHub repoの移行ガイドで、v2と各変更にに相当するv3の変更内容を確認できます。

AWS SDK for JavaScript v3 を最大限に活用するには、以下に説明する codemod スクリプトを使用することをお勧めします。

codemod を使用して既存の v2 コードを移行する

aws-sdk-js-codemod での codemod スクリプトのコレクションは、既存の 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 });
await client.listTables({}).promise()
  .then(console.log)
  .catch(console.error);

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 });
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-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";

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のパッケージは、アプリケーションに約40MBを追加します。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" });
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 for JavaScript で v2 コマンドを使用するには、以下のコードに示すように 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();

新しいミドルウェアスタック

SDK の v2 では、イベントリスナーをリクエストに添付することで、ライフサイクルの複数のステージを介してリクエストを変更できるようになりました。このアプローチでは、リクエストのライフサイクル中に問題が発生したことをデバッグすることが困難になる可能性があります。

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