Azure Cosmos DB Node.js SDK v4 für API für NoSQL: Versionshinweise und Ressourcen

GILT FÜR: NoSQL

• .NET SDK v3
• .NET SDK v2
• .NET Core SDK v2
• .NET Change Feed SDK v2
• Node.js
• Java SDK v4
• Sync Java SDK v2
• Async Java SDK v2
• Spring Data v2
• Spring Data v3
• Spring Data v5
• Python
• Go
• REST
• REST-Ressourcenanbieter
• SQL
• Bulk Executor – .NET v2
• Bulk Executor – Java

Resource	Link
Herunterladen des SDK	@azure/cosmos
API-Dokumentation	Referenzdokumentation zum JavaScript SDK
SDK-Installationsanweisungen	npm install @azure/cosmos
Mitwirkung am SDK	Leitfaden zur Mitwirkung am Repository „azure-sdk-for-js“
Beispiele	Node.js-Codebeispiele
Tutorial mit ersten Schritten	Erste Schritte mit dem JavaScript SDK
Tutorial zu Web-Apps	Erstellen einer Node.js-Webanwendung mithilfe von Azure Cosmos DB
Derzeit unterstützte Node.js-Plattformen	LTS-Versionen von Node.js

Anmerkungen zu dieser Version

Der Releaseverlauf wird im Repository „azure-sdk-for-js“ verwaltet. Eine ausführliche Liste der Releases finden Sie in der Datei „changelog“.

Migrationshandbuch für wichtige Änderungen

Wenn Sie eine ältere Version des SDK verwenden, wird die Migration zur Version 3.0 empfohlen. In diesem Abschnitt werden die Verbesserungen, die sie mit dieser Version erhalten, und die in der Version 3.0 vorgenommenen Fehlerbehebungen erläutert.

Clientkonstruktoroptionen verbessert

Konstruktoroptionen wurden vereinfacht:

• masterKey wurde in „key“ umbenannt und auf die oberste Ebene verschoben
• Eigenschaften, die sich zuvor unter „options.auth“ befanden, wurden auf die oberste Ebene verschoben

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

Abfrageiterator-API vereinfacht

In Version 2 gab es viele verschiedene Möglichkeiten, Ergebnisse einer Abfrage zu durchlaufen oder abzurufen. Wir haben versucht, die API der Version 3 zu vereinfachen und ähnliche oder doppelte APIs zu entfernen:

• iterator.next() und iterator.current() entfernt. Verwenden Sie fetchnext(), um Seiten mit Ergebnissen abzurufen.
• Entfernen Sie iterator.forEach(). Verwenden Sie stattdessen asynchrone Iteratoren.
• iterator.executeNext() in iterator.fetchNext() umbenannt
• iterator.toArray() in iterator.fetchAll() umbenannt
• Seiten sind nun ordnungsgemäße Antwortobjekte anstatt einfache JS-Objekte
• 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)
}

Feste Container sind jetzt partitioniert

Der Azure Cosmos DB-Dienst unterstützt jetzt Partitionsschlüssel in allen Containern, einschließlich denjenigen, die zuvor als feste Container erstellt wurden. Das SDK der Version 3 wird auf die neueste API-Version aktualisiert, die diese Änderung implementiert, aber nicht unterbrechend wirkt. Wenn Sie keinen Partitionsschlüssel für den Betrieb bereitstellen, verwenden wir standardmäßig einen Systemschlüssel, der mit allen Ihren vorhandenen Containern und Dokumenten funktioniert.

Upsert für gespeicherte Prozeduren entfernt

Zuvor war Upsert für nicht partitionierte Sammlungen erlaubt, aber mit dem Update der API-Version sind alle Sammlungen partitioniert, sodass wir den Upsert vollständig entfernt haben.

Kein Fehler vom Typ 404 beim Lesen von Elementen

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') }

Standardmäßige Schreibvorgänge in mehreren Regionen

Das SDK schreibt jetzt standardmäßig in mehrere Regionen, wenn dies von ihrer Azure Cosmos DB-Konfiguration unterstützt wird. Dieses Verhalten musste zuvor abonniert werden.

