Programmation d’Amazon DynamoDB avec JavaScript

Ce guide fournit une orientation aux programmeurs qui souhaitent utiliser Amazon DynamoDB avec JavaScript. Découvrez AWS SDK pour JavaScript, les couches d’abstraction disponibles, la configuration de connexions, le traitement des erreurs, la définition de politiques de nouvelle tentative, la gestion de keep-alive, et bien d’autres fonctionnalités.

À propos de AWS SDK pour JavaScript

AWS SDK pour JavaScript permet d’accéder à des Services AWS en utilisant des scripts de navigateur ou Node.js. Cette documentation se concentre sur la dernière version du kit SDK (V3). La version 3 de AWS SDK pour JavaScript est gérée par AWS e, tant que projet open source hébergé sur GitHub. Les problèmes et les demandes de fonctionnalités sont publics et vous pouvez y accéder sur la page des problèmes du référentiel GitHub.

La version 2 de JavaScript est similaire à la version 3, mais elle contient des différences de syntaxe. La version 3 est plus modulaire, ce qui facilite l’expédition de petites dépendances, et dispose d’une prise en charge TypeScript de première classe. Nous vous recommandons d’utiliser la dernière version du kit SDK.

Utilisation de la version 3 de AWS SDK pour JavaScript

Vous pouvez ajouter le kit SDK à votre application Node.js à l’aide de Node Package Manager. Les exemples ci-dessous montrent comment ajouter les packages SDK les plus courants à utiliser avec DynamoDB.

L’installation de packages ajoute des références à la section de dépendance de votre fichier de projet package.json. Vous avez la possibilité d’utiliser la nouvelle syntaxe du module ECMAScript. Pour plus de détails sur ces deux approches, consultez la section Considérations.

Accès à la documentation JavaScript

Démarrez avec la documentation JavaScript grâce aux ressources suivantes :

Couches d’abstraction

Le kit SDK pour JavaScript version V3 possède un client de bas niveau (DynamoDBClient) et un client de haut niveau (DynamoDBDocumentClient).

Client de bas niveau (DynamoDBClient)

Le client de bas niveau ne fournit aucune abstraction supplémentaire par rapport au protocole filaire sous-jacent. Cela vous donne un contrôle total sur tous les aspects de la communication, mais comme il n’y a pas d’abstractions, vous devez notamment fournir des définitions d’éléments à l’aide du format JSON DynamoDB.

Comme le montre l’exemple ci-dessous, avec ce format, les types de données doivent être indiqués explicitement. Un S indique une valeur de chaîne et un N une valeur numérique. Les numéros sur la transmission sont toujours envoyés sous forme de chaînes balisées sous forme de types numériques pour éviter toute perte de précision. Les appels d’API de bas niveau ont un modèle d’affectation tel que PutItemCommand et GetItemCommand.

L’exemple suivant utilise un client de bas niveau Item défini à l’aide d’un fichier JSON DynamoDB :

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

Client de haut niveau (DynamoDBDocumentClient)

Le client de document DynamoDB de haut niveau offre des fonctionnalités pratiques intégrées, telles que l’élimination de la nécessité de rassembler manuellement les données et l’autorisation de lectures et d’écritures directes à l’aide d’objets JavaScript standard. La documentation de lib-dynamodb fournit la liste des avantages.

Pour instancier le DynamoDBDocumentClient, construisez un DynamoDBClient de bas niveau ; puis encapsulez-le avec un DynamoDBDocumentClient. La convention de dénomination des fonctions diffère légèrement entre les deux packages. Par exemple, le bas niveau utilise PutItemCommand tandis que le haut niveau utilise PutCommand. Les noms distincts permettent aux deux ensembles de fonctions de coexister dans le même contexte, ce qui vous permet de combiner les deux dans le même script.

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

Le modèle d’utilisation est cohérent lorsque vous lisez des éléments à l’aide d’opérations d’API telles que GetItem, Query ou Scan.

Utilisation de la fonction utilitaire de regroupement

