使用 Amazon DynamoDB 進行編程 JavaScript

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

本指南為想要使用 Amazon DynamoDB 的程式設計人員提供了一個方向。 JavaScript瞭解可用的抽象層 AWS SDK for JavaScript、設定連線、處理錯誤、定義重試原則、管理保持活動狀態等。

關於 AWS SDK for JavaScript

可讓您存取使 AWS 服務 用瀏覽器指令碼或 Node.js。 AWS SDK for JavaScript 本文件著重於 SDK (V3) 的最新版本。 AWS SDK for JavaScript V3 作 AWS 為託管的開源項目進行維護 GitHub。問題和功能請求是公開的，您可以在存放庫的問題頁面上 GitHub 存取它們。

JavaScript V2 類似於 V3，但包含語法差異。V3 更加模塊化，可以更輕鬆地提供較小的依賴關係，並具有一流的 TypeScript 支持。我們建議使用最新版本的 SDK。

使用 AWS SDK for JavaScript V3

您可以使用節點 Package 管理員將 SDK 新增至 Node.js 應用程式。下列範例說明如何新增最常用的 SDK 套件，以便與 DynamoDB 搭配使用。

安裝套件會將參考新增至 package.json 專案檔案的相依性區段。您可以選擇使用較新的 ECMAScript 模塊語法。如需這兩種方法的詳細資訊，請參閱 ＜ 考量 ＞ 一節。

存取 JavaScript文件

使用下列資源開始使用 JavaScript 文件：

抽象層

JavaScript V3 的 SDK 具有低級客戶端（DynamoDBClient）和高級客戶端（DynamoDBDocumentClient）。

低階用戶端 () DynamoDBClient

低級客戶端在基礎有線協議上不提供額外的抽象。它可讓您完全控制通訊的所有層面，但由於沒有抽象化，因此您必須執行諸如使用 DynamoDB JSON 格式提供項目定義之類的操作。

如下面的例子所示，用這種格式的數據類型必須明確說明。S 表示字串值，N 表示數值。配線上的號碼永遠做為標記為數字類型的字串傳送，以確保不會損失精確度。低階 API 呼叫具有命名模式，例如PutItemCommand和GetItemCommand。

下列範例是使用使用 DynamoDB JSON Item 定義的低階用戶端：

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

高階用戶端 (DynamoDBDocumentClient)

高階 DynamoDB 文件用戶端提供內建的便利功能，例如無需手動封送資料，並允許使用標準物件直接讀取和寫入。 JavaScript 的文件提lib-dynamodb供優點清單。

要實例化DynamoDBDocumentClient，構建一個低級別，DynamoDBClient然後用. DynamoDBDocumentClient 這兩個套件之間的函數命名慣例略有不同。例如，低級別的使用，PutItemCommand而高級使用PutCommand。不同的名稱允許兩組函數在相同的上下文中共存，允許您在同一個腳本中混合兩個函數。

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

當您使用 API 操作（例如、或）讀取項目時GetItem，Query使用模式是一致的Scan。

使用馬歇爾實用程序函數

您可以使用低級客戶端和馬歇爾或解開自己的數據類型。公用程式套件公用程式 Dynamodb 具有接受 JSON 並產生 DynamoDB JSON 的marshall()公用程式函數，以及可反向執行相反作業的unmarshall()函數。下列範例會使用具有呼叫所處理之資料封送的低階用戶端。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();

讀取項目

若要從 DynamoDB 讀取單一項目，請使用 GetItem API 作業。與PutItem命令類似，您可以選擇使用低階用戶端或高階 Document 用戶端。下面的例子演示了如何使用高級文檔客戶端檢索項目。

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

使用 Query API 作業讀取多個項目。您可以使用低階用戶端或文件用戶端。以下範例使用高階文件用戶端。

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

條件式寫入

DynamoDB 寫入作業可以指定邏輯條件運算式，必須評估為 true 才能繼續寫入。如果條件未評估為 true，寫入作業會產生例外狀況。條件運算式可以檢查項目是否已存在，或其屬性是否符合某些限制。

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