Ordnungsgemäße Fehlerobjekte

Fehlerhafte Anforderungen lösen jetzt den ordnungsgemäßen Fehler oder dessen Unterklassen aus. Zuvor wurden einfache JS-Objekte ausgelöst.

Neue Funktionen

Vom Benutzer abbrechbare Anforderungen

Durch den Umstieg auf internes Abrufen können wir die AbortController-API des Browsers verwenden, um vom Benutzer abbrechbare Vorgänge zu unterstützen. Bei Vorgängen, bei denen möglicherweise mehrere Anforderungen bearbeitet werden (z. B. bei partitionsübergreifende Abfragen), werden alle Anforderungen für den Vorgang abgebrochen. Benutzer moderner Browser verfügen bereits über AbortController. Node.js-Benutzer müssen eine Polyfill-Bibliothek verwenden.

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

Festlegen des Durchsatzes als Teil eines Erstellungsvorgangs für DB/Container

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

@azure/cosmos-sign

Die Generierung von Headertoken wurde in die neue Bibliothek @azure/cosmos-sign verlagert. Aufrufer der Azure Cosmos DB-REST-API können damit Header mit dem gleichen Code signieren, den wir innerhalb von @azure/cosmos aufrufen.

UUID für generierte IDs

Version 2 enthielt benutzerdefinierten Code zum Generieren von Element-IDs. Wir haben auf die bekannte und gepflegte Communitybibliotheks-UUID umgestellt.

Verbindungszeichenfolgen

Es ist nun möglich, eine im Azure-Portal kopierte Verbindungszeichenfolge zu übergeben:

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

Verbesserte Browsererfahrung

Obwohl es möglich war, das SDK von Version 2 im Browser zu verwenden, war dies keine ideale Lösung. Sie mussten mehrere in Node.js integrierte Polyfill-Bibliotheken und einen Bundler wie Webpack oder Parcel verwenden. Mithilfe des SDK von Version 3 ist die Standarderfahrung für Browserbenutzer wesentlich besser.

