SDK para Node.js de Azure Cosmos DB para la API para NoSQL: notas de la versión y recursos

  • Artículo

SE APLICA A: NoSQL

Resource Vínculo
Descargar SDK @azure/cosmos
Documentación de la API Documentación de referencia del SDK de JavaScript
Instrucciones de instalación del SDK npm install @azure/cosmos
Contribuya al SDK Guía de contribución para el repositorio azure-sdk-for-js
Ejemplos Ejemplos de código Node.js
Tutorial de inicio Introducción al SDK de JavaScript
Tutorial de la aplicación web Creación de una aplicación web de Node.js con Azure Cosmos DB
Plataformas Node.js compatibles actuales Versiones de LTS de Node.js

Notas de la versión

El historial de versiones se mantiene en el repositorio azure-sdk-for-js. Para obtener una lista detallada de las versiones, vea el archivo changelog.

Guía de migración para cambios con un impacto importante

Si se trata de una versión anterior del SDK, se recomienda migrar a la versión 3.0. En esta sección se detallan las mejoras que se obtienen con esta versión y las correcciones de errores realizadas en la versión 3.0.

Opciones de constructor de cliente mejoradas

Las opciones de constructor se han simplificado:

  • Se ha cambiado el nombre de la clave masterKey y se ha movido al nivel superior.
  • Las propiedades que antes estaban en options.auth se han movido al nivel superior.
// 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"
})

API de iterador de consultas simplificada

En la versión 2, había muchas formas diferentes de iterar o recuperar los resultados de una consulta. Hemos intentado simplificar la API v3 y quitar API similares o duplicadas:

  • Quitar iterator.next() e iterator.current(). Usar fetchNext() para obtener páginas de resultados.
  • Quitar iterator.forEach(). Usar iteradores asincrónicos en su lugar.
  • Se ha cambiado el nombre de iterator.executeNext() a iterator.fetchNext().
  • Se ha cambiado el nombre de iterator.toArray() a iterator.fetchAll().
  • Ahora las páginas son objetos de respuesta adecuados en lugar de objetos de JS estándar.
  • 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)
}

Los contenedores fijos ahora tienen particiones

El servicio Azure Cosmos DB ahora admite claves de partición en todos los contenedores, incluidos los que se habían creado como contenedores fijos. El SDK v3 se actualiza a la última versión de la API que implementa este cambio, pero no tiene un impacto importante. Si no proporciona una clave de partición para las operaciones, se usará de forma predeterminada una clave del sistema que funcione con todos los contenedores y documentos actuales.

Se ha quitado upsert para procedimientos almacenados

Antes se permitía upsert para colecciones sin particiones, pero, con la actualización de la versión de la API, todas las colecciones se particionan, así que se ha quitado por completo.

Las lecturas del elemento no arrojan 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') }

Escrituras en varias regiones predeterminadas

Ahora el SDK escribirá en varias regiones de forma predeterminada si la configuración de Azure Cosmos DB lo admite. Antes este era un comportamiento opcional.

Objetos de error correctos

Ahora las solicitudes que no se pueden ejecutar devuelven un error o subclases de error correctos. Antes devolvían objetos de JS estándar.

Nuevas características

Solicitudes que puede cancelar el usuario

El cambio a la recuperación de cambios interna nos permite usar la API AbortController del explorador para admitir operaciones que puede cancelar el usuario. En el caso de las operaciones en las que puede haber varias solicitudes en curso (como las consultas entre particiones), se cancelarán todas las solicitudes de la operación. Los usuarios de los nuevos exploradores ya tendrán AbortController. Los usuarios de Node.js deberán usar una biblioteca de Polyfill.

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

Establecer el procesamiento como parte de la operación de creación de una base de datos o un contenedor

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

@azure/cosmos-sign

La generación de tokens de encabezado se ha separado en una biblioteca nueva, @azure/cosmos-sign. Cualquiera que llame directamente a la API REST de Azure Cosmos DB puede utilizarla para firmar encabezados con el mismo código que se llama en @azure/cosmos.

UUID para identificadores generados

La versión 2 tenía código personalizado para generar id. de elemento. Hemos cambiado al conocido y mantenido UUID de biblioteca de la comunidad.

Cadenas de conexión

Ahora se puede pasar una cadena de conexión copiada de 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()

Experiencia de explorador mejorada

