Migrez de la version 2.x vers la version 3.x du AWS SDK for JavaScript

La AWS SDK for JavaScript version 3 est une réécriture majeure de la version 2. La section décrit les différences entre les deux versions et explique comment migrer de la version 2 à la version 3 du SDK for JavaScript.

Migrez votre code vers SDK for JavaScript v3 à l'aide de codemod

AWS SDK for JavaScript la version 3 (v3) est dotée d'interfaces modernisées pour les configurations client et les utilitaires, notamment les informations d'identification, le téléchargement partitionné sur Amazon S3, le client de documents DynamoDB, les serveurs, etc. Vous pouvez trouver ce qui a changé dans la v2 et les équivalents v3 pour chaque modification dans le guide de migration sur le AWS SDK for JavaScript GitHub dépôt.

Pour tirer pleinement parti de la AWS SDK for JavaScript v3, nous vous recommandons d'utiliser les scripts codemod décrits ci-dessous.

Utiliser codemod pour migrer le code v2 existant

La collection de scripts Codemod aws-sdk-js-codemodpermet de migrer votre application existante AWS SDK for JavaScript (v2) pour utiliser la v3. APIs Vous pouvez exécuter la transformation comme suit.

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

Par exemple, supposons que vous avez le code suivant, qui crée un client Amazon DynamoDB à partir de la version 2 et appelle une opération. 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);

Vous pouvez exécuter notre v2-to-v3 transformation example.ts comme suit.

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

La transformation convertira l'importation DynamoDB en version 3, créera un client v3 et appellera l'opération comme suit. 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);

Nous avons mis en œuvre des transformations pour les cas d'utilisation courants. Si votre code ne se transforme pas correctement, veuillez créer un rapport de bogue ou une demande de fonctionnalité avec un exemple de code d'entrée et un code de sortie observé/attendu. Si votre cas d'utilisation spécifique est déjà signalé dans un numéro existant, montrez votre soutien par un vote positif.

Nouveautés de la version 3

La version 3 de SDK for JavaScript (v3) contient les nouvelles fonctionnalités suivantes.

De plus, le SDK est écrit TypeScript, ce qui présente de nombreux avantages, tels que la saisie statique.

Packages modularisés

La version 2 du SDK for JavaScript (v2) exigeait que vous utilisiez l'intégralité AWS SDK, comme suit.

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

Le chargement complet SDK n'est pas un problème si votre application utilise de nombreux AWS services. Toutefois, si vous n'avez besoin que de quelques AWS services, cela signifie augmenter la taille de votre application avec du code dont vous n'avez pas besoin ou que vous n'utilisez pas.

Dans la version 3, vous ne pouvez charger et utiliser que les AWS services individuels dont vous avez besoin. Cela est illustré dans l'exemple suivant, qui vous donne accès à Amazon DynamoDB (DynamoDB).

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

Vous pouvez non seulement charger et utiliser AWS des services individuels, mais vous pouvez également charger et utiliser uniquement les commandes de service dont vous avez besoin. Cela est illustré dans les exemples suivants, qui vous permettent d'accéder au client DynamoDB et à la commande. 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";

Comparaison de la taille du code

Dans la version 2 (v2), un exemple de code simple répertoriant toutes vos tables Amazon DynamoDB de us-west-2 la région peut ressembler à ce qui suit.

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

La v3 ressemble à ce qui suit.

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

Le aws-sdk package ajoute environ 40 Mo à votre application. Le remplacement var AWS = require("aws-sdk") par import {DynamoDB} from "@aws-sdk/client-dynamodb" réduit cette surcharge à environ 3 Mo. Le fait de limiter l'importation au client ListTablesCommand et à la commande DynamoDB permet de réduire la surcharge à moins de 100 Ko.

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

Appeler des commandes dans la version 3

Vous pouvez effectuer des opérations dans la version 3 à l'aide des commandes v2 ou v3. Pour utiliser les commandes v3, vous importez les commandes et les clients du package AWS Services requis, puis exécutez la commande en utilisant la .send méthode utilisant le modèle async/await.

Pour utiliser les commandes v2, vous importez les packages de AWS services requis et exécutez la commande v2 directement dans le package en utilisant un modèle de rappel ou async/await.

Utilisation des commandes v3

La version 3 fournit un ensemble de commandes pour chaque package de AWS service afin de vous permettre d'effectuer des opérations pour ce AWS service. Après avoir installé un AWS service, vous pouvez parcourir les commandes disponibles dans le node-modules/@aws-sdk/client-PACKAGE_NAME/commands folder.

Vous devez importer les commandes que vous souhaitez utiliser. Par exemple, le code suivant charge le service DynamoDB et la commande. CreateTableCommand

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

Pour appeler ces commandes selon le modèle async/await recommandé, utilisez la syntaxe suivante.

CLIENT.send(new XXXCommand);

Par exemple, l'exemple suivant crée une table DynamoDB en utilisant le modèle async/await recommandé.

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

Utilisation des commandes v2

Pour utiliser les commandes v2 dans le SDK for JavaScript, vous devez importer les packages de AWS service complets, comme illustré dans le code suivant.

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

Pour appeler des commandes v2 selon le modèle async/await recommandé, utilisez la syntaxe suivante.

client.command(parameters);

L'exemple suivant utilise la createTable commande v2 pour créer une table DynamoDB en utilisant le modèle async/await recommandé.

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

L'exemple suivant utilise la createBucket commande v2 pour créer un compartiment Amazon S3 à l'aide du modèle de rappel.

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

Nouvelle pile d'intergiciels

La version 2 vous SDK a permis de modifier une demande au cours des différentes étapes de son cycle de vie en y attachant des écouteurs d'événements. Cette approche peut rendre difficile le débogage de ce qui s'est mal passé au cours du cycle de vie d'une demande.

Dans la version 3, vous pouvez utiliser une nouvelle pile intergicielle pour contrôler le cycle de vie d'un appel d'opération. Cette approche présente quelques avantages. Chaque étape de middleware de la pile appelle l'étape de middleware suivante après avoir apporté des modifications à l'objet de la requête. Cela facilite également le débogage des problèmes dans la pile, car vous pouvez voir exactement quelles étapes du middleware ont été appelées à l'origine de l'erreur.

L'exemple suivant ajoute un en-tête personnalisé à un client Amazon DynamoDB (que nous avons créé et présenté précédemment) à l'aide d'un intergiciel. Le premier argument est une fonction qui acceptenext, qui est la prochaine étape du middleware à appeler dans la pilecontext, et qui est un objet contenant des informations sur l'opération appelée. La fonction renvoie une fonction qui accepteargs, c'est-à-dire un objet contenant les paramètres transmis à l'opération et à la demande. Il renvoie le résultat de l'appel du prochain intergiciel avec. 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));