當條件運算式失敗時，您可以使用ReturnValuesOnConditionCheckFailure來要求錯誤回應包含不符合條件的項目，以推斷出問題所在。如需詳細資訊，請參閱使用 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;
      }
  }

其他程式碼範例顯示 JavsScript SDK V3 使用方式的其他層面，請參閱 JavaScript SDK V3 文件和 DynamoDB- GitHub 軟體開發套件範例範例的範例儲存庫下。

分頁

讀取要求 (例如Scan或可能Query會傳回資料集中的多個項目)。如果您Query使用Limit參數執行Scan或，則一旦系統讀取了許多項目，就會傳送部分回應，而且您需要分頁以擷取其他項目。

系統每個請求最多只能讀取 1 MB 的資料。如果您包含Filter運算式，系統仍會從磁碟讀取最多 MB 的資料，但會傳回符合篩選器的 MB 項目。篩選作業可能會針對頁面傳回 0 個項目，但在搜尋用盡之前仍需要進一步的分頁。

您應該在回應LastEvaluatedKey中尋找，並在後續要求中使用它作為ExclusiveStartKey參數，以繼續擷取資料。如下列範例中所述，這可做為書籤使用。

使用以下示例LastEvaluatedKey：

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

使用paginateScan便利的方法

SDK 提供了所謂的便利方法paginateQuery，paginateScan並為您完成此工作，並在幕後發出重複的請求。使用標準Limit參數指定每個請求要讀取的最大項目數。

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

指定組態

設定時DynamoDBClient，您可以將組態物件傳遞給建構函式，以指定各種組態覆寫。例如，如果呼叫內容或要使用的端點 URL 尚未知道該區域，您可以指定要連接的區域。如果您想要針對開發目的將 DynamoDB 本機執行個體作為目標，此功能非常有用。

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

Config 逾時

DynamoDB 會使用 HTTPS 進行用戶端與伺服器的通訊。您可以透過提供物件來控制 HTTP 層的某些方NodeHttpHandler面。例如，您可以調整金鑰逾時值connectionTimeout和requestTimeout。這connectionTimeout是用戶端在放棄之前嘗試建立連線時等待的最長持續時間 (以毫秒為單位)。

定requestTimeout義了多長時間客戶端將等待一個請求已發送後，也以毫秒為單位的響應。兩者的默認值都是零，這意味著超時被禁用，並且如果響應沒有到達，客戶端將等待多長時間沒有限制。您應該將超時設置為合理的值，以便在發生網絡問題時，請求將錯誤並啟動新請求。例如：

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

除了配置超時值之外，您還可以設置最大套接字數，這樣可以增加每個來源的並行連接數量。開發人員指南包含有關配置maxSockets參數的詳細信息。

保持活著的 Config

使用 HTTPS 時，第一個請求始終需要一些 back-and-forth 通信來建立安全連接。HTTP Keep-Alive 允許後續請求重複使用已經建立的連接，從而使請求更有效率並降低延遲。HTTP 保持活動狀態默認情況下與 JavaScript V3 啟用。

閒置連接可以保持活躍的時間是有限的。如果您有閒置連接，但希望下一個請求使用已建立的連接，請考慮發送定期請求，也許每分鐘發送一次請求。

重試 Config

當 SDK 收到錯誤回應，而且由 SDK 決定可繼續發生錯誤時，例如節流例外或暫時性服務例外狀況，則會再次重試。作為調用者，您無形地發生這種情況，除了您可能會注意到請求花費更長的時間才能成功。

在放棄並將錯誤傳遞到調用上下文之前， JavaScript V3 的 SDK 將發出 3 個總請求，默認情況下。您可以調整這些重試的次數和頻率。

DynamoDBClient構造函數接受一個限maxAttempts制會發生多少次嘗試的設置。下面的例子提出了從默認值 3 到總共 5 的值。如果將其設置為 0 或 1，則表示您不希望任何自動重試，並希望自己在 catch 塊中處理任何可恢復的錯誤。

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