Vous pouvez utiliser le client de bas niveau et regrouper ou désorganiser vous-même les types de données. Le package d’utilitaires, util-dynamodb, possède une fonction utilitaire marshall() qui accepte le JSON et produit DynamoDB JSON, ainsi qu’une fonction unmarshall() qui effectue l’inverse. L’exemple suivant utilise le client de bas niveau avec la désorganisation des données gérée par l’appel 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();

Lecture d’éléments

Pour lire un seul élément à partir de DynamoDB, utilisez l’opération d’API GetItem. Comme pour la commande PutItem, vous avez le choix d’utiliser le client de bas niveau ou le client Document de haut niveau. L’exemple ci-dessous montre comment utiliser le client Document de haut niveau pour extraire un élément.

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

Utilisez l’opération d’API Query pour lire plusieurs éléments. Vous pouvez utiliser le client de bas niveau ou le client Document. L’exemple ci-dessous utilise le client Document de haut niveau.

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

Écritures conditionnelles

Les opérations d’écriture DynamoDB peuvent spécifier une expression de condition logique qui doit être définie sur true pour que l’écriture puisse se poursuivre. Si la condition n’est pas définie sur true, l’opération d’écriture génère une exception. L’expression de condition peut vérifier si l’élément existe déjà ou si ses attributs correspondent à certaines contraintes.

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

Lorsque l’expression conditionnelle échoue, vous pouvez utiliser ReturnValuesOnConditionCheckFailure pour demander que la réponse d’erreur inclue l’élément qui ne satisfaisait pas aux conditions afin de déduire l’origine du problème. Pour plus de détails, consultez Handle conditional write errors in high concurrency scenarios with 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;
      }
  }

Des exemples de code supplémentaires illustrant d’autres aspects de l’utilisation du kit SDK JavaScript version 3 sont disponibles dans la documentation du kit SDK JavaScript version 3 et dans le référentiel GitHub DynamoDB-SDK-Examples.

Pagination

Les demandes de lecture telles que Scan ou Query renverront probablement plusieurs éléments dans un jeu de données. Si vous effectuez une Scan ou une Query avec un paramètre Limit, une fois que le système aura lu autant d’éléments, une réponse partielle sera envoyée et vous devrez paginer pour récupérer des éléments supplémentaires.

Le système ne lira qu’un maximum de 1 mégaoctet de données par demande. Si vous incluez une expression Filter, le système lira toujours un mégaoctet, au maximum, de données sur le disque, mais renverra les éléments de ce mégaoctet qui correspondent au filtre. L’opération de filtrage peut renvoyer 0 élément pour une page, mais nécessite tout de même une pagination supplémentaire avant que la recherche ne soit épuisée.

Vous devez rechercher LastEvaluatedKey dans la réponse et l’utiliser comme paramètre ExclusiveStartKey dans une demande ultérieure pour poursuivre l’extraction des données. Cela sert de signet, comme indiqué dans l’exemple suivant.

Exemple d’utilisation de 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);
});

Utilisation de la méthode pratique paginateScan

Le kit SDK fournit des méthodes pratiques appelées paginateScan et paginateQuery qui font cela à votre place et qui font les demandes répétées en arrière-plan. Spécifiez le nombre maximum d’éléments à lire par demande à l’aide du paramètre standard 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);
});

Spécification d’une configuration

Lors de la configuration de DynamoDBClient, vous pouvez spécifier différentes remplacements de configuration en transmettant un objet de configuration au constructeur. Par exemple, vous pouvez spécifier la région à laquelle vous connecter si le contexte d’appel ne la connaît pas déjà ou si l’URL du point de terminaison à utiliser ne la connaît pas déjà. Cela est utile si vous souhaitez cibler une instance DynamoDB local à des fins de développement.

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

Configuration pour les délais d’expiration

