Migrieren Sie von Version 2.x auf 3.x von AWS SDK for JavaScript

Die AWS SDK for JavaScript Version 3 ist eine umfassende Neufassung von Version 2. Der Abschnitt beschreibt die Unterschiede zwischen den beiden Versionen und erklärt, wie Sie von Version 2 auf Version 3 des SDK für JavaScript migrieren.

Migrieren Sie Ihren Code mithilfe von Codemod auf SDK für JavaScript v3

AWS SDK for JavaScript Version 3 (v3) bietet modernisierte Schnittstellen für Client-Konfigurationen und Dienstprogramme, zu denen Anmeldeinformationen, mehrteiliger Amazon S3 S3-Upload, DynamoDB-Dokumentenclient, Kellner und mehr gehören. Was sich in Version 2 geändert hat, und was in Version 3 für jede Änderung geändert wurde, finden Sie im Migrationsleitfaden im Repo. AWS SDK for JavaScript GitHub

Um die Vorteile der Version 3 voll auszuschöpfen, empfehlen AWS SDK for JavaScript wir die Verwendung der unten beschriebenen Codemod-Skripte.

Verwenden Sie Codemod, um vorhandenen v2-Code zu migrieren

Die Sammlung von Codemod-Skripten in aws-sdk-js-codemod hilft Ihnen bei der Migration Ihrer vorhandenen (v2) -Anwendung zur Verwendung von v3-APIs. AWS SDK for JavaScript Sie können die Transformation wie folgt ausführen.

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

Stellen Sie sich zum Beispiel vor, Sie haben den folgenden Code, der einen Amazon DynamoDB-Client aus Version 2 erstellt und Operation aufruftlistTables.

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

Sie können unsere v2-to-v3 Transformation example.ts wie folgt ausführen.

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

Die Transformation konvertiert den DynamoDB-Import in Version 3, erstellt einen v3-Client und ruft den listTables Vorgang wie folgt auf.

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

Wir haben Transformationen für gängige Anwendungsfälle implementiert. Wenn Ihr Code nicht korrekt transformiert wird, erstellen Sie bitte einen Fehlerbericht oder eine Funktionsanfrage mit Beispiel-Eingabecode und beobachtetem/erwartetem Ausgabecode. Wenn Ihr spezieller Anwendungsfall bereits in einem bestehenden Problem gemeldet wurde, zeigen Sie Ihre Unterstützung durch eine positive Bewertung.

Was ist neu in Version 3

Version 3 des SDK für JavaScript (v3) enthält die folgenden neuen Funktionen.

Darüber hinaus ist das SDK integriert, was viele Vorteile bietet TypeScript, wie z. B. die statische Typisierung.

Modularisierte Pakete

Für Version 2 des SDK für JavaScript (v2) mussten Sie das gesamte AWS SDK wie folgt verwenden.

var AWS = require("aws-sdk");

Das Laden des gesamten SDK ist kein Problem, wenn Ihre Anwendung viele AWS Dienste verwendet. Wenn Sie jedoch nur wenige AWS Dienste verwenden müssen, bedeutet dies, dass Sie die Größe Ihrer Anwendung mit Code erhöhen müssen, den Sie nicht benötigen oder verwenden.

In Version 3 können Sie nur die einzelnen AWS Dienste laden und verwenden, die Sie benötigen. Dies wird im folgenden Beispiel gezeigt, das Ihnen Zugriff auf Amazon DynamoDB (DynamoDB) gewährt.

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

Sie können nicht nur einzelne AWS Dienste laden und verwenden, sondern Sie können auch nur die Servicebefehle laden und verwenden, die Sie benötigen. Dies wird in den folgenden Beispielen veranschaulicht, die Ihnen Zugriff auf den DynamoDB-Client und den ListTablesCommand Befehl geben.

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

Codegröße vergleichen

In Version 2 (v2) könnte ein einfaches Codebeispiel, das alle Ihre Amazon DynamoDB-Tabellen in der us-west-2 Region auflistet, wie folgt aussehen.

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 sieht wie folgt aus.

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

