Kit SDK Node.js Azure Cosmos DB pour l’API pour NoSQL : notes de publication et ressources

  • Article

S’APPLIQUE À : NoSQL

Ressource Lien
Télécharger le SDK @azure/cosmos
Documentation de l’API Documentation de référence sur le SDK JavaScript
Instructions d’installation du SDK npm install @azure/cosmos
Contribuer au SDK Guide de contribution pour le référentiel azure-sdk-for-js
Exemples Exemples de code Node.js
Tutoriel pour bien démarrer Bien démarrer avec le SDK JavaScript
Tutoriel basé sur une application web Générer une application web Node.js à l’aide d’Azure Cosmos DB
Plates-formes Node.js prise en charge actuelles Versions LTS de Node.js

Notes de publication

L’historique des versions est conservé dans le référentiel azure-sdk-for-js. Pour obtenir une liste détaillée des versions, consultez le fichier d’historique des versions.

Guide de migration pour les changements cassants

Si vous avez une version antérieure du SDK, il est recommandé de migrer vers la version 3.0. Cette section détaille les améliorations que vous apporteriez avec cette version et les corrections de bogues apportées à la version 3.0.

Amélioration des options du constructeur client

Les options du constructeur ont été simplifiées :

  • masterKey a été renommé key et a été déplacée vers le niveau supérieur
  • Les propriétés qui se trouvaient précédemment sous options.auth ont été déplacées vers le niveau supérieur
// 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"
})

Simplification de l’API itérateur de requête

Dans la version v2, il existait de nombreuses façons d’itérer ou de récupérer les résultats d’une requête. Nous avons tenté de simplifier l’API v3 et de supprimer les API similaires ou en double :

  • Suppression d’iterator.next() et d’iterator.current(). Utilisez fetchNext() pour obtenir des pages de résultats.
  • Suppression d’iterator.forEach(). Utilisez des itérateurs asynchrones à la place.
  • Renommage d’iterator.executeNext() en iterator.fetchNext()
  • Renommage d’iterator.toArray() en iterator.fetchAll()
  • Les pages sont désormais des objets de réponse appropriés plutôt que des objets JavaScript simples
  • 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)
}

Les conteneurs fixes sont maintenant partitionnés

Le service Azure Cosmos DB prend désormais en charge les clés de partition sur tous les conteneurs, notamment ceux précédemment créés en tant que conteneurs fixes. Le SDK v3 est mis à jour vers la dernière version de l’API qui implémente ce changement, qui n’est toutefois pas cassant. Si vous ne fournissez pas de clé de partition pour les opérations, nous utiliserons par défaut une clé système qui fonctionne avec tous vos conteneurs et documents existants.

Suppression de l’upsert pour les procédures stockées

Auparavant, l’upsert était autorisé pour les collections non partitionnées, mais avec la mise à jour de la version de l’API, toutes les collections sont partitionnées. Nous l’avons donc entièrement supprimé.

Les lectures d’éléments ne produiront pas d’erreurs 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') }

Écriture multirégion par défaut

Le SDK écrira désormais par défaut dans plusieurs régions si votre configuration Azure Cosmos DB prend en charge cette capacité. Ce comportement était auparavant optionnel.

Objets d’erreur appropriés

Les requêtes ayant échoué lèvent désormais l’erreur ou les sous-classes d’erreur appropriées. Avant, elles levaient des objets JavaScript simples.

Nouvelles fonctionnalités

Requêtes annulables par l’utilisateur

Le passage à la récupération en interne nous permet d’utiliser l’API AbortController du navigateur pour prendre en charge les opérations annulables par l’utilisateur. Dans le cas d’opérations où plusieurs requêtes sont potentiellement en cours (comme les requêtes entre partitions), toutes les requêtes pour l’opération sont annulées. Les utilisateurs de navigateurs récents disposeront déjà d’AbortController. Les utilisateurs Node.js devront utiliser une bibliothèque Polyfills

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

Définition du débit dans le cadre de l’opération de création d’une base de données/d’un conteneur

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

@azure/cosmos-sign

La génération d’un jeton d’en-tête a été divisée pour être incluse dans une nouvelle bibliothèque, @azure/cosmos-sign. Toute personne appelant l’API REST Azure Cosmos DB directement peut utiliser cela pour signer des en-têtes avec le même code que celui que nous appelons dans @azure/cosmos.

UUID des ID générés

La version v2 avait du code personnalisé pour générer des ID d’élément. Nous sommes passés à l’UUID bien connu et gérée de la bibliothèque de communauté.

Chaînes de connexion

Il est maintenant possible de transmettre une chaîne de connexion copiée à partir du portail 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()

Amélioration de l’expérience de navigateur

Bien qu’il était possible d’utiliser le SDK v2 dans le navigateur, cette expérience n’était pas optimale. Vous deviez effectuer un polyfill sur plusieurs bibliothèques intégrées node.js et utiliser un programme d’installation d’offre groupée (bundler) comme webpack ou Parcel. Le SDK v3 améliore considérablement l’expérience prête pour les utilisateurs de navigateur.

  • Remplacement des éléments internes des requêtes par la récupération (fetch) (n° 245)
  • Suppression de l’utilisation d’un tampon (n° 330)
  • Suppression de l’utilisation intégrée de nœuds en faveur de packages universels/d’API (n° 328)
  • Passage à un contrôleur des abandons de nœuds (n° 294)