DynamoDB utilise HTTPS pour les communications client-serveur. Vous pouvez contrôler certains aspects de la couche HTTP en fournissant un objet NodeHttpHandler. Par exemple, vous pouvez ajuster les principales valeurs de délai d’expiration connectionTimeout et requestTimeout. connectionTimeout représente la durée maximale, en millisecondes, pendant laquelle le client doit attendre lorsqu’il essaie d’établir une connexion avant d’abandonner.

requestTimeout définit le temps pendant lequel le client doit attendre une réponse après l’envoi d’une demande, également en millisecondes. La valeur par défaut pour les deux est zéro, ce qui signifie que le délai d’attente est désactivé et qu’il n’y a aucune limite quant au temps d’attente du client si la réponse n’arrive pas. Vous devez définir les délais d’expiration à un niveau raisonnable afin qu’en cas de problème réseau, la demande soit en erreur et qu’une nouvelle demande puisse être initiée. Par exemple :

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

Outre la configuration des valeurs de délai d’expiration, vous pouvez définir le nombre maximum de sockets, ce qui permet d’augmenter le nombre de connexions simultanées par origine. Le guide du développeur contient des informations détaillées sur la configuration du paramètre maxSockets.

Configuration pour keep-alive

Lorsque vous utilisez le protocole HTTPS, la première demande nécessite toujours des échanges de va-et-vient pour établir une connexion sécurisée. HTTP Keep-Alive permet aux requêtes suivantes de réutiliser la connexion déjà établie, ce qui les rend plus efficaces et réduit le temps de latence. HTTP Keep-Alive est activé par défaut avec la version 3 de JavaScript.

Il y a une limite à la durée pendant laquelle une connexion inactive peut être maintenue en vie. Envisagez d’envoyer des demandes périodiques, par exemple toutes les minutes, si vous avez une connexion inactive mais que vous souhaitez que la prochaine demande utilise une connexion déjà établie.

Configuration pour les nouvelles tentatives

Lorsque le kit SDK reçoit une réponse d’erreur et que l’erreur peut être reprise comme indiqué par le kit SDK, par exemple une exception de limitation ou une exception de service temporaire, il réessaie. Cela se produit de manière invisible pour vous en tant qu’appelant, sauf que vous remarquerez peut-être que la demande a mis plus de temps à aboutir.

Le kit SDK pour JavaScript version 3 effectuera 3 demandes au total, par défaut, avant d’abandonner et de transmettre l’erreur au contexte d’appel. Vous pouvez ajuster le nombre et la fréquence de ces nouvelles tentatives.

Le constructeur DynamoDBClient accepte un paramètre maxAttempts qui limite le nombre de tentatives possibles. L’exemple ci-dessous augmente la valeur de 3 par défaut à 5 au total. Si vous le définissez sur 0 ou 1, cela indique que vous ne souhaitez pas de nouvelles tentatives automatiques et que vous souhaitez gérer vous-même les erreurs reprenant dans votre bloc catch.

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

Vous pouvez également contrôler le calendrier des nouvelles tentatives à l’aide d’une stratégie de nouvelle tentative personnalisée. Pour ce faire, importez le package d’utilitaires util-retry et créez une fonction de sauvegarde personnalisée qui calcule le temps d’attente entre les tentatives en fonction du nombre de tentatives actuel.

L’exemple ci-dessous indique d’effectuer un maximum de 5 tentatives avec des délais de 15, 30, 90 et 360 millisecondes en cas d’échec de la première tentative. La fonction d’annulation personnalisée, calculateRetryBackoff, calcule les délais en acceptant le nombre de nouvelles tentatives (commence par 1 pour la première nouvelle tentative) et renvoie le nombre de millisecondes à attendre pour cette demande.

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

Programmes d’attente

Le client DynamoDB inclut deux fonctions de programmes d’attente qui peuvent être utilisées lors de la création, de la modification ou de la suppression de tables lorsque vous souhaitez que votre code attende jusqu’à ce que la modification des tables soit terminée. Par exemple, vous pouvez déployer une table, appeler la fonction waitUntilTableExists, et le code bloquera jusqu’à ce que la table soit ACTIVE. Le serveur interroge en interne le service DynamoDB avec un describe-table toutes les 20 secondes.

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

