Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Programmazione di Amazon DynamoDB con JavaScript

Questa guida fornisce un orientamento ai programmatori che desiderano utilizzare Amazon DynamoDB con JavaScript. Informazioni sull’AWS SDK per JavaScript, i livelli di astrazione disponibili, la configurazione delle connessioni, la gestione degli errori, la definizione delle policy di ripetizione dei tentativi, la gestione del keep-alive e altro ancora.

Informazioni su AWS SDK per JavaScript

L’AWS SDK per JavaScript fornisce l’accesso ai Servizi AWS negli script del browser o su Node.js. Questa documentazione si concentra sull’ultima versione dell’SDK (V3). L’AWS SDK per JavaScript V3 è gestito da AWS come progetto open source ospitato su GitHub. I problemi e le richieste di funzionalità sono pubblici ed è possibile accedervi nella pagina dei problemi del repository GitHub.

JavaScript V2 è simile a V3, ma contiene differenze di sintassi. V3 è più modulare, facilita l’invio di dipendenze più piccole e dispone di un supporto TypeScript di primo livello. Si consiglia di utilizzare sempre la versione più recente dell’SDK.

Utilizzo di AWS SDK per JavaScript V3

È possibile aggiungere l’SDK all’applicazione Node.js tramite Node Package Manager. Gli esempi seguenti mostrano come aggiungere i pacchetti SDK più comuni per lavorare con DynamoDB.

L’installazione dei pacchetti aggiunge riferimenti alla sezione relativa alle dipendenze del file di progetto package.json. È possibile utilizzare la sintassi del modulo ECMAScript più recente. Per ulteriori dettagli su questi due approcci, consulta la sezione Considerazioni.

Accesso alla documentazione JavaScript

Inizia a esplorare la documentazione JavaScript con le seguenti risorse:

Livelli di astrazione

L’SDK per JavaScript V3 ha un client di basso livello (DynamoDBClient) e un client di alto livello (DynamoDBDocumentClient).

Client di basso livello (DynamoDBClient)

Il client di basso livello non fornisce astrazioni aggiuntive rispetto al protocollo wire sottostante. Dà il pieno controllo su tutti gli aspetti della comunicazione, ma poiché non ci sono astrazioni, è necessario occuparsi manualmente di aspetti come la definizione degli elementi utilizzando il formato JSON di DynamoDB.

Come illustrato nell’esempio seguente, con questo formato i tipi di dati devono essere indicati in modo esplicito. Una S indica un valore di stringa e una N indica un valore numerico. I numeri in rete vengono sempre inviati come stringhe contrassegnate come tipi di numeri per evitare perdite di precisione. Le chiamate API di basso livello hanno uno schema di denominazione come PutItemCommand e GetItemCommand.

L’esempio seguente utilizza un client di basso livello con Item definito utilizzando 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();

Client di alto livello (DynamoDBDocumentClient)

Il client di documenti di alto livello DynamoDB offre funzionalità pratiche integrate, come l’eliminazione della necessità di eseguire manualmente il marshalling dei dati e la possibilità di letture e scritture dirette utilizzando oggetti JavaScript standard. La documentazione per lib-dynamodb illustra l’elenco dei vantaggi.

Per istanziare DynamoDBDocumentClient, costruisci un DynamoDBClient di basso livello e poi avvolgilo con un DynamoDBDocumentClient. La convenzione di denominazione delle funzioni differisce leggermente tra i due pacchetti. Ad esempio, il basso livello utilizza PutItemCommand, mentre l’alto livello utilizza PutCommand. I nomi distinti consentono a entrambi i set di funzioni di coesistere nello stesso contesto, permettendo di mescolarli entrambi nello stesso 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();

Il modello di utilizzo è coerente quando si leggono elementi utilizzando operazioni API come GetItem, Query oScan.

Utilizzo della funzione di utilità marshall

È possibile utilizzare il client di basso livello ed eseguire manualmente le operazioni di marshall e unmarshall sui tipi di dati. Il pacchetto di utilità util-dynamodb ha una funzione di utilità marshall() che accetta JSON e produce DynamoDB JSON, oltre a una funzione unmarshall(), che fa l’opposto. L’esempio seguente utilizza il client di basso livello con il marshalling dei dati gestito dalla chiamata 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();

Lettura degli elementi

Per leggere un singolo elemento da DynamoDB si utilizza l’operazione API GetItem. Analogamente al comando PutItem, è possibile scegliere di utilizzare il client di basso livello o il client di documenti di alto livello. L’esempio seguente dimostra l’utilizzo del client di documenti di alto livello per recuperare un elemento.

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

Utilizza l’operazione API Query per leggere più elementi. È possibile utilizzare il client di basso livello o il client di documenti. L’esempio seguente utilizza il client di documenti di alto livello.

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

Scritture condizionali

Le operazioni di scrittura di DynamoDB possono specificare un’espressione di condizione logica che deve restituire true affinché la scrittura possa procedere. Se la condizione non restituisce true, l’operazione di scrittura genera un’eccezione. L’espressione della condizione può verificare se l’elemento esiste già o se i suoi attributi soddisfano determinati vincoli.

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

