Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Pemrograman Amazon DynamoDB dengan JavaScript

Panduan ini memberikan orientasi kepada programmer yang ingin menggunakan Amazon DynamoDB dengan. JavaScript Pelajari tentang AWS SDK for JavaScript, lapisan abstraksi yang tersedia, mengonfigurasi koneksi, menangani kesalahan, menentukan kebijakan coba lagi, mengelola keep-alive, dan banyak lagi.

Tentang AWS SDK for JavaScript

AWS SDK for JavaScript Ini menyediakan akses untuk Layanan AWS menggunakan skrip browser atau Node.js. Dokumentasi ini berfokus pada versi terbaru SDK (V3). AWS SDK for JavaScript V3 dikelola oleh AWS sebagai proyek sumber terbuka yang dihosting di. GitHub Masalah dan permintaan fitur bersifat publik dan Anda dapat mengaksesnya di halaman masalah untuk GitHub repositori.

JavaScript V2 mirip dengan V3, tetapi berisi perbedaan sintaks. V3 lebih modular, membuatnya lebih mudah untuk mengirimkan dependensi yang lebih kecil, dan memiliki dukungan kelas satu. TypeScript Sebaiknya gunakan SDK versi terbaru.

Menggunakan AWS SDK for JavaScript V3

Anda dapat menambahkan SDK ke aplikasi Node.js Anda menggunakan Node Package Manager. Contoh di bawah ini menunjukkan cara menambahkan paket SDK paling umum untuk bekerja dengan DynamoDB.

Menginstal paket menambahkan referensi ke bagian ketergantungan file proyek package.json Anda. Anda memiliki opsi untuk menggunakan sintaks modul ECMAScript yang lebih baru. Untuk detail lebih lanjut tentang dua pendekatan ini, lihat bagian Pertimbangan.

Mengakses dokumentasi JavaScript

Mulailah dengan JavaScript dokumentasi dengan sumber daya berikut:

Lapisan abstraksi

SDK untuk JavaScript V3 memiliki klien tingkat rendah (DynamoDBClient) dan klien tingkat tinggi (). DynamoDBDocumentClient

Klien tingkat rendah () DynamoDBClient

Klien tingkat rendah tidak memberikan abstraksi tambahan atas protokol kawat yang mendasarinya. Ini memberi Anda kontrol penuh atas semua aspek komunikasi, tetapi karena tidak ada abstraksi, Anda harus melakukan hal-hal seperti memberikan definisi item menggunakan format DynamoDB JSON.

Seperti contoh di bawah ini menunjukkan, dengan format ini tipe data harus dinyatakan secara eksplisit. S menunjukkan nilai string dan N menunjukkan nilai angka. Angka pada kawat selalu dikirim sebagai string yang ditandai sebagai jenis angka untuk memastikan tidak ada kehilangan presisi. Panggilan API tingkat rendah memiliki pola penamaan seperti PutItemCommand danGetItemCommand.

Contoh berikut adalah menggunakan klien tingkat rendah dengan Item didefinisikan menggunakan DynamoDB JSON:

const { DynamoDBClient, PutItemCommand } = require("@aws-sdk/client-dynamodb");

const client = new DynamoDBClient({});

async function addProduct() {
  const params = {
    TableName: "products",
    Item: {
      "id": { S: "Product01" },
      "description": { S: "Hiking Boots" },
      "category": { S: "footwear" },
      "sku": { S: "hiking-sku-01" },
      "size": { N: "9" }
    }
  };

  try {
    const data = await client.send(new PutItemCommand(params));
    console.log('result : ' + JSON.stringify(data));
  } catch (error) {
    console.error("Error:", error);
  }
}
addProduct();

Klien tingkat tinggi () DynamoDBDocumentClient

Klien dokumen DynamoDB tingkat tinggi menawarkan fitur kenyamanan bawaan, seperti menghilangkan kebutuhan untuk mengumpulkan data secara manual dan memungkinkan untuk membaca dan menulis langsung menggunakan objek standar. JavaScript Dokumentasi untuk lib-dynamodb menyediakan daftar keuntungan.

