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

Notas de lanzamiento

El historial de versiones se mantiene en el repositorio azure-sdk-for-js para obtener una lista detallada de versiones, consulte 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, incluidas las que se crearon anteriormente 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, el valor predeterminado es una clave del sistema que funciona con todos los contenedores y documentos existentes.

Se ha quitado upsert para procedimientos almacenados

Anteriormente se permitía upsert para colecciones no particionadas, pero con la actualización de la versión de la API, todas las colecciones se particionan por lo que la quitamos 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

El SDK ahora escribirá en varias regiones de forma predeterminada si la configuración de Azure Cosmos DB la 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.

Características nuevas

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. Node.js los usuarios deben 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. Cualquier persona que llame directamente a la API rest de Azure Cosmos DB puede usarla para firmar encabezados con el mismo código al que llamamos dentro de @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 es posible pasar un cadena de conexión copiado desde el portal de 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()

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 compilaciones de CI (298)

Fechas de lanzamiento y de retirada

Microsoft proporciona una notificación al menos 12 meses antes de retirar un SDK para suavizar la transición a una versión más reciente o compatible. 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 Soporte técnico de Microsoft Policy for SDKs para obtener más detalles.

Preguntas más frecuentes

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

Microsoft proporcionará un aviso anticipado de 12 meses antes del final del soporte técnico del SDK de retirada para facilitar una transición fluida a un SDK compatible. Le notificaremos a través de varios canales de comunicación: el portal de Azure, las actualizaciones de Azure y la comunicación directa a los administradores de servicios asignados.

Can I author applications by using a to-be-retired Azure Cosmos DB SDK during the 12-month period?

Sí, podrá crear, implementar y modificar aplicaciones mediante el SDK de to-beretirado Azure Cosmos DB durante el período de aviso de 12 meses. Se recomienda migrar 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.

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

Después de la fecha de retirada, Azure Cosmos DB ya no realizará correcciones de errores, agregará nuevas características ni proporcionará compatibilidad con las versiones retiradas del SDK. Si prefiere no actualizar, las solicitudes enviadas desde las versiones retiradas del SDK seguirán siendo atendidas por el servicio Azure Cosmos DB.

¿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 antigua y no retirada del SDK, las solicitudes a Azure Cosmos DB seguirán funcionando, pero no tendrá acceso a ninguna funcionalidad nueva.

¿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 actualizar por la fecha de retirada, las solicitudes enviadas desde las versiones retiradas del SDK seguirán siendo atendidas por Azure Cosmos DB, por lo que las aplicaciones en ejecución seguirán funcionando. Pero Azure Cosmos DB ya no realizará correcciones de errores, agregará nuevas características ni proporcionará compatibilidad con las versiones retiradas del SDK.

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 obtener más información sobre Azure Cosmos DB, consulte Microsoft Azure Cosmos DB página del servicio.