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

Memprogram Amazon DynamoDB dengan JavaScript

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

Tentang AWS SDK untuk JavaScript

Men AWS SDK untuk JavaScript yediakan akses untuk Layanan AWS menggunakan skrip browser atau Node.js. Dokumentasi ini berfokus pada versi terbaru SDK (V3). V AWS SDK untuk JavaScript 3 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 mengandung perbedaan sintaks. V3 lebih modular, membuatnya lebih mudah untuk mengirimkan dependensi yang lebih kecil, dan memiliki TypeScript dukungan kelas satu. Sebaiknya gunakan SDK versi terbaru.

Menggunakan AWS SDK untuk JavaScript V3

Anda dapat menambahkan SDK ke Node.js aplikasi Anda menggunakan Node Package Manager. Contoh di bawah ini menunjukkan cara menambahkan paket SDK yang 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 kedua pendekatan ini, lihat bagian Pertimbangan.

Mengakses JavaScript dokumentasi

Mulailah dengan JavaScript dokumentasi dengan sumber daya berikut:

Lapisan abstraksi

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

Low-level klien (Dynam oDBClient)

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 JSON DynamoDB.

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

Contoh berikut menggunakan klien tingkat rendah dengan Item ditentukan 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();

High-level klien (DynamoDBDocumentClient)

Klien dokumen DynamoDB tingkat tinggi menawarkan fitur kenyamanan bawaan, seperti menghilangkan kebutuhan untuk menyusun data secara manual dan memungkinkan pembacaan dan penulisan 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 sedangkan PutItemCommand penggunaan tingkat tinggi. PutCommand Nama yang berbeda memungkinkan kedua set fungsi 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 penggunaannya konsisten saat Anda membaca item menggunakan operasi API sepertiGetItem,Query, atauScan.

Menggunakan fungsi utilitas Marshall

Anda dapat menggunakan klien tingkat rendah dan Marshall atau menghapus jenis data Anda sendiri. Paket utilitas, util-dynamodb, memiliki fungsi marshall() utilitas yang menerima JSON dan menghasilkan DynamoDB JSON, serta unmarshall() fungsi, yang melakukan sebaliknya. Contoh berikut menggunakan klien tingkat rendah dengan rangkaian data yang 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 operasi GetItem API. Mirip dengan PutItem perintah, Anda memiliki pilihan untuk menggunakan klien tingkat rendah atau klien Dokumen tingkat tinggi. Contoh di bawah ini menunjukkan penggunaan 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 dievaluasi menjadi true agar penulisan dapat dilanjutkan. Jika kondisi tidak dievaluasi menjadi true, operasi tulis menghasilkan pengecualian. Ekspresi kondisi dapat memeriksa apakah item sudah ada atau jika 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 Men angani kesalahan penulisan bersyarat dalam skenario konkurensi tinggi dengan Amazon Dynam oDB.

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 JavaScript SDK V3 dan di bawah DynamoDB-SDK-Examples GitHub repositori.

Paginasi

Baca permintaan 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, respons parSIAL akan dikirim, dan Anda harus membuat paginate untuk mengambil item tambahan.

Sistem hanya akan membaca maksimal 1 megabyte data per permintaan. Jika Anda menyertakan Filter ekspresi, sistem masih akan membaca maksimum satu megabyte 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 dicatat 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 kenyamanan PaginateScan

SDK menyediakan metode kenyamanan yang disebut paginateScan dan paginateQuery yang melakukan ini 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 untuk terhubung jika belum diketahui konteks panggilan atau URL titik akhir yang akan digunakan. Ini berguna jika Anda ingin menargetkan instance DynamoDB Lokal untuk tujuan pengembangan.

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

Konfigurasi untuk batas waktu

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

Men requestTimeout definisikan 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 gagal dan klien dapat memulai permintaan baru. Misalnya, 10 detik:

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

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

const client = new DynamoDBClient({
  requestHandler
});

