La guía de API referencia de la versión AWS SDK for JavaScript 3 describe en detalle todas las API operaciones de la AWS SDK for JavaScript versión 3 (V3).
Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
Migre de la versión 2.x a la 3.x del AWS SDK for JavaScript
La AWS SDK for JavaScript versión 3 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 formularioSDK. JavaScript
Migre su código a la versión JavaScript 3 SDK de for mediante codemod
AWS SDK for JavaScript la 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. Encontrará los cambios en la versión 2 y los equivalentes de cada cambio en la versión 3 en la guía de migración del repositorio. AWS SDK for JavaScript GitHub
Para aprovechar al máximo las ventajas de la versión AWS SDK for JavaScript 3, te recomendamos que utilices los scripts de codemod que se describen a continuación.
Usa codemod para migrar el código de la versión 2 existente
La colección de scripts de codemod aws-sdk-js-codemod
$ 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
¿Qué novedades incluye la versión 3?
La versión 3 de SDK for JavaScript (v3) contiene las siguientes funciones nuevas.
- Paquetes modularizados
-
Los usuarios ahora pueden usar un paquete independiente para cada servicio.
- Nueva pila de middleware
-
Los usuarios ahora pueden usar una pila de middleware para controlar el ciclo de vida de una llamada a una operación.
Además, SDK está escrito TypeScript, lo que tiene muchas ventajas, como la escritura estática.
importante
Los ejemplos de código para la versión 3 de esta guía están escritos en ECMAScript 6 (ES6). ES6incorpora una nueva sintaxis y nuevas funciones para que su código sea más moderno y legible, y haga más. ES6requiere que utilice la versión 13.x o superior de Node.js. Para descargar e instalar la versión más reciente de Node.js, consulte Descargas de Node.js
Paquetes modularizados
La versión 2 del formulario SDK JavaScript (v2) requería que lo usara completo AWS SDK, de la siguiente manera.
var AWS = require("aws-sdk");
Cargarlo completo SDK no es un problema si la aplicación utiliza muchos AWS servicios. Sin embargo, si necesita usar solo unos pocos AWS servicios, significa aumentar el tamaño de la aplicación con un código que no necesita o no usa.
En la versión 3, puedes cargar y usar solo los AWS servicios individuales que necesites. 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 AWS servicios 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";
importante
No debe importar submódulos a módulos. Por ejemplo, el siguiente código podría dar lugar a errores.
import { CognitoIdentity } from "@aws-sdk/client-cognito-identity/CognitoIdentity";
El siguiente es el código correcto.
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 las tablas de Amazon DynamoDB de us-west-2
la región 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 versión 3 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({});
Comandos de llamada en la v3
Puede realizar operaciones en la versión 3 mediante los comandos de la versión 2 o la versión 3. Para utilizar los comandos de la versión 3, importe los comandos y los clientes del paquete de AWS servicios necesarios y ejecute el comando mediante el .send
método que utilice el patrón async/await.
Para utilizar los comandos de la versión 2, se importan los paquetes de AWS servicios necesarios y se ejecuta el comando de la versión 2 directamente en el paquete mediante un patrón de devolución de llamada o async/await.
Uso de los comandos de la versión 3
La versión 3 proporciona un conjunto de comandos para cada paquete de AWS servicios que le permiten realizar operaciones para ese AWS servicio. Después de instalar un servicio AWS, puede explorar los comandos disponibles en el node-modules/@aws-sdk/client-
de su proyecto. PACKAGE_NAME
/commands
folder.
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(newXXX
Command);
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 = { Table:
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 la versión 2
Para utilizar los comandos de la versión 2 en el SDK formulario JavaScript, se importan los paquetes de AWS servicio completos, como se muestra en el código siguiente.
const { DynamoDB } = require('@aws-sdk/client-dynamodb');
Para llamar a los comandos de la versión 2 con el patrón asíncrono/de espera recomendado, utilice la siguiente sintaxis.
client
.command
(parameters
);
En el siguiente ejemplo, se utiliza el createTable
comando 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 siguiente ejemplo, se utiliza el createBucket
comando v2 para crear un bucket de Amazon S3 mediante el patrón callback.
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 versión 2 le SDK permitía modificar una solicitud a lo largo de las múltiples etapas de su ciclo de vida al adjuntar detectores 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 la versión 3, puede utilizar 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));