您還可以使用自定義重試策略控制重試的時間。若要這麼做，請匯入util-retry公用程式套件並建立自訂輪詢函數，以根據目前的重試計數計算重試之間的等待時間。

下面的例子說，如果第一次嘗試失敗，最多可進行 5 次嘗試，延遲 15，30，90 和 360 毫秒。自訂輪詢函式會接受重試嘗試次數 (第一次重試時從 1 開始) 計算延遲 calculateRetryBackoff，並傳回等待該要求的毫秒數。

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

等待程式

DynamoDB 用戶端包含兩個實用的侍者函數，當您希望程式碼等待資料表修改完成之前，建立、修改或刪除資料表時，可以使用這些函數。例如，您可以部署資料表、呼叫waitUntilTableExists函式，程式碼會封鎖，直到資料表變成 ACTIVE 為止。服務員會在內部輪詢 DynamoDB 服務，describe-table每 20 秒進行一次。

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

只有當它可以執行顯示表狀態 ACTIVE 的describe-table命令時，該waitUntilTableExists功能才返回控制權。這樣可確保您可以用waitUntilTableExists來等待建立完成，以及新增 GSI 索引之類的修改，這可能需要一些時間才能套用資料表返回 ACTIVE 狀態。

錯誤處理

在這裡早期的例子中，我們已經廣泛地發現了所有錯誤。但是，在實際應用中，分辨各種錯誤類型並實現更精確的錯誤處理非常重要。

DynamoDB 錯誤回應包含中繼資料，包括錯誤名稱。您可以 catch 錯誤，然後匹配錯誤條件的可能字符串名稱，以確定如何繼續。對於伺服器端錯誤，您可以利用instanceof運算子搭配@aws-sdk/client-dynamodb封裝匯出的錯誤類型，以有效率地管理錯誤處理。

重要的是要注意，這些錯誤僅在所有重試用盡後才會顯示出來。如果重試錯誤並最終成功調用，則從代碼的角度來看，沒有錯誤只是稍微升高的延遲。重試將在 Amazon CloudWatch 圖表中顯示為不成功的請求，例如節流或錯誤請求。如果用戶端達到最大重試次數，就會放棄並產生例外狀況。這是用戶端說它不會重試的方式。

以下是 catch 獲錯誤並根據返回的錯誤類型採取行動的代碼片段。

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

使用 DynamoDB 時發生錯誤如需 DynamoDB 開發人員指南中的常見錯誤字串，請參閱。可以在該 API 調用的文檔中找到任何特定 API 調用可能發生的確切錯誤，例如查詢 API 文檔。

錯誤的元數據包括其他屬性，具體取決於錯誤。對於 a TimeoutError，中繼資料包括已進行的嘗試次數和totalRetryDelay，如下所示。

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

如果您管理自己的重試原則，則需要區分節流和錯誤：

日誌

打開日誌記錄以獲取有關 SDK 正在執行的更多詳細信息。您可以在上設定參數，如下列範例所示。DynamoDBClient更多記錄檔資訊會顯示在主控台中，並包含中繼資料，例如狀態碼和使用的容量。如果您在終端機視窗中本機執行程式碼，記錄會出現在該處。如果您在中運行代碼 AWS Lambda，並且已經設置了 Amazon CloudWatch 日誌，那麼控制台輸出將寫入那裡。

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

您也可以掛接到內部 SDK 活動，並在某些事件發生時執行自訂記錄。下面的示例使用客戶middlewareStack端攔截從 SDK 發送的每個請求，並在發生時對其進行記錄。

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

MiddlewareStack提供了一個強大的鉤子來觀察和控制 SDK 行為。如需詳細資訊 AWS SDK for JavaScript，請參閱模組化介紹中介軟體堆疊的部落格。

考量事項

AWS SDK for JavaScript 在您的項目中實施時，以下是一些需要考慮的其他因素。