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

Note di rilascio

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

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 usa una chiave di sistema che funziona con tutti i contenitori e i documenti esistenti.

È stato rimosso l'upsert per le stored procedure

In precedenza upsert era consentito per le raccolte non partizionate, ma con l'aggiornamento della versione dell'API, tutte le raccolte vengono partizionate in modo da rimuoverle completamente.

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 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 devono 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 Azure Cosmos DB può usarlo per firmare le intestazioni usando lo stesso codice chiamato all'interno di @azure/cosmos.

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)
• Azure Pipelines YAML per le compilazioni CI (#298)

Date di rilascio e di ritiro

Microsoft fornisce notifiche almeno 12 mesi prima di ritirare un SDK per consentire la transizione a una versione più recente/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 altri dettagli, leggere i criteri di supporto tecnico Microsoft per gli SDK.

Domande frequenti

In che modo si viene avvisati del ritiro degli SDK?

Microsoft fornirà un preavviso di 12 mesi prima della fine del supporto dell'SDK di ritiro per facilitare una transizione senza problemi a un SDK supportato. Verrà visualizzata una notifica tramite vari canali di comunicazione: il portale di Azure, gli aggiornamenti Azure e la comunicazione diretta agli amministratori del servizio assegnati.

Can I author applications by using a to-be-retired Azure Cosmos DB SDK during the 12-month period?

Sì, sarà possibile creare, distribuire e modificare le applicazioni usando il to-be-ritirato Azure Cosmos DB SDK durante il periodo di preavviso di 12 mesi. È consigliabile eseguire la migrazione a una versione più recente supportata di Azure Cosmos DB SDK durante il periodo di preavviso di 12 mesi, in base alle esigenze.

Dopo la data di ritiro, cosa accade alle applicazioni che usano l'SDK di Azure Cosmos DB non supportato?

Dopo la data di ritiro, Azure Cosmos DB non eseguirà più correzioni di bug, aggiungerà nuove funzionalità o fornirà supporto alle versioni dell'SDK ritirato. Se si preferisce non eseguire l'aggiornamento, le richieste inviate dalle versioni ritirata 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 precedente e non ritirata dell'SDK, le richieste di Azure Cosmos DB funzioneranno ancora, ma non si avrà accesso a 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 è possibile eseguire l'aggiornamento in base alla data di ritiro, le richieste inviate dalle versioni ritirata dell'SDK continueranno a essere gestite da Azure Cosmos DB, quindi le applicazioni in esecuzione continueranno a funzionare. Tuttavia, Azure Cosmos DB non effettuerà più correzioni di bug, aggiungerà nuove funzionalità o fornirà supporto alle versioni dell'SDK ritirato.

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.

Vedere anche

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