Résolution des bogues

  • Correction de la lecture des offres et rétablissement des tests de l’offre (n° 224)
  • Correction d’EnableEndpointDiscovery (n° 207)
  • Correction du unités de requête manquantes sur les résultats paginés (n° 360)
  • Développement du type de paramètre de requête SQL (n° 346)
  • Ajout de TTL à ItemDefinition (n° 341)
  • Correction des métriques de requête de processeur central (n° 311)
  • Ajout d’activityId à FeedResponse (n° 293)
  • Changement du type _ts de chaîne en nombre (n° 252) (n° 295)
  • Correction de l’agrégation des frais de requêtes (n° 289)
  • Autorisation des clés de partition de chaîne vides (n° 277)
  • Ajout d’une chaîne au type de requête de conflit (n° 237)
  • Ajout d’uniqueKeyPolicy à un conteneur (n° 234)

Systèmes d’ingénierie

Ce ne sont pas toujours les changements les plus visibles, mais ils permettent à notre équipe à livrer plus rapidement un meilleur code.

  • Utilisation d’un correctif cumulatif pour les builds de production (n° 104)
  • Mise à jour vers TypeScript 3.5 (n° 327)
  • Conversion en références de projet TS. Extraction du dossier de test (n° 270)
  • Activation de noUnusedLocals et de noUnusedParameters (n° 275)
  • YAML Azure Pipelines pour les builds d’intégration continue (CI) (n° 298)

Dates de lancement et de suppression

Microsoft envoie une notification au moins 12 mois avant le retrait d’un Kit de développement logiciel (SDK) pour faciliter la transition vers une version plus récente/prise en charge. Les nouvelles fonctionnalités et fonctions, et les optimisations sont uniquement ajoutées au kit SDK actuel. Par conséquent, il est recommandé de toujours passer à la dernière version du SDK dès que possible. Pour plus d’informations, consultez la stratégie de support Microsoft des SDK.

Version Date de sortie Date de suppression
v3 28 juin 2019 ---
v2 24 septembre 2018 24 septembre 2021
v1 8 avril 2015 30 août 2020

Questions fréquentes (FAQ)

Comment serai-je informé du retrait du kit SDK ?

Microsoft vous avertit 12 mois à l’avance de la fin de la prise en charge d’un kit SDK mis hors service afin de favoriser une transition en douceur vers un kit SDK pris en charge. Nous vous informons via différents canaux de communication : le portail Azure, les mises à jour Azure et une communication directe avec les administrateurs de service affectés.

Pendant cette période de 12 mois, puis-je créer des applications à l’aide d’un kit SDK Azure Cosmos DB destiné à être mis hors service ?

Oui, au cours de la période de préavis de 12 mois, vous pouvez créer, déployer et modifier des applications à l’aide du kit SDK Azure Cosmos DB destiné à être mis hors service. Nous vous conseillons de migrer vers une version prise en charge plus récente du kit SDK Azure Cosmos DB pendant cette période de 12 mois, le cas échéant.

Après la date de mise hors service, qu’advient-il des applications qui utilisent le kit SDK Azure Cosmos DB non pris en charge ?

Après la date de mise hors service, Azure Cosmos DB n’apporte plus de correctifs de bogues, n’ajoute plus de nouvelles fonctionnalités et ne fournit plus de support aux versions mises hors service du kit SDK. Si vous préférez ne pas effectuer la mise à niveau, les requêtes envoyées depuis les versions mises hors service du Kit de développement logiciel (SDK) continueront d’être traitées par le service Azure Cosmos DB.

Quelles versions du kit SDK disposent des dernières fonctionnalités et mises à jour ?

Les nouvelles fonctionnalités et mises à jour ne sont ajoutées qu’à la dernière version mineure de la dernière version majeure prise en charge du kit SDK. Nous vous recommandons de toujours utiliser la dernière version pour tirer parti des nouvelles fonctionnalités, des améliorations des performances et des correctifs de bogues. Si vous utilisez une ancienne version du kit SDK encore en service, vos requêtes vers Azure Cosmos DB continuent de fonctionner, mais vous n’avez accès à aucune des nouvelles fonctionnalités.

Que faire si je ne parviens pas à mettre à jour mon application avant la date limite ?

Nous vous recommandons de mettre à niveau vers la dernière version du kit de développement logiciel dès que possible. Une fois qu’un kit SDK est marqué pour la mise hors service, vous avez 12 mois pour mettre à jour votre application. Si vous n’êtes pas en mesure de procéder à une mise à jour avant la date de mise hors service, les requêtes envoyées à partir des versions mises hors service du kit SDK continuent d’être traitées par Azure Cosmos DB. Vos applications continuent donc de fonctionner. Toutefois, Azure Cosmos DB n’apporte plus de correctifs de bogues, n’ajoute plus de nouvelles fonctionnalités et ne fournit plus de support aux versions mises hors service du kit SDK.

Si vous disposez d’un plan de support et avez besoin d’assistance technique, veuillez nous contacter en remplissant un ticket de support.

Comment puis-je demander l’ajout de fonctionnalités à un SDK ou un connecteur ?

Les nouvelles fonctionnalités ne sont pas toujours ajoutées à chaque SDK ou connecteur immédiatement. S’il existe une fonctionnalité non prise en charge que vous souhaitez ajouter, ajoutez des commentaires à notre forum communautaire.

Voir aussi

Pour en savoir plus sur Azure Cosmos DB, consultez la page du service Microsoft Azure Cosmos DB.