Azure Cosmos DB Node.js-SDK für SQL-API: Versionshinweise und Ressourcen

GILT FÜR: SQL-API

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 Cosmos-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 Sie ist nicht unterbrechend. 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.

Bei Lesevorgängen von Elementen wird 404 nicht ausgelöst

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 Cosmos-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 Cosmos-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.

Weitere Informationen

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