Untuk membuat instanceDynamoDBDocumentClient, buat level rendah DynamoDBClient dan kemudian bungkus dengan a. DynamoDBDocumentClient Konvensi penamaan fungsi sedikit berbeda antara kedua paket. Misalnya, penggunaan tingkat rendah PutItemCommand sementara penggunaan tingkat tinggi. PutCommand Nama yang berbeda memungkinkan kedua set fungsi untuk hidup berdampingan dalam konteks yang sama, memungkinkan Anda untuk mencampur keduanya dalam skrip yang sama.

const { DynamoDBClient } = require("@aws-sdk/client-dynamodb");
const { DynamoDBDocumentClient, PutCommand } = require("@aws-sdk/lib-dynamodb");

const client = new DynamoDBClient({});

const docClient = DynamoDBDocumentClient.from(client);

async function addProduct() {
  const params = {
    TableName: "products",
    Item: {
      id: "Product01",
      description: "Hiking Boots",
      category: "footwear",
      sku: "hiking-sku-01",
      size: 9,
    },
  };

  try {
    const data = await docClient.send(new PutCommand(params));
    console.log('result : ' + JSON.stringify(data));
  } catch (error) {
    console.error("Error:", error);
  }
}

addProduct();

Pola penggunaan konsisten saat Anda membaca item menggunakan operasi API sepertiGetItem,Query, atauScan.

Menggunakan fungsi utilitas marshall

Anda dapat menggunakan klien tingkat rendah dan marshall atau unmarshall tipe data Anda sendiri. Paket utilitas, util-dynamodb, memiliki fungsi marshall() utilitas yang menerima JSON dan menghasilkan DynamoDB JSON, serta fungsi, yang melakukan sebaliknya. unmarshall() Contoh berikut menggunakan klien tingkat rendah dengan data marshalling ditangani oleh panggilan. marshall()

const { DynamoDBClient, PutItemCommand } = require("@aws-sdk/client-dynamodb");
const { marshall } = require("@aws-sdk/util-dynamodb");

const client = new DynamoDBClient({});

async function addProduct() {
  const params = {
    TableName: "products",
    Item: marshall({
      id: "Product01",
      description: "Hiking Boots",
      category: "footwear",
      sku: "hiking-sku-01",
      size: 9,
    }),
  };

  try {
    const data = await client.send(new PutItemCommand(params));
  } catch (error) {
    console.error("Error:", error);
  }
}
addProduct();

Membaca item

Untuk membaca satu item dari DynamoDB, Anda menggunakan GetItem operasi API. Mirip dengan PutItem perintah, Anda memiliki pilihan untuk menggunakan klien tingkat rendah atau klien Dokumen tingkat tinggi. Contoh di bawah ini menunjukkan menggunakan klien Dokumen tingkat tinggi untuk mengambil item.

const { DynamoDBClient } = require("@aws-sdk/client-dynamodb");
const { DynamoDBDocumentClient, GetCommand } = require("@aws-sdk/lib-dynamodb");

const client = new DynamoDBClient({});

const docClient = DynamoDBDocumentClient.from(client);

async function getProduct() {
  const params = {
    TableName: "products",
    Key: {
      id: "Product01",
    },
  };

  try {
    const data = await docClient.send(new GetCommand(params));
    console.log('result : ' + JSON.stringify(data));
  } catch (error) {
    console.error("Error:", error);
  }
}

getProduct();

Gunakan operasi Query API untuk membaca beberapa item. Anda dapat menggunakan klien tingkat rendah atau klien Dokumen. Contoh di bawah ini menggunakan klien Dokumen tingkat tinggi.

const { DynamoDBClient } = require("@aws-sdk/client-dynamodb");
const {
  DynamoDBDocumentClient,
  QueryCommand,
} = require("@aws-sdk/lib-dynamodb");

const client = new DynamoDBClient({});

const docClient = DynamoDBDocumentClient.from(client);

