Azure Cosmos DB Node.js SDK voor API voor NoSQL: opmerkingen bij de release en resources

VAN TOEPASSING OP: NoSQL

• .NET SDK v3
• .NET SDK v2
• .NET Core SDK v2
• .NET wijzigingenfeed-SDK v2
• Node.js
• Java SDK v4
• Java SDK v2 synchroniseren
• Async Java SDK v2
• Spring Data v2
• Spring Data v3
• Spring Data v5
• Python
• Go
• REST
• REST-resourceprovider
• SQL
• Bulkuitvoerprogramma - .NET v2
• Bulkuitvoerprogramma - Java

Bron	Koppeling
Download-SDK	@azure/cosmos
API-documentatie	Naslagdocumentatie voor JavaScript SDK
INSTALLATIE-instructies voor SDK	npm install @azure/cosmos
Bijdragen aan SDK	Gids voor bijdragen voor azure-sdk-for-js-opslagplaats
Voorbeelden	codevoorbeelden Node.js
Zelfstudie Aan de slag	Aan de slag met de JavaScript SDK
Zelfstudie voor web-apps	Een Node.js-webtoepassing bouwen met behulp van Azure Cosmos DB
Huidige ondersteunde Node.js platforms	LTS-versies van Node.js

Opmerkingen bij de release

Releasegeschiedenis wordt onderhouden in de opslagplaats azure-sdk-for-js, voor een gedetailleerde lijst met releases, zie het changelog-bestand.

Migratiehandleiding voor belangrijke wijzigingen

Als u een oudere versie van de SDK gebruikt, is het raadzaam om te migreren naar de versie 3.0. In deze sectie worden de verbeteringen beschreven die u krijgt met deze versie en de opgeloste fouten in de versie 3.0.

Verbeterde clientconstructoropties

Constructoropties zijn vereenvoudigd:

• masterKey heeft de naam van de sleutel gewijzigd en is verplaatst naar het hoogste niveau
• Eigenschappen eerder onder options.auth zijn verplaatst naar het hoogste niveau

// 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"
})

Vereenvoudigde query-iterator-API

In v2 zijn er veel verschillende manieren om resultaten van een query te herhalen of op te halen. We hebben geprobeerd de v3-API te vereenvoudigen en vergelijkbare of dubbele API's te verwijderen:

• Verwijder iterator.next() en iterator.current(). Gebruik fetchNext() om pagina's met resultaten op te halen.
• Verwijder iterator.forEach(). Gebruik in plaats daarvan asynchrone iterators.
• iterator.executeNext() hernoemd naar iterator.fetchNext()
• iterator.toArray() hernoemd in iterator.fetchAll()
• Pagina's zijn nu de juiste antwoordobjecten in plaats van gewone JS-objecten
• 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)
}

Vaste containers worden nu gepartitioneerd

De Azure Cosmos DB-service ondersteunt nu partitiesleutels voor alle containers, inclusief de containers die eerder zijn gemaakt als vaste containers. De v3 SDK wordt bijgewerkt naar de nieuwste API-versie waarmee deze wijziging wordt geïmplementeerd, maar deze wordt niet onderbroken. Als u geen partitiesleutel opgeeft voor bewerkingen, wordt standaard een systeemsleutel gebruikt die werkt met al uw bestaande containers en documenten.

Upsert verwijderd voor opgeslagen procedures

Eerder was upsert toegestaan voor niet-gepartitioneerde verzamelingen, maar met de API-versie-update worden alle verzamelingen gepartitioneerd, zodat deze volledig zijn verwijderd.

Itemleesbewerkingen worden niet gegooid op 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') }

Standaardschrijfbewerkingen voor meerdere regio's

De SDK schrijft nu standaard naar meerdere regio's als uw Azure Cosmos DB-configuratie dit ondersteunt. Dit was eerder opt-in-gedrag.

Juiste foutobjecten

Mislukte aanvragen veroorzaken nu de juiste fout- of subklassen van fout. Voorheen gooiden ze gewone JS-objecten.

Nieuwe functies

Door de gebruiker geannuleerde aanvragen