Quando l’espressione condizionale non va a buon fine, è possibile utilizzare ReturnValuesOnConditionCheckFailure per richiedere che la risposta all’errore includa l’elemento che non soddisfa le condizioni per dedurre quale fosse il problema. Per ulteriori dettagli, consulta 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;
      }
  }

Esempi di codice aggiuntivi che mostrano altri aspetti dell’utilizzo dell’SDK per JavaScript V3 sono disponibili nella risorsa relativa alla documentazione dell’SDK per JavaScript V3 e nel repository GitHub DynamoDB-SDK-Examples.

Impaginazione

Richieste di lettura come Scan o Query probabilmente restituiranno più elementi in un set di dati. Se si esegue un’operazione Scan o Query con un parametro Limit, una volta che il sistema avrà letto quel numero di elementi, verrà inviata una risposta parziale e sarà necessario eseguire un’impaginazione per recuperare elementi aggiuntivi.

Il sistema leggerà solo un massimo di 1 megabyte di dati per richiesta. Se si include un’espressione Filter, il sistema continuerà a leggere al massimo un megabyte di dati dal disco, ma restituirà gli elementi di quel megabyte che corrispondono al filtro. L’operazione di filtro potrebbe restituire 0 elementi per una pagina, ma richiedere comunque un’ulteriore impaginazione prima che la ricerca sia esaurita.

È necessario cercare LastEvaluatedKey nella risposta e utilizzarlo come parametro ExclusiveStartKey in una richiesta successiva per continuare il recupero dei dati. Questa operazione funge da segnalibro, come indicato nell’esempio seguente.

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

Utilizzo del metodo di convenienza paginateScan

L’SDK fornisce metodi pratici denominati paginateScan e paginateQuery che funzionano automaticamente ed eseguono le richieste ripetute in background. Specifica il numero massimo di elementi da leggere per richiesta utilizzando il parametro 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);
});

Specificare la configurazione

Per la configurazione di DynamoDBClient, è possibile specificare varie sostituzioni di configurazione passando un oggetto di configurazione al costruttore. Ad esempio, è possibile specificare la Regione a cui connettersi se non è già nota al contesto di chiamata o all’URL dell’endpoint da utilizzare. Ciò è utile se si desidera indirizzare un’istanza di DynamoDB locale per scopi di sviluppo.

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

Configurazione per i timeout

DynamoDB utilizza HTTPS per la comunicazione client-server. È possibile controllare alcuni aspetti del livello HTTP fornendo un oggetto NodeHttpHandler. Ad esempio, è possibile regolare i valori di timeout chiave connectionTimeout e requestTimeout. connectionTimeout è la durata massima, in millisecondi, che il client aspetterà mentre tenta di stabilire una connessione prima di rinunciare.

requestTimeout definisce per quanto tempo il client aspetterà una risposta dopo l’invio di una richiesta, anch’esso in millisecondi. Le impostazioni predefinite per entrambi sono zero, il che significa che il timeout è disabilitato e non c’è limite al tempo di attesa del client se la risposta non arriva. È necessario impostare i timeout su un valore ragionevole in modo che, in caso di problemi di rete, la richiesta venga annullata e possa essere avviata una nuova richiesta. Per esempio:

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

Oltre a configurare i valori di timeout, è possibile impostare il numero massimo di socket, il che consente un numero maggiore di connessioni simultanee per origine. La guida per gli sviluppatori include dettagli sulla configurazione del parametro maxSockets.

Configurazione per keep-alive

Quando si utilizza HTTPS, la prima richiesta richiede sempre alcuni scambi preliminari per stabilire una connessione sicura. HTTP Keep-Alive consente alle richieste successive di riutilizzare la connessione già stabilita, rendendo le richieste più efficienti e riducendo la latenza. HTTP Keep-Alive è abilitato per impostazione predefinita con JavaScript V3.

Esiste un limite per la quantità di tempo in cui una connessione inattiva può essere mantenuta attiva. Prendi in considerazione l’invio di richieste periodiche, ad esempio ogni minuto, se hai una connessione inattiva ma desideri che la richiesta successiva utilizzi una connessione già stabilita.

Configurazione per le ripetizioni di tentativi

Quando l’SDK riceve una risposta di errore e l’errore è ripristinabile in base a quanto stabilito dall’SDK, ad esempio un’eccezione di limitazione (della larghezza di banda della rete) o un’eccezione temporanea di servizio, ripeterà il tentativo. L’operazione avviene in modo invisibile al chiamante, sebbene sia possibile osservare un tempo maggiore per il completamento della richiesta.

L’SDK per JavaScript V3 effettuerà tre richieste totali, per impostazione predefinita, prima di rinunciare e restituire l’errore al contesto chiamante. È possibile modificare il numero e la frequenza di tali ripetizioni di tentativi.

Il costruttore DynamoDBClient accetta un’impostazione maxAttempts che limita il numero di tentativi da eseguire. L’esempio seguente aumenta il valore dal valore predefinito di 3 a un totale di 5. Se viene impostato su 0 o 1, significa l’assenza di intenzione di effettuare ripetizioni di tentativi automatiche e l’intenzione di gestire in autonomia eventuali errori ripristinabili all’interno del blocco catch.

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