async function productSearch() {
  const params = {
    TableName: "products",
    IndexName: "GSI1",
    KeyConditionExpression: "#category = :category and begins_with(#sku, :sku)",
    ExpressionAttributeNames: {
      "#category": "category",
      "#sku": "sku",
    },
    ExpressionAttributeValues: {
      ":category": "footwear",
      ":sku": "hiking",
    },
  };

  try {
    const data = await docClient.send(new QueryCommand(params));
    console.log('result : ' + JSON.stringify(data));
  } catch (error) {
    console.error("Error:", error);
  }
}

productSearch();

Penulisan bersyarat

Operasi penulisan DynamoDB dapat menentukan ekspresi kondisi logis yang harus mengevaluasi ke true agar penulisan dapat dilanjutkan. Jika kondisi tidak mengevaluasi ke true, operasi tulis menghasilkan pengecualian. Ekspresi kondisi dapat memeriksa apakah item sudah ada atau apakah atributnya cocok dengan batasan tertentu.

ConditionExpression = "version = :ver AND size(VideoClip) < :maxsize"

Ketika ekspresi kondisional gagal, Anda dapat menggunakan ReturnValuesOnConditionCheckFailure untuk meminta agar respons kesalahan menyertakan item yang tidak memenuhi kondisi untuk menyimpulkan apa masalahnya. Untuk detail selengkapnya, lihat Menangani kesalahan penulisan bersyarat dalam skenario konkurensi tinggi dengan Amazon DynamoDB.

try {
      const response = await client.send(new PutCommand({
          TableName: "YourTableName",
          Item: item,
          ConditionExpression: "attribute_not_exists(pk)",
          ReturnValuesOnConditionCheckFailure: "ALL_OLD"
      }));
  } catch (e) {
      if (e.name === 'ConditionalCheckFailedException') {
          console.log('Item already exists:', e.Item);
      } else {
          throw e;
      }
  }

Contoh kode tambahan yang menunjukkan aspek lain dari penggunaan JavsScript SDK V3 tersedia di Dokumentasi SDK V3 dan di bawah repositori JavaScript DynamoDB-SDK-Examples. GitHub

Paginasi

Permintaan baca seperti Scan atau kemungkinan Query akan mengembalikan beberapa item dalam kumpulan data. Jika Anda melakukan Scan atau Query dengan Limit parameter, maka setelah sistem membaca banyak item, sebagian respons akan dikirim, dan Anda harus membuat paginasi untuk mengambil item tambahan.

Sistem hanya akan membaca maksimal 1 megabyte data per permintaan. Jika Anda menyertakan Filter ekspresi, sistem akan tetap membaca megabyte, maksimum, data dari disk, tetapi akan mengembalikan item megabyte yang cocok dengan filter. Operasi filter dapat mengembalikan 0 item untuk halaman, tetapi masih memerlukan pagination lebih lanjut sebelum pencarian habis.

Anda harus mencari LastEvaluatedKey dalam respons dan menggunakannya sebagai ExclusiveStartKey parameter dalam permintaan berikutnya untuk melanjutkan pengambilan data. Ini berfungsi sebagai bookmark seperti yang tercantum dalam contoh berikut.

Contoh menggunakanLastEvaluatedKey:

const { DynamoDBClient, ScanCommand } = require("@aws-sdk/client-dynamodb");

const client = new DynamoDBClient({});

async function paginatedScan() {
  let lastEvaluatedKey;
  let pageCount = 0;

  do {
    const params = {
      TableName: "products",
      ExclusiveStartKey: lastEvaluatedKey,
    };

    const response = await client.send(new ScanCommand(params));
    pageCount++;
    console.log(`Page ${pageCount}, Items:`, response.Items);
    lastEvaluatedKey = response.LastEvaluatedKey;
  } while (lastEvaluatedKey);
}

paginatedScan().catch((err) => {
  console.error(err);
});

Menggunakan metode paginateScan kenyamanan

