Azure Cosmos DB Node.js SDK per l'API per NoSQL: note sulla versione e risorse

  • Articolo

SI APPLICA A: NoSQL

Resource Collega
Scaricare l'SDK @azure/cosmos
Documentazione API Documentazione di riferimento per JavaScript SDK
Istruzioni per l'installazione dell'SDK npm install @azure/cosmos
Contribuire all'SDK Guida ai contributi per il repository azure-sdk-for-js
Esempi Esempi di codice Node.js
Esercitazione introduttiva Introduzione a JavaScript SDK
Esercitazione sull'app Web Creare un'applicazione Web Node.js con Azure Cosmos DB
Piattaforme di Node.js supportate correnti Versioni LTS di Node.js

Note sulla versione

La cronologia delle versioni viene mantenuta nel repository azure-sdk-for-js, per un elenco dettagliato delle versioni, vedere il file del log delle modifiche.

Guida alla migrazione per modifiche di rilievo

Se si usa una versione precedente dell'SDK, è consigliabile eseguire la migrazione alla versione 3.0. Questa sezione descrive in dettaglio i miglioramenti che si otterrebbero con questa versione e le correzioni di bug apportate nella versione 3.0.

Opzioni del costruttore client migliorate

Sono state semplificate le opzioni del costruttore:

  • masterKey è stata rinominata chiave e spostata al livello superiore
  • Le proprietà in precedenza in options.auth sono state spostate al livello superiore
// v2
const client = new CosmosClient({
    endpoint: "https://your-database.cosmos.azure.com",
    auth: {
        masterKey: "your-primary-key"
    }
})

// v3
const client = new CosmosClient({
    endpoint: "https://your-database.cosmos.azure.com",
    key: "your-primary-key"
})

API iteratore di query semplificata

Nella versione 2 sono disponibili molti modi diversi per eseguire l'iterazione o recuperare i risultati da una query. Si è provato a semplificare l'API v3 e a rimuovere API simili o duplicate:

  • Sono stati rimossi iterator.next() e iterator.current(). È stato usato fetchNext() per ottenere pagine di risultati.
  • È stato rimosso iterator.forEach(). Vengono usati invece iteratori asincroni.
  • iterator.executeNext() è stato rinominato in iterator.fetchNext()
  • iterator.toArray() è stato rinominato in iterator.fetchAll()
  • Le pagine sono ora oggetti Response appropriati anziché oggetti JS semplici
  • const container = client.database(dbId).container(containerId)
// v2
container.items.query('SELECT * from c').toArray()
container.items.query('SELECT * from c').executeNext()
container.items.query('SELECT * from c').forEach(({ body: item }) => { console.log(item.id) })

// v3
container.items.query('SELECT * from c').fetchAll()
container.items.query('SELECT * from c').fetchNext()
for await(const { result: item } in client.databases.readAll().getAsyncIterator()) {
    console.log(item.id)
}

I contenitori fissi sono ora partizionati

Il servizio Azure Cosmos DB supporta ora le chiavi di partizione in tutti i contenitori, incluse quelle create in precedenza come contenitori fissi. L'SDK v3 viene aggiornato alla versione più recente dell'API che implementa questa modifica, ma non causa interruzioni. Se non si specifica una chiave di partizione per le operazioni, per impostazione predefinita si userà una chiave di sistema che funziona con tutti i contenitori e i documenti esistenti.

È stato rimosso l'upsert per le stored procedure

In precedenza, era possibile usare l'upsert per le raccolte non partizionate, ma con l'aggiornamento della versione dell'API, tutte le raccolte sono ora partizionate e, di conseguenza, l'upsert è stato completamente rimosso.

Le letture degli elementi non generano un'eccezione su 404

const container = client.database(dbId).container(containerId)

// v2
try {
    container.items.read(id, undefined)
} catch (e) {
    if (e.code === 404) { console.log('item not found') }
}

// v3
const { result: item }  = container.items.read(id, undefined)
if (item === undefined) { console.log('item not found') }

Scritture predefinite in più aree

L'SDK scriverà ora in più aree per impostazione predefinita se la configurazione di Azure Cosmos DB la supporta. In precedenza, per questo comportamento era necessario il consenso esplicito.