La fonctionnalité waitUntilTableExists ne rend le contrôle que lorsqu’elle peut exécuter une commande describe-table indiquant le statut de table ACTIF. Cela garantit que vous pouvez utiliser waitUntilTableExists pour attendre la fin de la création, ainsi que des modifications telles que l’ajout d’un index GSI, dont l’application peut prendre un certain temps avant que la table ne revienne au statut ACTIF.

Gestion des erreurs

Dans les premiers exemples présentés ici, nous avons identifié toutes les erreurs de manière générale. Cependant, dans les applications pratiques, il est important de distinguer les différents types d’erreurs et de mettre en œuvre une gestion plus précise de celles-ci.

Les réponses aux erreurs DynamoDB contiennent des métadonnées, notamment le nom de l’erreur. Vous pouvez détecter les erreurs puis les comparer aux noms de chaîne possibles des conditions d’erreur afin de déterminer la marche à suivre. Pour les erreurs côté serveur, vous pouvez optimiser l’opérateur instanceof avec les types d’erreur exportés par le package @aws-sdk/client-dynamodb pour gérer efficacement la gestion des erreurs.

Il est important de noter que ces erreurs ne se manifestent qu’une fois toutes les nouvelles tentatives épuisées. Si une erreur fait l’objet d’une nouvelle tentative, suivi d’un appel qui aboutit, du point de vue du code, aucune erreur n’est détectée, juste une latence légèrement élevée. Les nouvelles tentatives apparaîtront dans les graphiques Amazon CloudWatch en tant que demandes infructueuses, telles que les demandes de limitation ou d’erreur. Si le client atteint le nombre maximal de nouvelles tentatives, il abandonne et génère une exception. Il s’agit de la façon dont le client dit qu’il ne va pas réessayer.

Vous trouverez ci-dessous un extrait permettant de détecter l’erreur et de prendre des mesures en fonction du type d’erreur renvoyé.

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

Pour plus d’informations sur les chaînes d’erreur les plus courantes, consultez Gestion des erreurs avec DynamoDB dans le guide du développeur DynamoDB. Les erreurs exactes possibles avec un appel d’API particulier peuvent être trouvées dans la documentation de cet appel d’API, telle que la documentation de l’API de requête.

Les métadonnées des erreurs incluent des propriétés supplémentaires, en fonction de l’erreur. Pour un TimeoutError, les métadonnées incluent le nombre de tentatives effectuées et le totalRetryDelay, comme indiqué ci-dessous.

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

Si vous gérez votre propre stratégie de nouvelle tentative, vous devez faire la différence entre les limitations et les erreurs :

Journalisation

Activez la journalisation pour obtenir plus de détails sur le fonctionnement du kit SDK. Vous pouvez définir un paramètre sur leDynamoDBClient, comme indiqué dans l’exemple ci-dessous. D’autres informations de journal apparaîtront dans la console et incluent des métadonnées telles que le code d’état et la capacité consommée. Si vous exécutez le code localement dans une fenêtre de terminal, les journaux y apparaissent. Si vous exécutez le code dans AWS Lambda et que les journaux Amazon CloudWatch sont configurés, la sortie de la console y sera écrite.

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

Vous pouvez également vous connecter aux activités internes du kit SDK et effectuer une journalisation personnalisée lorsque certains événements se produisent. L’exemple ci-dessous utilise le middlewareStack du client pour intercepter chaque demande au fur et à mesure qu’elle est envoyée par le kit SDK et l’enregistre au fur et à mesure qu’elle se produit.

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

Le MiddlewareStack constitue un hook puissant pour observer et contrôler le comportement du kit SDK. Consultez le blog Introducing Middleware Stack in Modular AWS SDK pour JavaScript pour plus d’informations.

Considérations

Lorsque vous implémentez l’AWS SDK pour JavaScript dans votre projet, voici d’autres facteurs à prendre en compte.