SDK menyediakan metode kenyamanan yang dipanggil paginateScan dan paginateQuery yang melakukan ini bekerja untuk Anda dan membuat permintaan berulang di belakang layar. Tentukan jumlah maksimum item yang akan dibaca per permintaan menggunakan Limit parameter standar.

const { DynamoDBClient, paginateScan } = require("@aws-sdk/client-dynamodb");

const client = new DynamoDBClient({});

async function paginatedScanUsingPaginator() {
  const params = {
    TableName: "products",
    Limit: 100
  };

  const paginator = paginateScan({client}, params);

  let pageCount = 0;

  for await (const page of paginator) {
    pageCount++;
    console.log(`Page ${pageCount}, Items:`, page.Items);
  }
}

paginatedScanUsingPaginator().catch((err) => {
  console.error(err);
});

Menentukan konfigurasi

Saat mengaturDynamoDBClient, Anda dapat menentukan berbagai penggantian konfigurasi dengan meneruskan objek konfigurasi ke konstruktor. Misalnya, Anda dapat menentukan Wilayah yang akan disambungkan jika belum diketahui konteks panggilan atau URL titik akhir yang akan digunakan. Ini berguna jika Anda ingin menargetkan instance DynamoDB Local untuk tujuan pengembangan.

const client = new DynamoDBClient({
  region: "eu-west-1",
  endpoint: "http://localhost:8000",
});

Config untuk batas waktu

DynamoDB menggunakan HTTPS untuk komunikasi client-server. Anda dapat mengontrol beberapa aspek dari lapisan HTTP dengan menyediakan NodeHttpHandler objek. Misalnya, Anda dapat menyesuaikan nilai batas waktu kunci connectionTimeout danrequestTimeout. connectionTimeoutIni adalah durasi maksimum, dalam milidetik, bahwa klien akan menunggu sambil mencoba membuat koneksi sebelum menyerah.

Ini requestTimeout menentukan berapa lama klien akan menunggu respons setelah permintaan dikirim, juga dalam milidetik. Default untuk keduanya adalah nol, artinya batas waktu dinonaktifkan dan tidak ada batasan berapa lama klien akan menunggu jika respons tidak tiba. Anda harus mengatur batas waktu ke sesuatu yang masuk akal sehingga jika terjadi masalah jaringan, permintaan akan error dan permintaan baru dapat dimulai. Sebagai contoh:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { NodeHttpHandler } from "@smithy/node-http-handler";

const requestHandler = new NodeHttpHandler({
  connectionTimeout: 2000,
  requestTimeout: 2000,
});

const client = new DynamoDBClient({
  requestHandler
});

Selain mengonfigurasi nilai batas waktu, Anda dapat mengatur jumlah soket maksimum, yang memungkinkan peningkatan jumlah koneksi bersamaan per asal. Panduan pengembang mencakup detail tentang mengonfigurasi maxSockets parameter.

Config untuk keep-alive

Saat menggunakan HTTPS, permintaan pertama selalu membutuhkan back-and-forth komunikasi untuk membuat koneksi yang aman. HTTP Keep-Alive memungkinkan permintaan berikutnya untuk menggunakan kembali koneksi yang sudah dibuat, membuat permintaan lebih efisien dan menurunkan latensi. HTTP Keep-Alive diaktifkan secara default dengan V3. JavaScript

Ada batasan berapa lama koneksi idle dapat tetap hidup. Pertimbangkan untuk mengirim permintaan berkala, mungkin setiap menit, jika Anda memiliki koneksi idle tetapi ingin permintaan berikutnya menggunakan koneksi yang sudah dibuat.

Config untuk percobaan ulang

Ketika SDK menerima respons kesalahan dan kesalahan dapat dilanjutkan seperti yang ditentukan oleh SDK, seperti pengecualian pelambatan atau pengecualian layanan sementara, SDK akan mencoba lagi. Ini terjadi tanpa terlihat bagi Anda sebagai penelepon, kecuali bahwa Anda mungkin memperhatikan permintaan membutuhkan waktu lebih lama untuk berhasil.

