Eseguire operazioni in blocco in Azure Cosmos DB per NoSQL usando Azure SDK per JavaScript

  • Si applica a: ✅ NoSQL

In questa guida si utilizza la funzione executeBulkOperations nel Azure SDK per JavaScript per eseguire operazioni bulk di creazione e aggiornamento in Azure Cosmos DB per NoSQL. Questa funzionalità regola la concorrenza per partizione, gestisce automaticamente la logica di ripetizione dei tentativi per ogni singola operazione ed esegue grandi quantità (100+) di operazioni. Questa funzionalità regola automaticamente la concorrenza in modo dinamico, aumentando quando le chiamate riescono senza limitazione e riducendo quando si verifica la limitazione.

Prerequisiti

  • Un account Azure Cosmos DB per NoSQL esistente

  • Node.js 22.x o versione successiva

Inizializzare l'ambiente di sviluppo

Per iniziare, creare un ambiente di sviluppo con un progetto iniziale e tutte le dipendenze degli sviluppatori. Per questo progetto, installerai @azure/cosmos dall'Azure SDK per JavaScript come dipendenza per lo sviluppo.

  1. Aprire un terminale in una cartella vuota.

  2. Inizializzare un nuovo progetto Node.js.

    npm init

  3. Aggiornare il file appena generato package.json con questo contenuto.

    {
  "main": "app.js",
  "scripts": {
    "start": "node app.js"
  }
}

  4. Installare il pacchetto @azure/cosmos da Node Gestione pacchetti (npm).

    npm install --save @azure/cosmos

    Importante

    La funzionalità di esecuzione in blocco è disponibile nelle versioni 4.3 o successive della @azure/cosmos libreria in Azure SDK per JavaScript. Se si usa una versione precedente dell'SDK, è necessario eseguire la migrazione a una versione più recente per usare queste funzionalità.

Configurare la connessione e le risorse

Usare ora il pacchetto installato per configurare la connessione a un account Azure Cosmos DB per NoSQL esistente.

  1. Importare il tipo CosmosClient e i tipi di supporto BulkOperationType e PatchOperationType.

    const { BulkOperationType, PatchOperationType, CosmosClient } = require('@azure/cosmos');

  2. Creare una nuova istanza della CosmosClient classe passando le credenziali appropriate per l'account.

    const client = new CosmosClient({
    endpoint: '<azure-cosmos-db-nosql-account-endpoint>',
    credential
});

  3. Creare costanti per i puntatori alle risorse del database e del contenitore esistenti.

    const database = client.database('<database-name>');

const container = database.container('<container-name>');

Creare un'operazione di upsert multiplo in blocco

Per iniziare, eseguire un'operazione in blocco che effettua l'upsert di due elementi. Entrambi gli elementi sono composti in una matrice di OperationInput elementi. Upsert e Create operazioni devono includere almeno i campi identificatore univoco (id) e chiave di partizione.

Annotazioni

In questo esempio la chiave di partizione è il /category campo .

  1. Creare due costanti per degli elementi da inserire o aggiornare nel contenitore.

    const yambdaSurfboard = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    category: 'gear-surf-surfboards',
    name: 'Yamba Surfboard',
    quantity: 12,
    price: 850.0,
    clearance: false
};

const kiamaClassicSurfboard = {
    id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
    category: 'gear-surf-surfboards',
    name: 'Kiama Classic Surfboard',
    quantity: 25,
    price: 790.0,
    clearance: true
};

  2. Creare una matrice di operazioni usando l'operazione Upsert per entrambi gli elementi. Specificare in modo esplicito la partitionKey proprietà e l'elemento stesso nella resourceBody proprietà .

    const upsertOperations = [
    {
        operationType: BulkOperationType.Upsert,
        partitionKey: 'gear-surf-surfboards',
        resourceBody: yambdaSurfboard
    },
    {
        operationType: BulkOperationType.Upsert,
        partitionKey: 'gear-surf-surfboards',
        resourceBody: kiamaClassicSurfboard
    }
];

Analizzare la risposta dell'operazione di massa

Eseguire e quindi esaminare la risposta dell'operazione in blocco. La risposta contiene metadati relativi a ogni operazione.

  1. Eseguire le operazioni in blocco usando il metodo executeBulkOperations della proprietà items del contenitore.

    const response = await container.items.executeBulkOperations(upsertOperations);

console.log(response);

  2. Analizzare l'oggetto della risposta. La risposta contiene un codice di stato e response un oggetto per le operazioni riuscite. Le operazioni non riuscite includono invece un error oggetto .

    npm run start

    Annotazioni

    Per ridurre al minimo le dimensioni del payload della risposta, impostare contentResponseOnWriteEnabled su false. Questo flag è specifico per le funzionalità bulk e batch nell'SDK.

    [
  {
    operationInput: {
      operationType: 'Upsert',
      id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
      partitionKey: 'gear-surf-surfboards',
      resourceBody: { ... }
    },
    response: {
      statusCode: 201,
      eTag: '...',
      activityId: '...',
      requestCharge: 7.23,
      resourceBody: { ... },
      diagnostics: { ... },
      headers: { ... }
    }
  },
  ...
]

Eseguire più operazioni in blocco

Facoltativamente, è possibile eseguire altre operazioni, tra cui Read, Deletee Patch. Tutte le operazioni usate in questa sezione devono includere il campo chiave di partizione.

Suggerimento

Le Create e Upsert operazioni richiedono sia i campi id che quelli della chiave di partizione. Le operazioni rimanenti, Read, Delete, Replacee Patch richiedono solo il campo della chiave di partizione . Se i campi obbligatori non vengono specificati, l'operazione ha esito negativo.

const variousOperations = [
    {
        operationType: BulkOperationType.Read,
        id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
        partitionKey: 'gear-surf-surfboards',
    },
    {
        operationType: BulkOperationType.Delete,
        id: 'bbbbbbbb-1111-2222-3333-cccccccccccc',
        partitionKey: 'gear-surf-surfboards',
    },
    {
        operationType: BulkOperationType.Patch,
        id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
        partitionKey: 'gear-surf-surfboards',
        resourceBody: {
            operations: [
                {
                    op: PatchOperationType.add,
                    path: '/onSale',
                    value: true
                }
            ],
        },
    }
]

const response = await container.items.executeBulkOperations(upsertOperations);

Contenuti correlati

  • Last updated on