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 una guida ai programmatori che desiderano utilizzare Amazon DynamoDB con. JavaScript Scopri i livelli di astrazione disponibili AWS SDK for JavaScript, la configurazione delle connessioni, la gestione degli errori, la definizione delle politiche di ripetizione dei tentativi, la gestione del keep-alive e altro ancora.

Informazioni su AWS SDK for JavaScript

AWS SDK for JavaScript Fornisce l'accesso all' Servizi AWS utilizzo degli script del browser o di Node.js. Questa documentazione si concentra sulla versione più recente dell'SDK (V3). La AWS SDK for JavaScript V3 è gestita da AWS come progetto open source ospitato su. GitHub I problemi e le richieste di funzionalità sono pubblici e puoi accedervi nella pagina dei problemi del repository. GitHub

JavaScript La V2 è simile alla V3, ma contiene differenze di sintassi. V3 è più modulare, facilita la distribuzione di dipendenze più piccole e offre un supporto di prima classe. TypeScript Ti consigliamo di utilizzare la versione più recente dell'SDK.

Utilizzando la versione V3 AWS SDK for JavaScript

È possibile aggiungere l'SDK all'applicazione Node.js utilizzando 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, consultate la sezione Considerazioni.

Accesso alla documentazione JavaScript

Inizia con JavaScript la documentazione 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. Ti dà il pieno controllo su tutti gli aspetti della comunicazione, ma poiché non ci sono astrazioni, devi fare cose come fornire le definizioni 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 sul filo 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 e. PutItemCommand 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 documentale di alto livello DynamoDB offre funzionalità di praticità integrate, come l'eliminazione della necessità di organizzare manualmente i dati e la possibilità di letture e scritture dirette utilizzando oggetti standard. JavaScript La documentazione per fornisce l'elenco dei vantaggi lib-dynamodb.

Per istanziare ilDynamoDBDocumentClient, costruisci un livello basso DynamoDBClient e poi avvolgilo con un. DynamoDBDocumentClient La convenzione di denominazione delle funzioni differisce leggermente tra i due pacchetti. Ad esempio, gli usi di basso livello PutItemCommand mentre quelli di alto livello. 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 GetItemQuery, oScan.

Utilizzo della funzione di utilità marshall

Puoi usare il client di basso livello e marshall o unmarshall i tipi di dati da solo. Il pacchetto di utilità util-dynamodb ha una funzione di marshall() utilità che accetta JSON e produce DynamoDB JSON, oltre a una funzione che fa il contrario. unmarshall() 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();

Elementi di lettura

Per leggere un singolo elemento da DynamoDB, si utilizza l'GetItemoperazione API. Analogamente al PutItem comando, è possibile scegliere di utilizzare il client di basso livello o il client Document di alto livello. L'esempio seguente dimostra l'utilizzo del client Document 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();

Utilizzate l'operazione Query API per leggere più elementi. È possibile utilizzare il client di basso livello o il client Document. L'esempio seguente utilizza il client Document 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 vero, 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 fallisce, puoi richiedere che la risposta ReturnValuesOnConditionCheckFailure all'errore includa l'elemento che non soddisfa le condizioni per dedurre quale fosse il problema. Per ulteriori dettagli, consulta Gestire gli errori di scrittura condizionale in scenari ad alta concorrenza con 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 di JavsScript SDK V3 sono disponibili nella documentazione di SDK V3 e nel JavaScript repository DynamoDB-SDK-Examples. GitHub

Paginazione

Richieste di lettura come o probabilmente restituiranno più Scan elementi in un set di dati. Query Se esegui un Scan o Query con un Limit parametro, una volta che il sistema avrà letto quel numero di elementi, verrà inviata una risposta parziale e dovrai impaginare per recuperare elementi aggiuntivi.

Il sistema leggerà solo un massimo di 1 megabyte di dati per richiesta. Se includi un'Filterespressione, 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 ExclusiveStartKey parametro in una richiesta successiva per continuare il recupero dei dati. Questo funge da segnalibro, come indicato nell'esempio seguente.

Esempio che utilizza: 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 paginateScan convenienza

L'SDK fornisce metodi pratici chiamati «paginateScane» paginateQuery che funzionano automaticamente ed eseguono le richieste ripetute dietro le quinte. Specificate il numero massimo di elementi da leggere per richiesta utilizzando il Limit parametro standard.

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

Durante l'impostazione diDynamoDBClient, è possibile specificare varie sostituzioni di configurazione passando un oggetto di configurazione al costruttore. Ad esempio, puoi specificare la regione a cui connetterti se non è già nota al contesto di chiamata o all'URL dell'endpoint da utilizzare. Ciò è utile se si desidera indirizzare un'istanza locale di DynamoDB per scopi di sviluppo.

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

Config 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 erequestTimeout. connectionTimeoutÈ la durata massima, in millisecondi, che il client aspetterà mentre tenta di stabilire una connessione prima di rinunciare.