È possibile anche controllare la tempistica delle ripetizioni di tentativi con una strategia relativa personalizzata. A tale scopo, importa il pacchetto di utilità util-retry e crea una funzione di backoff personalizzata che calcola il tempo di attesa tra le ripetizioni dei tentativi in base al numero di ripetizioni di tentativi corrente.

L’esempio seguente indica di effettuare un massimo di 5 tentativi con ritardi di 15, 30, 90 e 360 millisecondi se il primo tentativo fallisce. La funzione di backoff personalizzata, calculateRetryBackoff, calcola i ritardi accettando il numero di ripetizioni dei tentativi (inizia con 1 per il primo tentativo) e restituisce quanti millisecondi attendere per quella richiesta.

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

Waiter

Il client DynamoDB include due utili funzioni waiter che possono essere utilizzate durante la creazione, la modifica o l’eliminazione di tabelle quando si desidera che il codice attenda di procedere fino al termine della modifica della tabella. Ad esempio, è possibile implementare una tabella, chiamare la funzione waitUntilTableExists e il codice si bloccherà finché la tabella non sarà resa ACTIVE. Il waiter interroga internamente il servizio DynamoDB con describe-table ogni 20 secondi.

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 funzionalità waitUntilTableExists restituisce il controllo solo quando può eseguire un comando describe-table che mostra lo stato della tabella ACTIVE. In questo modo è possibile utilizzare waitUntilTableExists per attendere il completamento della creazione, nonché apportare modifiche come l’aggiunta di un GSI, che potrebbe richiedere del tempo prima che la tabella ritorni allo stato ACTIVE.

Gestione degli errori

Nei primi esempi precedenti sono stati individuati tutti gli errori in generale. Tuttavia, nelle applicazioni pratiche, è importante distinguere tra vari tipi di errore e implementare una gestione degli errori più precisa.

Le risposte di errore di DynamoDB contengono metadati, che comprendono il nome dell’errore. È possibile intercettare gli errori e confrontarli con i possibili nomi delle condizioni di errore per stabilire come procedere. Per gli errori lato server, è possibile sfruttare l’operatore instanceof con i tipi di errore esportati dal pacchetto @aws-sdk/client-dynamodb per dedicarsi in modo efficiente alla gestione degli errori.

È importante notare che questi errori si manifestano solo dopo aver esaurito tutte le ripetizioni di tentativi. Se dopo un errore viene effettuata una ripetizione di tentativo, successivamente seguita da una chiamata riuscita, dal punto di vista del codice non c’è alcun errore, ma solo una latenza leggermente maggiore. Le ripetizioni di tentativi verranno visualizzate nei grafici di Amazon CloudWatch come richieste non riuscite, ad esempio richieste di limitazione (della larghezza di banda della rete) o di errore. Se il client raggiunge il numero massimo di ripetizioni dei tentativi, rinuncerà e genererà un’eccezione. Con questa modalità il client comunica che non ripeterà i tentativi.

Di seguito è riportato uno snippet per intercettare l’errore e agire in base al tipo di errore restituito.

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

Consulta Gestione degli errori con DynamoDB per le stringhe di errore più comuni nella Guida per gli sviluppatori di DynamoDB. Gli errori esatti possibili con una particolare chiamata API sono disponibili nella documentazione relativa a quella chiamata API, come Query API docs.

I metadati degli errori includono proprietà aggiuntive, a seconda dell’errore. Per un TimeoutError, i metadati includono il numero di tentativi effettuati e il totalRetryDelay, come illustrato di seguito.

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

Se si gestisce in autonomia la propria policy sulla ripetizione dei tentativi, si consiglia di distinguere tra limitazioni (della larghezza di banda della rete) ed errori:

Registrazione

Attiva la registrazione di log per ottenere maggiori dettagli sulle attività dell’SDK. È possibile impostare un parametro DynamoDBClient come mostrato nell’esempio seguente. Nella console verranno visualizzate ulteriori informazioni dei log che includono metadati come il codice dello stato e la capacità utilizzata. Eseguendo il codice in locale tramite una finestra del terminale, i log saranno mostrati direttamente in questo ambiente. Se si esegue il codice in AWS Lambda e i Amazon CloudWatch Logs è stato configurato, l’output della console verrà scritto lì.

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

È anche possibile collegarsi alle attività interne dell’SDK ed eseguire registrazioni di log personalizzate quando si verificano determinati eventi. L’esempio seguente utilizza i dati del client middlewareStack per intercettare ogni richiesta inviata dall’SDK e per eseguirne la registrazione di log man mano che avviene.

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 fornisce un potente strumento per osservare e controllare il comportamento dell’SDK. Per ulteriori informazioni, consulta il blog Introducing Middleware Stack in Modular AWS SDK per JavaScript.

Considerazioni

Per l’implementazione di AWS SDK per JavaScript in un progetto, ecco alcuni altri fattori da considerare.