Migre da versão 2.x para a 3.x do AWS SDK for JavaScript

A AWS SDK for JavaScript versão 3 é uma grande reescrita da versão 2. A seção descreve as diferenças entre as duas versões e explica como migrar da versão 2 para a versão 3 do SDK for JavaScript.

Migre seu código SDK para a JavaScript v3 usando codemod

AWS SDK for JavaScript a versão 3 (v3) vem com interfaces modernizadas para configurações e utilitários de clientes, que incluem credenciais, upload de várias partes do Amazon S3, cliente de documentos do DynamoDB, garçons e muito mais. Você pode descobrir o que mudou na v2 e nos equivalentes da v3 para cada alteração no guia de migração no repositório. AWS SDK for JavaScript GitHub

Para aproveitar ao máximo a AWS SDK for JavaScript v3, recomendamos usar os scripts de codemod descritos abaixo.

Use o codemod para migrar o código v2 existente

A coleção de scripts de codemod aws-sdk-js-codemodajuda a migrar seu aplicativo existente AWS SDK for JavaScript (v2) para usar a v3. APIs Você pode executar a transformação da seguinte maneira.

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

Por exemplo, considere que você tem o código a seguir, que cria um cliente Amazon DynamoDB a partir da v2 e chama a operação 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);

Você pode executar a transformação v2-to-v3 em example.ts da seguinte maneira.

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

A transformação converterá a importação do DynamoDB em v3, criará o cliente v3 e chamará a operação listTables da seguinte forma.

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

Implementamos transformações para casos de uso comuns. Se seu código não for transformado corretamente, crie um relatório de bugs ou uma solicitação de atributo com exemplo de código de entrada e código de saída observado/esperado. Se seu caso de uso específico já foi relatado em um problema existente, mostre seu apoio por meio de um voto positivo.

Novidades da versão 3

A versão 3 do SDK for JavaScript (v3) contém os seguintes novos recursos.

Além disso, SDK é escrito em TypeScript, o que tem muitas vantagens, como digitação estática.

Pacotes modularizados

A versão 2 do SDK for JavaScript (v2) exigia que você usasse o todo AWS SDK, da seguinte maneira.

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

Carregar o SDK arquivo inteiro não é um problema se seu aplicativo estiver usando muitos AWS serviços. No entanto, se você precisar usar apenas alguns AWS serviços, isso significa aumentar o tamanho do seu aplicativo com código que você não precisa nem usa.

Na v3, você pode carregar e usar somente os AWS serviços individuais de que precisa. Isso é mostrado no exemplo a seguir, que fornece acesso ao Amazon DynamoDB (DynamoDB).

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

Você não só pode carregar e usar AWS serviços individuais, mas também pode carregar e usar somente os comandos de serviço necessários. Isso é mostrado nos exemplos a seguir, que fornecem acesso ao cliente do DynamoDB e ao 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";

Comparação de tamanho de código

Na versão 2 (v2), um exemplo de código simples que lista todas as suas tabelas do Amazon DynamoDB us-west-2 na região pode ter a seguinte aparência.

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

A v3 tem a seguinte aparência.

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

O pacote aws-sdk adiciona cerca de 40 MB ao seu aplicativo. Substituir var AWS = require("aws-sdk") por import {DynamoDB} from "@aws-sdk/client-dynamodb" reduz essa sobrecarga para cerca de 3 MB. Restringir a importação apenas ao cliente do DynamoDB e ao comando ListTablesCommand reduz a sobrecarga para 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({});

Chamando comandos na v3

Você pode realizar operações na v3 usando os comandos v2 ou v3. Para usar os comandos v3, você importa os comandos e os clientes do pacote de AWS serviços necessários e executa o comando usando o .send método usando o padrão async/await.

Para usar os comandos v2, você importa os pacotes de AWS serviços necessários e executa o comando v2 diretamente no pacote usando um padrão de retorno de chamada ou async/await.

Usando comandos v3

A v3 fornece um conjunto de comandos para cada pacote AWS de serviços para permitir que você execute operações para esse AWS serviço. Depois de instalar um Serviço da AWS , você pode navegar pelos comandos disponíveis na node-modules/@aws-sdk/client-PACKAGE_NAME/commands folder. de seu projeto.

Você deve importar os comandos que deseja usar. Por exemplo, o código a seguir carrega o serviço do DynamoDB e o comando CreateTableCommand.

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

Para chamar esses comandos no padrão async/await recomendado, use a seguinte sintaxe.

CLIENT.send(new XXXCommand);

O exemplo a seguir cria uma tabela do DynamoDB usando o padrão 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);
};

Usando comandos v2

Para usar os comandos v2 no SDK for JavaScript, você importa os pacotes de AWS serviços completos, conforme demonstrado no código a seguir.

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

Para chamar os comandos v2 no padrão async/await recomendado, use a sintaxe a seguir.

client.command(parameters);

O exemplo a seguir usa o createTable comando v2 para criar uma tabela do DynamoDB usando o padrão 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();

O exemplo a seguir usa o createBucket comando v2 para criar um bucket Amazon S3 usando o padrão de retorno de chamada.

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

Nova pilha de middleware

A v2 do SDK permitiu que você modificasse uma solicitação em vários estágios de seu ciclo de vida anexando ouvintes de eventos à solicitação. Essa abordagem pode dificultar a depuração do que deu errado durante o ciclo de vida de uma solicitação.

Na v3, você pode usar uma nova pilha de middleware para controlar o ciclo de vida de uma chamada de operação. Essa abordagem oferece alguns benefícios. Cada estágio de middleware na pilha chama o próximo estágio de middleware depois de fazer qualquer alteração no objeto de solicitação. Isso também facilita muito a depuração de problemas na pilha, porque você pode ver exatamente quais estágios de middleware foram chamados antes do erro.

O exemplo a seguir adiciona um cabeçalho personalizado a um cliente do Amazon DynamoDB (que criamos e mostramos anteriormente) usando middleware. O primeiro argumento é uma função que aceita next, que é o próximo estágio de middleware na pilha a ser chamada, e context, que é um objeto que contém algumas informações sobre a operação que está sendo chamada. A função retorna uma função que aceita args, que é um objeto que contém os parâmetros passados para a operação e a solicitação. Ela retorna o resultado da chamada do próximo middleware com 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));