Oggetti errore appropriati

Le richieste non riuscite generano ora errori o sottoclassi di errore appropriati. In precedenza, generavano oggetti JS semplici.

Nuove funzionalità

Richieste annullabili dall'utente

Con il passaggio al fetch interno, è possibile usare l'API AbortController del browser per supportare le operazioni annullabili dall'utente. Nel caso di operazioni in cui più richieste sono potenzialmente in corso (ad esempio query tra partizioni), tutte le richieste per l'operazione verranno annullate. Gli utenti dei browser moderni hanno già a disposizione AbortController. Node.js gli utenti dovranno usare una libreria Polyfill

 const controller = new AbortController()
 const {result: item} = await items.query('SELECT * from c', { abortSignal: controller.signal});
 controller.abort()

Impostazione della velocità effettiva inclusa nell'operazione di creazione del database/contenitore

const { database }  = client.databases.create({ id: 'my-database', throughput: 10000 })
database.containers.create({ id: 'my-container', throughput: 10000 })

@azure/cosmos-sign

La generazione del token di intestazione è stata suddivisa in una nuova libreria, @azure/cosmos-sign. Chiunque chiami direttamente l'API REST di Azure Cosmos DB può usarlo per firmare le intestazioni usando lo stesso codice chiamato all'interno @azure/cosmosdi .

UUID per ID generati

Nella versione 2 era disponibile codice personalizzato per la generazione di ID elemento. È stata eseguita la transizione all'UUID della libreria della community, già noto e correttamente gestito.

Stringhe di connessione

È ora possibile passare un stringa di connessione copiato dal portale di Azure:

const client = new CosmosClient("AccountEndpoint=https://test-account.documents.azure.com:443/;AccountKey=c213asdasdefgdfgrtweaYPpgoeCsHbpRTHhxuMsTaw==;")
Add DISTINCT and LIMIT/OFFSET queries (#306)
 const { results } = await items.query('SELECT DISTINCT VALUE r.name FROM ROOT').fetchAll()
 const { results } = await items.query('SELECT * FROM root r OFFSET 1 LIMIT 2').fetchAll()

Esperienza browser migliorata

Anche se era possibile usare l'SDK v2 nel browser, non era un'esperienza ideale. È necessario riempire diverse librerie predefinite di Node.js e usare un bundler come webpack o Parcel. Con l'SDK V3 l'esperienza d'uso del browser risulta considerevolmente migliorata.

  • Sono stati sostituiti alcuni elementi interni request con fetch (n. 245)
  • È stato rimosso l'utilizzo del buffer (n. 330)
  • È stato eliminato l'utilizzo predefinito del nodo a favore di pacchetti/API universali (#328)
  • Si è passati a node-abort-controller (n. 294)

Correzioni di bug

  • È stata corretta la lettura di offerte e sono stati ripristinati i test delle offerte (#224)
  • È stato corretto EnableEndpointDiscovery (n. 207)
  • Sono state corrette le unità riservate nei risultati impaginati (n. 360)
  • È stato esteso il tipo di parametro delle query SQL (n. 346)
  • È stata aggiunta la durata TTL a ItemDefinition (n. 341)
  • Sono state corrette le metriche delle query CP (n. 311)
  • È stato aggiunto activityId a FeedResponse (n. 293)
  • Il tipo_ts è stato convertito da stringa a numero (n. 252)(n. 295)
  • È stata corretta l'aggregazione di addebiti delle richieste (n. 289)
  • Sono state consentite chiavi di partizione di stringhe vuote (n. 277)
  • È stata aggiunta una stringa al tipo di query dei conflitti (n. 237)
  • È stato aggiunto uniqueKeyPolicy al contenitore (n. 234)

Sistemi di ingegneria

Non sempre riguardano le modifiche più visibili, ma consentono al personale di fornire più rapidamente codice migliore.

  • È stato usato il rollup per le build di produzione (n. 104)
  • Aggiornamento a TypeScript 3.5 (#327)
  • È stata eseguita la conversione a riferimenti di progetti TS. È stata estratta la cartella di test (n. 270)
  • Sono stati abilitati noUnusedLocals e noUnusedParameters (n. 275)
  • File YAML di Azure Pipelines per build CI (n. 298)

Date di rilascio e di ritiro

Microsoft invia una notifica almeno 12 mesi prima del ritiro di un SDK per agevolare la transizione a una versione più recente o supportata. Le nuove funzionalità e funzionalità e ottimizzazioni vengono aggiunte solo all'SDK corrente, in quanto è consigliabile eseguire sempre l'aggiornamento alla versione più recente dell'SDK il prima possibile. Per altre informazioni, leggere i criteri di supporto tecnico Microsoft per gli SDK.

Versione Data di rilascio Data di ritiro
v3 28 giugno 2019 ---
v2 24 settembre 2018 24 settembre 2021
v1 08 aprile 2015 30 agosto 2020

Domande frequenti

In che modo si viene avvisati del ritiro degli SDK?

Microsoft invierà un preavviso di 12 mesi prima fine del supporto dell'SDK in fase di ritiro per agevolare la transizione a un SDK supportato. Verrà inviata una notifica tramite diversi canali di comunicazione, ossia il portale di Azure, gli aggiornamenti di Azure e la comunicazione diretta con gli amministratori del servizio assegnati.

È possibile creare applicazioni usando una versione di Azure Cosmos DB SDK che sta per essere ritirata durante il periodo di 12 mesi?

Sì, durante il periodo di preavviso di 12 mesi sarà possibile creare, distribuire e modificare applicazioni usando la versione di Azure Cosmos DB SDK che sta per essere ritirata. Durante il periodo di preavviso di 12 mesi, è consigliabile eseguire la migrazione a una versione più recente supportata di Azure Cosmos DB SDK.

Dopo la data di ritiro, che cosa succede alle applicazioni che usano una versione di Azure Cosmos DB SDK non supportata?

Dopo la data di ritiro, Azure Cosmos DB non eseguirà più correzioni dei bug, non aggiungerà nuove funzionalità, né fornirà supporto per le versioni ritirate dell'SDK. Se si preferisce non eseguire l'aggiornamento, le richieste inviate dalle versioni ritirate dell'SDK continueranno a essere gestite dal servizio Azure Cosmos DB.

Quali versioni dell'SDK avranno le funzionalità e gli aggiornamenti più recenti?

Le nuove funzionalità e gli aggiornamenti verranno aggiunti solo alla versione secondaria più recente della versione principale più recente supportata dell'SDK. È consigliabile usare sempre la versione più recente per sfruttare le nuove funzionalità, i miglioramenti delle prestazioni e le correzioni dei bug. Se si usa una versione di SDK precedente, non ritirata, le richieste inviate ad Azure Cosmos DB continueranno a funzionare, ma non sarà possibile accedere alle nuove funzionalità.

Come si deve procedere se non è possibile aggiornare l'applicazione prima della data del ritiro?

Si consiglia di effettuare l'aggiornamento alla versione di SDK più recente quanto prima. Una volta che un SDK è stato contrassegnato per il ritiro, si avranno a disposizione 12 mesi per aggiornare l'applicazione. Se non si è in grado di eseguire l'aggiornamento entro la data di ritiro, le richieste inviate dalle versioni ritirate dell'SDK continueranno a essere gestite da Azure Cosmos DB, quindi le applicazioni in esecuzione continueranno a funzionare. Tuttavia, Azure Cosmos DB non eseguirà più correzioni dei bug, non aggiungerà nuove funzionalità, né non fornirà supporto per le versioni ritirate dell'SDK.

Se si ha un piano di supporto e si richiede supporto tecnico, contattare Microsoft inviando un ticket di supporto.

Come è possibile richiedere l'aggiunta di funzionalità a un SDK o a un connettore?

Le nuove funzionalità non vengono sempre aggiunte immediatamente a ogni SDK o connettore. Se non è supportata una funzionalità che si vuole aggiungere, aggiungere commenti e suggerimenti al forum della community.

Vedi anche

Per altre informazioni su Azure Cosmos DB, vedere la pagina del servizio Microsoft Azure Cosmos DB .