Selain mengonfigurasi nilai batas waktu, Anda dapat mengatur jumlah maksimum soket, yang memungkinkan peningkatan jumlah koneksi bersamaan per asal. Panduan pengembang mencakup detail tentang mengonfigurasi maxSockets parameter. Pertimbangkan untuk meningkatkan ini ketika konkurensi aplikasi Anda (jumlah permintaan simultan dalam penerbangan) secara teratur mendekati atau melebihi 50.

Konfigurasi untuk keep-alive

Saat menggunakan HTTPS, permintaan pertama selalu membutuhkan komunikasi bolak-balik untuk membangun 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 JavaScript V3.

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.

Konfigurasi untuk percobaan ulang

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

SDK untuk JavaScript V3 akan membuat 3 permintaan total, secara default, sebelum menyerah dan meneruskan kesalahan ke 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 meningkatkan nilai dari default 3 menjadi total 5. Jika Anda mengaturnya ke 0 atau 1, itu menunjukkan Anda tidak ingin percobaan ulang otomatis dan ingin menangani sendiri kesalahan yang dapat dilanjutkan dalam blok tangkapan Anda.

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

Anda juga dapat mengontrol waktu percobaan ulang dengan strategi coba ulang khusus. Untuk melakukan ini, impor paket util-retry utilitas dan buat fungsi backoff khusus yang menghitung waktu tunggu antara percobaan ulang berdasarkan jumlah percobaan ulang 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 khusus, calculateRetryBackoff, menghitung penundaan dengan menerima nomor percobaan coba lagi (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.
  ),
});

Untuk informasi tentang perubahan mendatang pada perilaku coba ulang default di semua AWS SDK, lihat Mengumumkan perilaku coba ulang yang diperbarui untuk AWS SDK dan Alat di Blog Alat Pengembang. AWS Untuk detail yang tepat untuk JavaScript v3, lihat pembaruan perilaku coba ulang JavaScript v3 (masalah #8037) di situs GitHub web.

Pelayan

Klien DynamoDB menyertakan dua fungsi pelayan berguna yang dapat digunakan saat membuat, memodifikasi, atau menghapus tabel ketika Anda ingin kode Anda menunggu untuk melanjutkan hingga modifikasi tabel selesai. Misalnya, Anda dapat menerapkan tabel, memanggil waitUntilTableExists fungsi, dan kode akan diblokir sampai tabel dibuat AKTIF. Pelayan secara internal mensurvei layanan DynamoDB describe-table setiap 20 detik.

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 AKTIF. 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 muncul setelah semua percobaan ulang habis. Jika kesalahan dicoba ulang dan akhirnya diikuti oleh panggilan yang berhasil, dari perspektif kode, tidak ada kesalahan hanya latensi yang sedikit meningkat. Percobaan ulang akan muncul di CloudWatch grafik Amazon sebagai permintaan yang tidak berhasil, seperti permintaan throttle atau error. Jika klien mencapai jumlah percobaan ulang maksimum, ia akan menyerah dan menghasilkan pengecualian. Ini adalah cara klien untuk mengatakan bahwa 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 untuk string kesalahan umum di Panduan Pengembang DynamoDB. Kesalahan pasti yang mungkin terjadi dengan panggilan API tertentu dapat ditemukan di dokumentasi untuk panggilan API tersebut, seperti dokumen API Kueri.

Metadata kesalahan mencakup properti tambahan, tergantung pada kesalahan. 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 sendiri, Anda harus membedakan antara throttle dan error:

Pencatatan log

Aktifkan logging untuk mendapatkan detail selengkapnya tentang apa yang dilakukan SDK. Anda dapat mengatur parameter seperti yang ditunjukkan pada contoh di bawah ini. DynamoDBClient 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 mencatat saat itu 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",
  }
);

Ini MiddlewareStack menyediakan kait yang kuat untuk mengamati dan mengendalikan perilaku SDK. Lihat blog Memperkenalkan Middleware Stack in Modular AWS SDK untuk JavaScript, untuk informasi lebih lanjut.

Pertimbangan-pertimbangan

Saat mengimplementas AWS SDK untuk JavaScript ikannya dalam proyek Anda, berikut adalah beberapa faktor lebih lanjut untuk dipertimbangkan.