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

Versionshinweise

Der Versionsverlauf wird im azure-sdk-for-js-Repository verwaltet, um eine detaillierte Liste der Versionen zu erhalten, 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 für alle Container, einschließlich derjenigen, 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 Vorgänge bereitstellen, verwenden wir standardmäßig einen Systemschlüssel, der mit allen vorhandenen Containern und Dokumenten funktioniert.

Upsert für gespeicherte Prozeduren entfernt

Zuvor war upsert für nicht partitionierte Sammlungen zulässig, aber mit dem API-Versionsupdate werden alle Sammlungen partitioniert, sodass wir es 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 ihre Azure Cosmos DB-Konfiguration sie unterstützt. 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 eine Polyfill-Bibliothek verwenden müssen

 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. Jeder, der die Azure Cosmos DB REST-API direkt aufruft, kann dies verwenden, um Header mit demselben Code zu signieren, den wir in @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 jetzt möglich, eine vom 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)

Fehlerkorrekturen

• 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

Microsoft stellt mindestens 12 Monate vor der Einstellung eines SDKs eine Benachrichtigung bereit, um den Übergang zu einer neueren/unterstützten Version zu glätten. 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. Weitere Informationen finden Sie in der Microsoft-Support-Richtlinie für SDKs.

Häufig gestellte Fragen

Wie werde ich über die Einstellung eines SDK benachrichtigt?

Microsoft wird vor Ablauf des Supports des reaktivierten SDK 12 Monate im Voraus informieren, um einen reibungslosen Übergang zu einem unterstützten SDK zu erleichtern. Wir benachrichtigen Sie über verschiedene Kommunikationskanäle: das Azure-Portal, Azure Updates und die direkte Kommunikation mit zugewiesenen Dienstadministratoren.

Kann ich Anwendungen mithilfe eines to-be-eingestellten Azure Cosmos DB SDK während des Zeitraums von 12 Monaten erstellen?

Ja, Sie können Anwendungen mithilfe des to-be-eingestellten Azure Cosmos DB SDK während des 12-Monat-Benachrichtigungszeitraums erstellen, bereitstellen und ändern. Es wird empfohlen, während des 12-monatigen Kündigungszeitraums zu einer neueren unterstützten Version des Azure Cosmos DB SDK zu migrieren.

Nach dem Deaktivierungsdatum geschieht folgendes mit Anwendungen, die das nicht unterstützte Azure Cosmos DB SDK verwenden?

Nach dem Deaktivierungsdatum werden Azure Cosmos DB keine Fehlerbehebungen mehr vornehmen, neue Features hinzufügen oder Unterstützung für die eingestellten SDK-Versionen bereitstellen. Wenn Sie kein Upgrade durchführen möchten, werden anforderungen, die von den eingestellten Versionen des SDK gesendet werden, weiterhin vom Azure Cosmos DB-Dienst bereitgestellt.

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, nicht eingestellte Version des SDK verwenden, funktionieren Ihre Anforderungen an Azure Cosmos DB weiterhin, aber Sie haben 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 nicht nach dem Einstellungsdatum aktualisieren können, werden anforderungen, die von den eingestellten Versionen des SDK gesendet werden, weiterhin von Azure Cosmos DB bereitgestellt, sodass Ihre ausgeführten Anwendungen weiterhin funktionieren. Aber Azure Cosmos DB werden keine Fehlerbehebungen mehr vornehmen, neue Features hinzufügen oder Unterstützung für die eingestellten SDK-Versionen bereitstellen.

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.

Siehe auch

Weitere Informationen zu Azure Cosmos DB finden Sie auf Microsoft Azure Cosmos DB Service page.