SDK untuk JavaScript V3 akan membuat 3 permintaan total, secara default, sebelum menyerah dan meneruskan kesalahan ke dalam konteks panggilan. Anda dapat menyesuaikan jumlah dan frekuensi percobaan ulang ini.

DynamoDBClientKonstruktor menerima maxAttempts pengaturan yang membatasi berapa banyak upaya yang akan terjadi. Contoh di bawah ini menaikkan nilai dari default 3 menjadi total 5. Jika Anda menyetelnya ke 0 atau 1, itu menunjukkan Anda tidak ingin mencoba ulang otomatis dan ingin menangani kesalahan yang dapat dilanjutkan sendiri dalam blok catch Anda.

const client = new DynamoDBClient({
  maxAttempts: 5,
});

Anda juga dapat mengontrol waktu percobaan ulang dengan strategi coba lagi khusus. Untuk melakukan ini, impor paket util-retry utilitas dan buat fungsi backoff khusus yang menghitung waktu tunggu antara percobaan ulang berdasarkan jumlah coba lagi saat ini.

Contoh di bawah ini mengatakan untuk melakukan maksimal 5 upaya dengan penundaan 15, 30, 90, dan 360 milidetik jika upaya pertama gagal. Fungsi backoff kustom, calculateRetryBackoff, menghitung penundaan dengan menerima nomor percobaan ulang (dimulai dengan 1 untuk percobaan ulang pertama) dan mengembalikan berapa milidetik untuk menunggu permintaan itu.

const { ConfiguredRetryStrategy } = require("@aws-sdk/util-retry");

const calculateRetryBackoff = (attempt) => {
  const backoffTimes = [15, 30, 90, 360];
  return backoffTimes[attempt - 1] || 0;
};

const client = new DynamoDBClient({
  retryStrategy: new ConfiguredRetryStrategy(
    5, // max attempts.
    calculateRetryBackoff // backoff function.
  ),
});

Pelayan

Klien DynamoDB mencakup dua fungsi pelayan berguna yang dapat digunakan saat membuat, memodifikasi, atau menghapus tabel saat Anda ingin kode Anda menunggu untuk melanjutkan hingga modifikasi tabel selesai. Misalnya, Anda dapat menyebarkan tabel, memanggil waitUntilTableExists fungsi, dan kode akan memblokir sampai tabel telah dibuat AKTIF. Pelayan secara internal melakukan polling layanan DynamoDB dengan setiap 20 detik. describe-table

import {waitUntilTableExists, waitUntilTableNotExists} from "@aws-sdk/client-dynamodb";

… <create table details>

const results = await waitUntilTableExists({client: client, maxWaitTime: 180}, {TableName: "products"});
if (results.state == 'SUCCESS') {
  return results.reason.Table
}
console.error(`${results.state} ${results.reason}`);

waitUntilTableExistsFitur mengembalikan kontrol hanya ketika dapat melakukan describe-table perintah yang menunjukkan status tabel ACTIVE. Ini memastikan bahwa Anda dapat menggunakan waitUntilTableExists untuk menunggu penyelesaian pembuatan, serta modifikasi seperti menambahkan indeks GSI, yang mungkin memerlukan beberapa waktu untuk diterapkan sebelum tabel kembali ke status AKTIF.

Penanganan kesalahan

Dalam contoh awal di sini, kami telah menangkap semua kesalahan secara luas. Namun, dalam aplikasi praktis, penting untuk membedakan antara berbagai jenis kesalahan dan menerapkan penanganan kesalahan yang lebih tepat.

Respons kesalahan DynamoDB berisi metadata, termasuk nama kesalahan. Anda dapat menangkap kesalahan kemudian mencocokkan dengan kemungkinan nama string dari kondisi kesalahan untuk menentukan cara melanjutkan. Untuk kesalahan sisi server, Anda dapat memanfaatkan instanceof operator dengan jenis kesalahan yang diekspor oleh @aws-sdk/client-dynamodb paket untuk mengelola penanganan kesalahan secara efisien.