Door intern op te halen, kunnen we de browser AbortController-API gebruiken om door de gebruiker geannuleerde bewerkingen te ondersteunen. In het geval van bewerkingen waarbij meerdere aanvragen mogelijk worden uitgevoerd (zoals query's voor meerdere partities), worden alle aanvragen voor de bewerking geannuleerd. Moderne browsergebruikers hebben abortController al. Node.js gebruikers een Polyfill-bibliotheek moeten gebruiken

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

Doorvoer instellen als onderdeel van de bewerking db/container maken

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

@azure/cosmos-sign

Het genereren van headertoken is opgesplitst in een nieuwe bibliotheek. @azure/cosmos-sign Iedereen die de Azure Cosmos DB REST API aanroept, kan dit rechtstreeks gebruiken om headers te ondertekenen met dezelfde code die we binnen aanroepen @azure/cosmos.

UUID voor gegenereerde id's

v2 had aangepaste code voor het genereren van item-id's. We zijn overgeschakeld naar de bekende en onderhouden communitybibliotheek uuid.

Verbindingsreeksen

Het is nu mogelijk om een verbindingsreeks door te geven die is gekopieerd uit Azure Portal:

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

Verbeterde browserervaring

Hoewel het mogelijk was om de v2 SDK in de browser te gebruiken, was het geen ideale ervaring. U moest polyfill verschillende Node.js ingebouwde bibliotheken en een bundel zoals webpack of Parcel gebruiken. De v3 SDK maakt de out-of-the-box-ervaring veel beter voor browsergebruikers.

• Interne aanvragen vervangen door ophalen (#245)
• Gebruik van buffer verwijderen (#330)
• Ingebouwde knooppuntgebruik verwijderen ten gunste van universele pakketten/API's (#328)
• Overschakelen naar node-abort-controller (#294)

Bugfixes

• Aanbieding lezen en terugbrengen van aanbiedingstests herstellen (#224)
• EnableEndpointDiscovery herstellen (#207)
• Ontbrekende RU's in gepagineerde resultaten herstellen (#360)
• Sql-queryparametertype uitvouwen (#346)
• TTL toevoegen aan ItemDefinition (#341)
• Metrische gegevens van CP-query's oplossen (#311)
• ActivityId toevoegen aan FeedResponse (#293)
• Schakel _ts type van tekenreeks naar getal (#252)(#295)
• Aggregatie van aanvraagkosten oplossen (#289)
• Lege tekenreekspartitiesleutels toestaan (#277)
• Tekenreeks toevoegen aan conflictquerytype (#237)
• UniqueKeyPolicy toevoegen aan container (#234)

Technische systemen

Niet altijd de meest zichtbare wijzigingen, maar ze helpen ons team betere code te verzenden, sneller.

• Rollup gebruiken voor productieversies (#104)
• Bijwerken naar TypeScript 3.5 (#327)
• Converteren naar TS-projectverwijzingen. Testmap extraheren (#270)
• NoUnusedLocals en noUnusedParameters (#275) inschakelen
• YAML voor Azure Pipelines voor CI-builds (#298)

Release- en buitengebruikstellingsdatums

Microsoft biedt ten minste 12 maanden voordat een SDK wordt buiten gebruik gesteld om de overgang naar een nieuwere/ondersteunde versie te vlakken. Nieuwe functies en functionaliteit en optimalisaties worden alleen toegevoegd aan de huidige SDK. Daarom wordt u aangeraden altijd zo vroeg mogelijk een upgrade uit te voeren naar de nieuwste SDK-versie. Lees het Microsoft Ondersteuning-beleid voor SDK's voor meer informatie.

Versie	Releasedatum	Buitengebruikstellingsdatum
v3	28 juni 2019	---
v2	24 september 2018	24 september 2021
v1	08 april 2015	30 augustus 2020

Veelgestelde vragen

Hoe word ik op de hoogte gesteld van de buitengebruikstelling van de SDK?

Microsoft zal u 12 maanden vóór het einde van de ondersteuning op de hoogte stellen van de buitengebruikstelling van de SDK om een soepele overgang naar een ondersteunde SDK te vergemakkelijken. We sturen u een melding via verschillende communicatiekanalen: de Azure Portal, Azure-updates en rechtstreekse communicatie met toegewezen servicebeheerders.

Kan ik toepassingen maken met behulp van de Azure Cosmos DB SDK die buiten gebruik gesteld zal worden gedurende de periode van 12 maanden?

Ja, u kunt toepassingen ontwerpen, implementeren en wijzigen met behulp van de Azure Cosmos DB SDK die buiten gebruik gesteld zal worden, gedurende de periode van 12 maanden. Wij raden u aan, indien van toepassing, te migreren naar een nieuwere, ondersteunde versie van de Azure Cosmos DB SDK gedurende de kennisgevingsperiode van 12 maanden.

Wat gebeurt er na de buitengebruikstellingsdatum met de toepassingen die de niet-ondersteunde Azure Cosmos DB SDK gebruiken?

Na de buitengebruikstellingsdatum lost Azure Cosmos DB geen problemen meer op, voegt geen nieuwe functies meer toe en levert geen ondersteuning meer voor de buiten gebruik gestelde SDK-versies. Als u liever geen upgrade uitvoert, worden aanvragen die zijn verzonden vanaf de buiten gebruik gestelde versies van de SDK nog steeds behandeld door de Azure Cosmos DB-service.

Welke SDK-versies hebben de nieuwste functies en updates?

Nieuwe functies en updates worden alleen toegevoegd aan de meest recente secundaire versie van de meest recente ondersteunde primaire SDK-versie. Wij raden aan altijd de nieuwste versie te gebruiken om te profiteren van nieuwe functies, prestatieverbeteringen en oplossingen voor problemen. Als u een oude, niet buiten gebruik gestelde versie van de SDK gebruikt, zullen uw aanvragen voor Azure Cosmos DB nog steeds werken, maar hebt u geen toegang tot nieuwe mogelijkheden.

Wat moet ik doen als ik mijn toepassing niet kan bijwerken vóór een afsluitdatum?

Wij raden u aan zo snel mogelijk een upgrade naar de nieuwste SDK uit te voeren. Nadat een SDK is gelabeld voor buitengebruikstelling, hebt u 12 maanden om de toepassing bij te werken. Als u niet kunt bijwerken voor de buitengebruikstellingsdatum, worden aanvragen die zijn verzonden vanuit de buiten gebruik gestelde versies van de SDK nog steeds behandeld door Azure Cosmos DB, zodat uw actieve toepassingen blijven functioneren. Maar Azure Cosmos DB lost geen problemen meer op, voegt geen nieuwe functies meer toe en levert geen ondersteuning meer voor de buiten gebruik gestelde SDK-versies.

Als u een ondersteuningsplan hebt en technische ondersteuning nodig hebt, neem contact met ons op door een ondersteuningsticket in te vullen.

Hoe kan ik aanvragen dat functies worden toegevoegd aan een SDK of connector?

Nieuwe functies worden niet altijd onmiddellijk toegevoegd aan elke SDK of connector. Als er geen functie wordt ondersteund die u wilt toevoegen, kunt u feedback toevoegen aan ons communityforum.

Zie ook

Zie de servicepagina van Microsoft Azure Cosmos DB voor meer informatie over Azure Cosmos DB .