requestTimeoutDefinisce per quanto tempo il client aspetterà una risposta dopo l'invio di una richiesta, anche 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

Config per keep-alive

Quando si utilizza HTTPS, la prima richiesta richiede sempre una certa back-and-forth comunicazione 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 di default con V3. JavaScript

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

Config per nuovi 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 o un'eccezione temporanea di servizio, riprova. Ciò accade in modo invisibile a te come chiamante, tranne per il fatto che potresti notare che la richiesta ha impiegato più tempo per essere accettata.

L'SDK per JavaScript V3 effettuerà 3 richieste totali, per impostazione predefinita, prima di rinunciare e passare l'errore nel contesto della chiamata. È possibile modificare il numero e la frequenza di questi tentativi.

Il DynamoDBClient costruttore accetta un'maxAttemptsimpostazione 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 lo imposti su 0 o 1, significa che non desideri effettuare nuovi tentativi automatici e che desideri gestire da solo eventuali errori ripristinabili all'interno del tuo catch block.

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

Puoi anche controllare la tempistica dei nuovi tentativi con una strategia di nuovo tentativo personalizzata. A tale scopo, importa il pacchetto di util-retry utilità e crea una funzione di backoff personalizzata che calcola il tempo di attesa tra un tentativo e l'altro in base al numero 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 calcola i ritardi accettando il numero di tentativi (inizia con 1 per il primo tentativo) e restituisce quanti millisecondi devono attendere per quella richiesta. 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.
  ),
});

Waiter

Il client DynamoDB include due utili funzioni di cameriere 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, puoi implementare una tabella, chiamare la waitUntilTableExists funzione e il codice si bloccherà finché la tabella non sarà resa ATTIVA. Il cameriere interroga internamente il servizio DynamoDB ogni 20 secondi. 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}`);

La waitUntilTableExists funzionalità restituisce il controllo solo quando può eseguire un describe-table comando che mostra lo stato della tabella ACTIVE. In questo modo è possibile waitUntilTableExists utilizzare l'opzione di attesa del completamento della creazione, nonché di apportare modifiche come l'aggiunta di un indice GSI, che potrebbe richiedere del tempo prima che la tabella ritorni allo stato ATTIVO.

Gestione degli errori

Nei primi esempi qui riportati, abbiamo individuato 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, incluso il nome dell'errore. È possibile catturare gli errori e confrontarli con i possibili nomi di stringa delle condizioni di errore per determinare come procedere. Per gli errori sul lato server, è possibile sfruttare l'instanceofoperatore con i tipi di errore esportati dal @aws-sdk/client-dynamodb pacchetto per gestire in modo efficiente la gestione degli errori.

È importante notare che questi errori si manifestano solo dopo aver esaurito tutti i tentativi. Se un errore viene ripetuto e alla fine viene seguito da una chiamata riuscita, dal punto di vista del codice, non si verifica alcun errore, ma solo una latenza leggermente elevata. I nuovi tentativi verranno visualizzati nei CloudWatch grafici di Amazon come richieste non riuscite, ad esempio richieste di accelerazione o di errore. Se il client raggiunge il numero massimo di tentativi, si arrenderà e genererà un'eccezione. Questo è il modo in cui il cliente dice che non riproverà.

Di seguito è riportato uno snippet per catturare 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.
      }
    }
}

Vedi Gestione degli errori con DynamoDB le stringhe di errore più comuni nella DynamoDB Developer Guide. Gli errori esatti possibili con una particolare chiamata API sono disponibili nella documentazione relativa a quella chiamata API, come i documenti dell'API Query.

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

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

Se gestisci la tua politica sui nuovi tentativi, ti consigliamo di distinguere tra limitatori ed errori:

Registrazione

Attiva la registrazione per ottenere maggiori dettagli su ciò che sta facendo l'SDK. Puoi impostare un parametro su DynamoDBClient come mostrato nell'esempio seguente. Nella console verranno visualizzate ulteriori informazioni di registro che includono metadati come il codice di stato e la capacità consumata. Se esegui il codice localmente in una finestra di terminale, i log vengono visualizzati lì. Se esegui il codice e hai configurato CloudWatch i log di Amazon, l'output della console verrà scritto lì. AWS Lambda

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

Puoi anche collegarti alle attività SDK interne ed eseguire registrazioni personalizzate quando si verificano determinati eventi. L'esempio seguente utilizza i dati del client middlewareStack per intercettare ogni richiesta inviata dall'SDK e per registrarla 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",
  }
);

MiddlewareStackFornisce un potente strumento per osservare e controllare il comportamento dell'SDK. Per ulteriori informazioni, consulta il blog Introducing Middleware Stack in Modular AWS SDK for JavaScript.

Considerazioni

Quando lo implementi AWS SDK for JavaScript nel tuo progetto, ecco alcuni altri fattori da considerare.