• Anforderungsinterna durch FETCH (#245) ersetzt
• Verwendung von BUFFER entfernt (#330)
• In Knoten integrierte Verwendung zugunsten universeller Pakete/APIs entfernt (#328)
• Auf node-abort-controller umgestiegen (#294)

Behebung von Programmfehlern

• Angebot zum Lesen korrigiert und erneutes Angebot von Tests (#224)
• EnableEndpointDiscovery korrigiert (#207)
• Fehlende RUs in paginierten Ergebnissen korrigiert (#360)
• SQL-Abfrageparametertyp erweitert (#346)
• ttl zu ItemDefinition hinzugefügt (#341)
• CP-Abfragemetriken korrigiert (#311)
• activityId zu FeedResponse hinzugefügt (#293)
• _ts-Typ von string in number geändert (#252)(#295)
• Aggregation der Belastungsanforderungen korrigiert (#289)
• Partitionsschlüssel mit leeren Zeichenfolgen zulässig (#277)
• Zeichenfolge zum Konfliktabfragetyp hinzugefügt (#237)
• uniqueKeyPolicy zu Container hinzugefügt (#234)

Entwicklungssysteme

Nicht immer die sichtbarsten Änderungen, aber sie helfen unserem Team, schneller besseren Code zu liefern.

• Rollup für Produktionsbuilds verwendet (#104)
• Auf TypeScript 3.5 aktualisiert (#327)
• Zu TS-Projektverweisen konvertiert. Testordner extrahiert (#270)
• noUnusedLocals und noUnusedParameters aktiviert (#275)
• Azure Pipelines YAML für CI-Builds (#298)

Veröffentlichungs- und Deaktivierungstermine

Wenn Microsoft ein SDK deaktiviert, werden Sie mindestens 12 Monate vorher benachrichtigt, um einen reibungslosen Übergang zu einer neueren/unterstützten Version zu gewährleisten. Neue Features, Funktionen und Optimierungen werden nur dem aktuellen SDK hinzugefügt. Daher wird empfohlen, immer so früh wie möglich auf die neueste SDK-Version zu aktualisieren. Ausführlichere Informationen finden Sie in der Microsoft-Supportrichtlinie für SDKs.

Version	Veröffentlichungsdatum	Deaktivierungstermine
V3	28. Juni 2019	---
V2	24. September 2018	24. September 2021
v1	8\. April 2015	30. August 2020

Häufig gestellte Fragen

Wie werde ich über die Einstellung eines SDK benachrichtigt?

Um einen reibungslosen Übergang zu einem unterstützten SDK zu ermöglichen, informiert Microsoft 12 Monate vor Ende des Supports über die Einstellung eines SDK. Sie werden über verschiedene Kommunikationskanäle benachrichtigt: Azure-Portal, Azure-Updates und direkte Kommunikation mit den entsprechenden Dienstadministratoren.

Kann ich mit einem Azure Cosmos DB SDK, das eingestellt werden soll, während der 12-monatigen Frist Anwendungen erstellen?

Ja, mit einem solchen Azure Cosmos DB SDK können Sie während der 12-monatigen Frist Anwendungen erstellen, bereitstellen und ändern. Es wird empfohlen, nach Bedarf innerhalb der 12-monatigen Frist zu einer neueren unterstützten Version des Azure Cosmos DB SDK zu migrieren.

Was geschieht nach dem Einstellungsdatum mit Anwendungen, die das nicht unterstützte Azure Cosmos DB SDK verwenden?

Nach dem Einstellungsdatum werden von Azure Cosmos DB für die eingestellten SDK-Versionen keine Fehlerbehebungen mehr durchgeführt und keine neuen Funktionen hinzugefügt, und es wird auch kein Support mehr dafür angeboten. Wenn Sie kein Upgrade durchführen möchten, werden von den eingestellten Versionen des SDK gesendete Anforderungen weiterhin vom Azure Cosmos DB-Dienst bedient.

Welche SDK-Versionen werden über die neuesten Funktionen und Updates verfügen?

Neue Funktionen und Updates werden nur der aktuellen Nebenversion der neuesten unterstützten SDK-Hauptversion hinzugefügt. Es wird empfohlen, immer die aktuelle Version zu verwenden, um von neuen Funktionen, Leistungsverbesserungen und Fehlerbehebungen zu profitieren. Wenn Sie eine alte, noch nicht eingestellte Version des SDK verwenden, funktionieren Ihre Anforderungen an Azure Cosmos DB weiterhin, Sie haben jedoch keinen Zugriff auf neue Funktionen.

Was muss ich tun, wenn ich meine Anwendung nicht vor einem Stichtag aktualisieren kann?

Es wird empfohlen, so früh wie möglich auf das neueste SDK zu aktualisieren. Nachdem ein SDK für die Einstellung markiert wurde, bleiben Ihnen 12 Monate zur Aktualisierung Ihrer Anwendung. Wenn Sie die Aktualisierung nicht bis zum Einstellungsdatum vornehmen können, werden von den eingestellten Versionen des SDK gesendete Anforderungen weiterhin von Azure Cosmos DB verarbeitet, sodass Ihre ausgeführten Anwendungen weiterhin funktionieren. Für die eingestellten SDK-Versionen werden jedoch von Azure Cosmos DB keine Fehlerbehebungen mehr durchgeführt und keine neuen Funktionen hinzugefügt, und es wird auch kein Support mehr dafür angeboten.

Wenn Sie über einen Supportplan verfügen und technischen Support benötigen, kontaktieren Sie uns, indem Sie ein Supportticket erstellen.

Wie kann ich anfordern, dass Features zu einem SDK oder Connector hinzugefügt werden?

Neue Features werden nicht immer jedem SDK oder Connector sofort hinzugefügt. Wenn eine Funktion, die Ihrer Meinung hinzugefügt werden sollte, nicht unterstützt wird, fügen Sie bitte unserem Communityforum ein Feedback hinzu.

Weitere Informationen

Weitere Informationen zu Azure Cosmos DB finden Sie auf der Seite zum Dienst Microsoft Azure Cosmos DB.