Aunque antes se podía usar el SDK v2 en el explorador, no era una experiencia idónea. Había que usar Polyfill en varias bibliotecas integradas de Node.js y un empaquetador, como Webpack o Parcel. El SDK v3 mejora la experiencia de configuración rápida para los usuarios de explorador.

  • Reemplazar los componentes internos de las solicitudes con fetch (#245).
  • Quitar el uso de búfer (#330).
  • Quitar el uso integrado de nodos en favor de paquetes universales o API (#328).
  • Cambiar a node-abort-controller (#294).

Corrección de errores

  • Corregir la lectura de las ofertas y restablecer las pruebas de ofertas (#224).
  • Corregir EnableEndpointDiscovery (#207).
  • Corregir las RU que faltan en los resultados paginados (#360).
  • Expandir el tipo de parámetro de consulta SQL (#346).
  • Agregar TTL a ItemDefinition (#341).
  • Corregir las métricas de las consultas de CP (#311).
  • Agregar activityId a FeedResponse (#293).
  • Cambiar el tipo de _ts de cadena a número (#252)(#295).
  • Corregir la agregación de cargos de solicitudes (#289).
  • Permitir claves de partición de cadenas en blanco (#277).
  • Agregar cadena al tipo de consulta de conflicto (#237).
  • Agregar uniqueKeyPolicy al contenedor (#234).

Sistemas de ingeniería

No son siempre los cambios más visibles, pero ayudan a nuestro equipo a distribuir un código de más calidad en menos tiempo.

  • Usar rollup para compilaciones de producción (#104).
  • Actualización a TypeScript 3.5 (#327)
  • Convertir en referencias de proyecto de TS. Extraer la carpeta de prueba (#270).
  • Habilitar noUnusedLocals y noUnusedParameters (#275).
  • Azure Pipelines YAML para las compilaciones de CI (#298).

Fechas de lanzamiento y de retirada

Microsoft notifica la retirada de un SDK con al menos 12 meses de antelación para facilitar la transición a una versión compatible o más reciente. Solo se agregan nuevas características, funcionalidad y optimizaciones al SDK actual, por lo que se recomienda actualizar siempre a la última versión del SDK tan pronto como sea posible. Lea la Directiva de soporte técnico de Microsoft para los SDK para obtener más detalles.

Versión Fecha de la versión Fecha de retirada
v3 28 de junio de 2019 ---
v2 24 de septiembre de 2018 24 de septiembre de 2021
v1 08 de abril de 2015 30 de agosto de 2020

Preguntas más frecuentes

¿Cómo se me notificará de la retirada del SDK?

Microsoft le notificará 12 meses antes de la finalización del soporte técnico del SDK que se retira para facilitar una transición sin problemas a un SDK compatible. Se le notificará a través de diversos canales de comunicación: Azure Portal, actualizaciones de Azure y comunicación directa a los administradores de servicios asignados.

¿Puedo crear aplicaciones con un SDK de Azure Cosmos DB que se retirará durante el período de 12 meses?

Sí, podrá crear, implementar y modificar aplicaciones mediante el SDK de Azure Cosmos DB que se retirará durante el período de aviso de 12 meses. Se recomienda que migre a una versión compatible más reciente del SDK de Azure Cosmos DB durante el período de aviso de 12 meses, según corresponda.

Tras la fecha de retirada, ¿qué ocurre con las aplicaciones que usan el SDK de Azure Cosmos DB no compatible?

Después de la fecha de retirada, Azure Cosmos DB ya no hará correcciones de errores, ni agregará nuevas características, ni proporcionará soporte técnico para las versiones del SDK retiradas. Si prefiere no realizar la actualización, el servicio Azure Cosmos DB seguirá atendiendo las solicitudes enviadas desde las versiones retiradas del SDK.

¿Qué versiones del SDK tendrán las características y actualizaciones más recientes?

Se agregarán nuevas características y actualizaciones solo a la versión secundaria más reciente de la versión del SDK principal compatible más reciente. Se recomienda que use siempre la versión más reciente para aprovechar las ventajas de las nuevas características, mejoras de rendimiento y correcciones de errores. Si usa una versión anterior del SDK que no se haya retirado, las solicitudes realizadas a Azure Cosmos DB seguirán funcionando, pero no tendrá acceso a las nuevas funcionalidades.

¿Qué debo hacer si no puedo actualizar la aplicación antes de una fecha límite?

Se recomienda que actualice al SDK más reciente tan pronto como sea posible. Después de etiquetar un SDK para su retirada, tendrá 12 meses para actualizar la aplicación. Si no puede realizar la actualización en la fecha de retirada, Azure Cosmos DB seguirá atendiendo las solicitudes enviadas desde las versiones retiradas del SDK, por lo que las aplicaciones en ejecución seguirán funcionando. Aunque Azure Cosmos DB ya no hará correcciones de errores, ni agregará nuevas características ni proporcionará soporte técnico para las versiones del SDK retiradas.

Si tiene un plan de soporte técnico y requiere soporte técnico, póngase en contacto con nosotros al abrir una incidencia de soporte técnico.

¿Cómo puedo solicitar que se agreguen características a un SDK o conector?

No siempre se agregan de inmediato características nuevas a los SDK o conectores. Si no se admite una característica que le gustaría agregar, agregue comentarios a nuestro foro de la comunidad.

Consulte también

Para más información sobre Azure Cosmos DB, consulte la página del servicio Microsoft Azure Cosmos DB.