Migrasi dari versi 2.x ke 3.x dari AWS SDK for JavaScript

AWS SDK for JavaScript Versi 3 adalah penulisan ulang utama versi 2. Bagian ini menjelaskan perbedaan antara dua versi dan menjelaskan cara bermigrasi dari versi 2 ke versi 3 SDK untuk JavaScript.

Migrasikan kode Anda ke SDK for JavaScript v3 menggunakan codemod

AWS SDK for JavaScript versi 3 (v3) dilengkapi dengan antarmuka modern untuk konfigurasi dan utilitas klien, yang mencakup kredensil, unggahan multipart Amazon S3, klien dokumen DynamoDB, pelayan, dan banyak lagi. Anda dapat menemukan apa yang berubah di v2 dan setara v3 untuk setiap perubahan dalam panduan migrasi di repo. AWS SDK for JavaScript GitHub

Untuk memanfaatkan sepenuhnya AWS SDK for JavaScript v3, kami sarankan menggunakan skrip codemod yang dijelaskan di bawah ini.

Gunakan codemod untuk memigrasikan kode v2 yang ada

Kumpulan skrip codemod di aws-sdk-js-codemodmembantu memigrasikan aplikasi AWS SDK for JavaScript (v2) Anda yang ada untuk menggunakan v3. APIs Anda dapat menjalankan transformasi sebagai berikut.

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

Misalnya, pertimbangkan Anda memiliki kode berikut, yang membuat klien Amazon DynamoDB dari v2 dan operasi panggilan. 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);

Anda dapat menjalankan v2-to-v3 transformasi kami example.ts sebagai berikut.

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

Transformasi akan mengonversi impor DynamoDB ke v3, membuat klien v3 dan memanggil operasi sebagai berikut. 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);

Kami telah menerapkan transformasi untuk kasus penggunaan umum. Jika kode Anda tidak berubah dengan benar, buat laporan bug atau permintaan fitur dengan contoh kode input dan kode keluaran yang diamati/diharapkan. Jika kasus penggunaan spesifik Anda sudah dilaporkan dalam masalah yang ada, tunjukkan dukungan Anda melalui upvote.

Apa yang baru di Versi 3

Versi 3 dari SDK for JavaScript (v3) berisi fitur-fitur baru berikut.

Selain itu, SDK tertulis TypeScript, yang memiliki banyak keunggulan, seperti mengetik statis.

Paket termodulasi

Versi 2 dari SDK for JavaScript (v2) mengharuskan Anda untuk menggunakan keseluruhan AWS SDK, sebagai berikut.

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

Memuat keseluruhan SDK tidak menjadi masalah jika aplikasi Anda menggunakan banyak AWS layanan. Namun, jika Anda hanya perlu menggunakan beberapa AWS layanan, itu berarti meningkatkan ukuran aplikasi Anda dengan kode yang tidak Anda perlukan atau gunakan.

Di v3, Anda hanya dapat memuat dan menggunakan AWS Layanan individual yang Anda butuhkan. Ini ditunjukkan dalam contoh berikut, yang memberi Anda akses ke Amazon DynamoDB (DynamoDB).

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

Anda tidak hanya dapat memuat dan menggunakan AWS layanan individual, tetapi Anda juga dapat memuat dan hanya menggunakan perintah layanan yang Anda butuhkan. Ini ditunjukkan dalam contoh berikut, yang memberi Anda akses ke klien DynamoDB dan perintah. 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";

Membandingkan ukuran kode

Di Versi 2 (v2), contoh kode sederhana yang mencantumkan semua tabel Amazon DynamoDB Anda di us-west-2 Wilayah mungkin terlihat seperti berikut.

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 terlihat seperti berikut ini.

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

aws-sdkPaket menambahkan sekitar 40 MB ke aplikasi Anda. Mengganti var AWS = require("aws-sdk") dengan import {DynamoDB} from "@aws-sdk/client-dynamodb" mengurangi overhead itu menjadi sekitar 3 MB. Membatasi impor hanya ke klien ListTablesCommand dan perintah DynamoDB mengurangi overhead menjadi kurang dari 100 KB.

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

Memanggil perintah di v3

Anda dapat melakukan operasi di v3 menggunakan perintah v2 atau v3. Untuk menggunakan perintah v3 Anda mengimpor perintah dan klien paket AWS Layanan yang diperlukan, dan menjalankan perintah menggunakan .send metode menggunakan pola async/await.

Untuk menggunakan perintah v2, Anda mengimpor paket AWS Layanan yang diperlukan, dan menjalankan perintah v2 secara langsung dalam paket menggunakan pola callback atau async/await.

Menggunakan perintah v3

v3 menyediakan serangkaian perintah untuk setiap paket AWS Layanan untuk memungkinkan Anda melakukan operasi untuk AWS Layanan tersebut. Setelah Anda menginstal AWS Layanan, Anda dapat menelusuri perintah yang tersedia di proyek Anda node-modules/@aws-sdk/client-PACKAGE_NAME/commands folder.

Anda harus mengimpor perintah yang ingin Anda gunakan. Misalnya, kode berikut memuat layanan DynamoDB, dan perintah. CreateTableCommand

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

Untuk memanggil perintah ini dalam pola async/await yang direkomendasikan, gunakan sintaks berikut.

CLIENT.send(new XXXCommand);

Misalnya, contoh berikut membuat tabel DynamoDB menggunakan pola async/await yang direkomendasikan.

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

Menggunakan perintah v2

Untuk menggunakan perintah v2 di SDK for JavaScript, Anda mengimpor paket AWS Layanan lengkap, seperti yang ditunjukkan dalam kode berikut.

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

Untuk memanggil perintah v2 dalam pola async/await yang disarankan, gunakan sintaks berikut.

client.command(parameters);

Contoh berikut menggunakan createTable perintah v2 untuk membuat tabel DynamoDB menggunakan pola async/await yang direkomendasikan.

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

Contoh berikut menggunakan createBucket perintah v2 untuk membuat bucket Amazon S3 menggunakan pola 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();

Tumpukan middleware baru

v2 SDK memungkinkan Anda untuk memodifikasi permintaan di seluruh beberapa tahap siklus hidupnya dengan melampirkan event listener ke permintaan. Pendekatan ini dapat mempersulit debug apa yang salah selama siklus hidup permintaan.

Di v3, Anda dapat menggunakan tumpukan middleware baru untuk mengontrol siklus hidup panggilan operasi. Pendekatan ini memberikan beberapa manfaat. Setiap tahap middleware dalam tumpukan memanggil tahap middleware berikutnya setelah membuat perubahan apa pun pada objek permintaan. Ini juga membuat masalah debugging di tumpukan jauh lebih mudah, karena Anda dapat melihat dengan tepat tahap middleware mana yang dipanggil menjelang kesalahan.

Contoh berikut menambahkan header kustom ke klien Amazon DynamoDB (yang kami buat dan tunjukkan sebelumnya) menggunakan middleware. Argumen pertama adalah fungsi yang menerimanext, yang merupakan tahap middleware berikutnya dalam tumpukan untuk memanggil, dancontext, yang merupakan objek yang berisi beberapa informasi tentang operasi yang dipanggil. Fungsi mengembalikan fungsi yang menerimaargs, yang merupakan objek yang berisi parameter yang diteruskan ke operasi dan permintaan. Ia mengembalikan hasil dari memanggil middleware berikutnya dengan. 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));