Penting untuk dicatat bahwa kesalahan ini hanya terwujud setelah semua percobaan ulang telah habis. Jika kesalahan dicoba lagi dan akhirnya diikuti oleh panggilan yang berhasil, dari perspektif kode, tidak ada kesalahan hanya latensi yang sedikit meningkat. Percobaan ulang akan muncul di CloudWatch bagan Amazon sebagai permintaan yang tidak berhasil, seperti permintaan throttle atau error. Jika klien mencapai jumlah percobaan ulang maksimum, itu akan menyerah dan menghasilkan pengecualian. Ini adalah cara klien mengatakan itu tidak akan mencoba lagi.

Di bawah ini adalah cuplikan untuk menangkap kesalahan dan mengambil tindakan berdasarkan jenis kesalahan yang dikembalikan.

import {
  ResourceNotFoundException
  ProvisionedThroughputExceededException,
  DynamoDBServiceException,
} from "@aws-sdk/client-dynamodb";

try {
  await client.send(someCommand);
} catch (e) {
    if (e instanceof ResourceNotFoundException) {
      // Handle ResourceNotFoundException
    } else if (e instanceof ProvisionedThroughputExceededException) {
      // Handle ProvisionedThroughputExceededException
    } else if (e instanceof DynamoDBServiceException) {
      // Handle DynamoDBServiceException
    } else {
      // Other errors such as those from the SDK
      if (e.name === "TimeoutError") {
        // Handle SDK TimeoutError.
      } else {
        // Handle other errors.
      }
    }
}

Lihat Penanganan kesalahan dengan DynamoDB string kesalahan umum di DynamoDB Developer Guide. Kesalahan persis yang mungkin terjadi dengan panggilan API tertentu dapat ditemukan dalam dokumentasi untuk panggilan API tersebut, seperti dokumen Query API.

Metadata kesalahan mencakup properti tambahan, tergantung pada kesalahannya. Untuk a TimeoutError, metadata mencakup jumlah upaya yang dilakukan dantotalRetryDelay, seperti yang ditunjukkan di bawah ini.

{
  "name": "TimeoutError",
  "$metadata": {
    "attempts": 3,
    "totalRetryDelay": 199
  }
}

Jika Anda mengelola kebijakan coba ulang Anda sendiri, Anda akan ingin membedakan antara throttle dan error:

Pencatatan log

Aktifkan logging untuk mendapatkan detail lebih lanjut tentang apa yang dilakukan SDK. Anda dapat mengatur parameter pada DynamoDBClient seperti yang ditunjukkan pada contoh di bawah ini. Informasi log lainnya akan muncul di konsol dan menyertakan metadata seperti kode status dan kapasitas yang dikonsumsi. Jika Anda menjalankan kode secara lokal di jendela terminal, log muncul di sana. Jika Anda menjalankan kode di AWS Lambda, dan Anda memiliki CloudWatch log Amazon yang disiapkan, maka output konsol akan ditulis di sana.

const client = new DynamoDBClient({
  logger: console
});

Anda juga dapat menghubungkan ke aktivitas SDK internal dan melakukan pencatatan khusus saat peristiwa tertentu terjadi. Contoh di bawah ini menggunakan klien middlewareStack untuk mencegat setiap permintaan saat dikirim dari SDK dan mencatatnya saat terjadi.

const client = new DynamoDBClient({});

client.middlewareStack.add(
  (next) => async (args) => {
    console.log("Sending request from AWS SDK", { request: args.request });
    return next(args);
  },
  {
    step: "build",
    name: "log-ddb-calls",
  }
);

MiddlewareStackIni menyediakan pengait yang kuat untuk mengamati dan mengendalikan perilaku SDK. Lihat blog Memperkenalkan Middleware Stack in Modular AWS SDK for JavaScript, untuk informasi lebih lanjut.

Pertimbangan

Saat menerapkan AWS SDK for JavaScript dalam proyek Anda, berikut adalah beberapa faktor lebih lanjut yang perlu dipertimbangkan.