Migración de la versión 2.x a la 3.x del AWS SDK para JavaScript

La versión 3 de AWS SDK para JavaScript es una reescritura importante de la versión 2. En esta sección se describen las diferencias entre las dos versiones y se explica cómo migrar de la versión 2 a la versión 3 del SDK para JavaScript.

Migración del código a SDK para JavaScript v3 mediante codemod

AWS SDK for JavaScript versión 3 (v3) incluye interfaces modernizadas para las configuraciones y utilidades de los clientes, que incluyen credenciales, carga multiparte de Amazon S3, cliente de documentos DynamoDB, camareros y más. Puede encontrar los cambios en v2 y sus equivalentes en v3 en la Guía de migración del repositorio de GitHub de AWS SDK para JavaScript.

Para aprovechar al máximo el AWS SDK para JavaScript v3, recomendamos utilizar los scripts de codemod que se describen a continuación.

Uso de codemod para migrar código de v2 existente

La colección de scripts de codemod de aws-sdk-js-codemod le ayuda a migrar su aplicación (v2) existente de AWS SDK para JavaScript para utilizar las API v3. Puede ejecutar la transformación de la siguiente manera.

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

Por ejemplo, supongamos que tiene el siguiente código, que crea un cliente Amazon DynamoDB a partir de la versión 2 y llama a la operación 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);

Puede ejecutar nuestra transformación v2-to-v3 en example.ts de la siguiente manera.

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

La transformación convertirá la importación de DynamoDB a la versión 3, creará el cliente de la versión 3 y llamará a la operación listTables de la siguiente manera.

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

Hemos implementado transformaciones para casos de uso comunes. Si su código no se transforma correctamente, cree un informe de errores o una solicitud de función con un ejemplo de código de entrada y código de salida observado/esperado. Si su caso de uso específico ya está incluido en un problema existente, muestre su apoyo votando a favor.

¿Qué novedades incluye la versión 3?

La versión 3 del SDK para JavaScript (v3) contiene las siguientes características nuevas.

Además, el SDK está escrito en TypeScript, lo que tiene muchas ventajas, como la escritura estática.

Paquetes modularizados

La versión 2 del SDK para JavaScript (v2) requería que se utilizara todo el AWS SDK, de la siguiente manera.

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

Cargar todo el SDK no es un problema si la aplicación utiliza muchos servicios de AWS. Sin embargo, si solo necesita usar unos pocos servicios de AWS, tendrá que aumentar el tamaño de la aplicación con código que no necesite o no utilice.

En v3, puede cargar y usar solo los servicios de AWS individuales que necesite. Esto se muestra en el siguiente ejemplo, que le da acceso a Amazon DynamoDB (DynamoDB).

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

No solo puede cargar y usar servicios de AWS individuales, sino que también puede cargar y usar solo los comandos de servicio que necesite. Esto se muestra en los siguientes ejemplos, que proporcionan acceso al cliente de DynamoDB y al comando 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";

Comparación del tamaño del código

En la versión 2 (v2), un ejemplo de código sencillo que muestre todas sus tablas de Amazon DynamoDB de la región de us-west-2 podría tener el siguiente aspecto.

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 tiene el siguiente aspecto:

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

El paquete aws-sdk añade unos 40 MB a la aplicación. Sustituir var AWS = require("aws-sdk") por import {DynamoDB} from "@aws-sdk/client-dynamodb" reduce esa sobrecarga a unos 3 MB. Al restringir la importación únicamente al cliente y al comando ListTablesCommand de DynamoDB, se reduce la sobrecarga a menos de 100 KB.

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

Llamada a comandos en v3

Puede realizar operaciones en v3 mediante los comandos de v2 o v3. Para utilizar los comandos de v3, debe importar los comandos y los clientes del paquete de servicios de AWS necesarios y ejecutar el comando mediante el método .send que sigue el patrón async/await.

Para usar los comandos de v2, se importan los paquetes de servicios de AWS necesarios y se ejecuta el comando de v2 directamente en el paquete mediante un patrón de devolución de llamada o async/await.

Uso de comandos de v3

La v3 proporciona un conjunto de comandos para cada paquete de servicios de AWS que le permiten realizar operaciones para ese servicio de AWS. Después de instalar un servicio de AWS, puede explorar los comandos disponibles en el node-modules/@aws-sdk/client-PACKAGE_NAME/commands folder. de su proyecto.

Tiene que importar los comandos que desee utilizar. Por ejemplo, el código siguiente carga el servicio de DynamoDB y el comando CreateTableCommand.

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

Para llamar a estos comandos con el patrón async/await recomendado, utilice la sintaxis siguiente.

CLIENT.send(new XXXCommand);

Por ejemplo, en el ejemplo siguiente se crea una tabla de DynamoDB con el patrón async/await recomendado.

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

Uso de comandos de v2

Para usar los comandos de v2 en el SDK para JavaScript, debe importar los paquetes de servicios de AWS completos, como se muestra en el código siguiente.

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

Para llamar a los comandos de v2 con el patrón async/await recomendado, use la siguiente sintaxis.

client.command(parameters);

En el siguiente ejemplo, se utiliza el comando createTable de v2 para crear una tabla de DynamoDB con el patrón async/await recomendado.

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

En el ejemplo siguiente, se utiliza el comando createBucket de v2 para crear un bucket de Amazon S3 con el patrón de devolución de llamada.

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

Nueva pila de middleware

La v2 del SDK permitía modificar una solicitud a lo largo de las varias etapas de su ciclo de vida al asociar oyentes de eventos a la solicitud. Este enfoque puede dificultar la depuración de lo que salió mal durante el ciclo de vida de una solicitud.

En v3, puede usar una nueva pila de middleware para controlar el ciclo de vida de una llamada a una operación. Este enfoque ofrece un par de ventajas. Cada etapa de middleware de la pila llama a la siguiente etapa de middleware después de realizar cualquier cambio en el objeto de solicitud. Esto también facilita mucho la depuración de problemas en la pila, ya que permite ver exactamente a qué etapas del middleware se llamó antes de que se produjera el error.

En el siguiente ejemplo, se añade un encabezado personalizado a un cliente de Amazon DynamoDB (que hemos creado y mostrado anteriormente) mediante middleware. El primer argumento es una función que acepta next, que es la siguiente fase de middleware de la pila a la que se debe llamar, y context, que es un objeto que contiene información sobre la operación a la que se está llamando. La función devuelve una función que acepta args, que es un objeto que contiene los parámetros pasados a la operación y a la solicitud. Devuelve el resultado de llamar al siguiente middleware con 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));