Das aws-sdk Paket erweitert Ihre Anwendung um etwa 40 MB. Durch das var AWS = require("aws-sdk") Ersetzen durch import {DynamoDB} from "@aws-sdk/client-dynamodb" wird dieser Overhead auf etwa 3 MB reduziert. Durch die Beschränkung des Imports auf den DynamoDB-Client und den ListTablesCommand Befehl wird der Overhead auf weniger als 100 KB reduziert.

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

Befehle in Version 3 aufrufen

Sie können Operationen in Version 3 entweder mit v2- oder v3-Befehlen ausführen. Um v3-Befehle zu verwenden, importieren Sie die Befehle und die erforderlichen AWS Services-Paketclients und führen den Befehl mithilfe der .send Methode aus, die das async/await-Muster verwendet.

Um v2-Befehle zu verwenden, importieren Sie die erforderlichen AWS Services-Pakete und führen den v2-Befehl direkt im Paket aus, indem Sie entweder ein Callback- oder ein Async/Await-Muster verwenden.

Verwenden von v3-Befehlen

v3 stellt für jedes AWS Servicepaket eine Reihe von Befehlen bereit, mit denen Sie Operationen für diesen AWS Dienst ausführen können. Nachdem Sie einen AWS Dienst installiert haben, können Sie die verfügbaren Befehle in Ihrem Projekt durchsuchen node-modules/@aws-sdk/client-PACKAGE_NAME/commands folder.

Sie müssen die Befehle importieren, die Sie verwenden möchten. Der folgende Code lädt beispielsweise den DynamoDB-Dienst und den CreateTableCommand Befehl.

import { DynamoDB, CreateTableCommand } from "@aws-sdk/client-dynamodb";

Verwenden Sie die folgende Syntax, um diese Befehle im empfohlenen Async/Await-Muster aufzurufen.

CLIENT.send(new XXXCommand);

Im folgenden Beispiel wird beispielsweise eine DynamoDB-Tabelle mit dem empfohlenen async/await-Muster erstellt.

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

Verwenden von v2-Befehlen

Um v2-Befehle im SDK für zu verwenden JavaScript, importieren Sie die vollständigen AWS Servicepakete, wie im folgenden Code gezeigt.

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

Verwenden Sie die folgende Syntax, um v2-Befehle im empfohlenen Async/Await-Muster aufzurufen.

client.command(parameters);

Im folgenden Beispiel wird der createTable v2-Befehl verwendet, um eine DynamoDB-Tabelle mit dem empfohlenen async/await-Muster zu erstellen.

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

Im folgenden Beispiel wird der createBucket v2-Befehl verwendet, um einen Amazon S3 S3-Bucket mithilfe des Callback-Musters zu erstellen.

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

Neuer Middleware-Stack

Version 2 des SDK ermöglichte es Ihnen, eine Anfrage in den verschiedenen Phasen ihres Lebenszyklus zu ändern, indem Sie der Anfrage Event-Listener anhängen. Dieser Ansatz kann es schwierig machen, Fehler zu debuggen, die während des Lebenszyklus einer Anfrage schief gelaufen sind.

In Version 3 können Sie einen neuen Middleware-Stack verwenden, um den Lebenszyklus eines Operationsaufrufs zu steuern. Dieser Ansatz bietet eine Reihe von Vorteilen. Jede Middleware-Phase im Stack ruft die nächste Middleware-Stufe auf, nachdem Änderungen am Anforderungsobjekt vorgenommen wurden. Dies erleichtert auch das Debuggen von Problemen im Stack erheblich, da Sie genau sehen können, welche Middleware-Stufen aufgerufen wurden, bevor der Fehler aufgetreten ist.

Das folgende Beispiel fügt einem Amazon DynamoDB-Client (den wir zuvor erstellt und gezeigt haben) mithilfe von Middleware einen benutzerdefinierten Header hinzu. Das erste Argument ist eine Funktion, die akzeptiertnext, was die nächste aufzurufende Middleware-Stufe im Stack ist, und ein Objektcontext, das einige Informationen über die aufgerufene Operation enthält. Die Funktion gibt eine Funktion zurück, die akzeptiertargs, d. h. ein Objekt, das die an den Vorgang und die Anforderung übergebenen Parameter enthält. Sie gibt das Ergebnis des Aufrufs der nächsten Middleware mit zurück. args

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

dbclient.send(new PutObjectCommand(params));