Inicio rápido: Uso de Node.js para conectarse y consultar datos en una cuenta de Azure Cosmos DB SQL API

Artículo
09/10/2021
9 minutos para leer

SE APLICA A: SQL API

En este inicio rápido se crea y administra una cuenta de Azure Cosmos DB para SQL API desde Azure Portal, y se usa una aplicación de Node.js clonada desde GitHub. Azure Cosmos DB es un servicio de base de datos multimodelo que permite crear y consultar rápidamente bases de datos de documentos, tablas, claves-valores y grafos con funcionalidades de distribución global y escala horizontal.

Tutorial de vídeo

Este vídeo incluye un tutorial completo sobre el contenido de este artículo.

Requisitos previos

Una cuenta de Azure con una suscripción activa. cree una de forma gratuita. O bien, pruebe gratis Azure Cosmos DB sin una suscripción de Azure. También puede usar el emulador de Azure Cosmos DB con el identificador URI https://localhost:8081 y la clave C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==.
Node.js 6.0.0+.
Git.

Creación de una cuenta de Azure Cosmos

Para los fines de este inicio rápido, puede usar la opción Pruebe gratis Azure Cosmos DB para crear una cuenta de Azure Cosmos.

Vaya a la página Pruebe gratis Azure Cosmos DB.
Elija la cuenta de API SQL y seleccione Crear. Inicie sesión con su cuenta de Microsoft.
Una vez que el inicio de sesión se haya realizado correctamente, la cuenta de Azure Cosmos debe estar preparada. Seleccione Abrir en Azure Portal para abrir la cuenta recién creada.

La opción "Pruebe gratis Azure Cosmos DB" no requiere una suscripción de Azure y le ofrece una cuenta de Azure Cosmos durante un período limitado de 30 días. Si desea usar la cuenta de Azure Cosmos durante un período de tiempo más largo, debe crear la cuenta en la suscripción de Azure.

Agregar un contenedor

Ahora puede usar la herramienta Explorador de datos en Azure Portal para crear una base de datos y un contenedor.

Seleccione Data Explorer > Nuevo contenedor.

El área Agregar contenedor se muestra en el extremo derecho, pero es posible que haya que desplazarse hacia la derecha para verlo.

En la página Agregar contenedor, especifique la configuración del nuevo contenedor.

Configuración	Valor sugerido	Descripción
Identificador de base de datos	ToDoList	Escriba Tareas como nombre de la nueva base de datos. Los nombres de base de datos tienen que tener entre 1 y 255 caracteres y no pueden contener `/, \\, #, ?` o espacios finales. Seleccione la opción Share throughput across containers (Compartir rendimiento entre contenedores) para compartir el rendimiento aprovisionado de la base de datos entre todos los contenedores de esta. Esta opción también le ayudará a reducir los costos.
Rendimiento de base de datos	Puede aprovisionar rendimiento de escalado automático o manual. El rendimiento manual le permite escalar RU/s por su cuenta, mientras que el rendimiento de escalabilidad automática permite que el sistema escale RU/s en función del uso. En este ejemplo, seleccione Manual. Deje el rendimiento en 400 unidades de solicitud por segundo (RU/s). Si quiere reducir la latencia, puede escalar verticalmente el rendimiento más adelante mediante la estimación de las RU/s necesarias con la calculadora de capacidad. Nota: Este valor no está disponible cuando se crea un contenedor en una cuenta sin servidor.
ID de contenedor	Elementos	Escriba Elementos como nombre del nuevo contenedor. Los identificadores de contenedor tienen los mismos requisitos de caracteres que los nombres de las bases de datos.
Clave de partición	/categoría	El ejemplo que se describe en este artículo usa /category como clave de partición.

En este ejemplo, no agregue claves únicas ni active el almacén analítico. Las claves únicas le permiten agregar una capa de integridad de datos a la base de datos mediante la garantía de unicidad de uno o varios valores por clave de partición. Para más información, consulte Claves únicas en Azure Cosmos DB. El almacén analítico se usa para permitir el análisis a gran escala de datos operativos sin ningún efecto sobre las cargas de trabajo transaccionales.

Seleccione Aceptar. El Explorador de datos muestra la nueva base de datos y el contenedor.

Adición de datos de ejemplo

Ahora, puede agregar datos al nuevo contenedor con el Explorador de datos.

En el Explorador de datos, expanda la base de datos Tareas y, después, el contenedor Elementos. Seleccione Elementos y, después, Nuevo elemento.

Ahora, agregue un documento al contenedor con la estructura siguiente.

{
    "id": "1",
    "category": "personal",
    "name": "groceries",
    "description": "Pick up apples and strawberries.",
    "isComplete": false
}

Después de agregar el archivo JSON a la pestaña Documentos, seleccione Guardar.
Cree y guarde un documento más donde insertará un valor único para la propiedad id y cambie las demás propiedades como corresponda. Los nuevos documentos pueden tener la estructura que quiera, ya que Azure Cosmos DB no impone ningún esquema en los datos.

Consulta de los datos

Ahora puede usar consultas en Data Explorer para recuperar y filtrar los datos.

En la parte superior de la pestaña Elementos de Data Explorer, examine la consulta predeterminada SELECT * FROM c. Esta consulta recupera y muestra todos los documentos del contenedor ordenados por identificador.
Para cambiar la consulta, seleccione Editar filtro, reemplace la consulta predeterminada por ORDER BY c._ts DESCy, después, seleccione Aplicar filtro.

Esta consulta modificada muestra los documentos en orden descendente según su marca de tiempo, por lo que ahora el segundo documento aparece en primer lugar.

Si está familiarizado con la sintaxis de SQL, puede especificar cualquiera de las consultas SQL admitidas en el cuadro de predicado de consulta. También puede usar Data Explorer para crear procedimientos almacenados, UDF y desencadenadores para la lógica de negocios del servidor.

Data Explorer proporciona un acceso sencillo en Azure Portal a todas las características de acceso a datos mediante programación integrado que está disponible en las API. Use también el portal para escalar el rendimiento, obtener las claves y cadenas de conexión, y revisar las métricas y los contratos de nivel de servicio de la cuenta de Azure Cosmos DB.

Clonación de la aplicación de ejemplo

Ahora vamos a clonar una aplicación en Node.js desde GitHub, establecer la cadena de conexión y ejecutarla.

Ejecute el comando siguiente para clonar el repositorio de ejemplo. Este comando crea una copia de la aplicación de ejemplo en el equipo.
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-sql-api-nodejs-getting-started.git
```

Revisión del código

Este paso es opcional. Si está interesado en aprender cómo se crean los recursos de base de datos de Azure Cosmos en el código, puede revisar los siguientes fragmentos de código. En caso contrario, puede ir directamente a Actualización de la cadena de conexión.

Si conoce la versión anterior del SDK de SQL para JavaScript, es posible que esté acostumbrado a ver los términos colección y documento. Dado que Azure Cosmos DB admite varios modelos de API, la versión 2.0+ del SDK de JavaScript usa los términos genéricos container (contenedor), que puede ser una colección, un grafo o una tabla, e item (elemento) para describir el contenido del contenedor.

El SDK de JavaScript de Cosmos DB se denomina "@azure/cosmos" y se puede instalar desde npm...

npm install @azure/cosmos

Los fragmentos de código siguientes se han tomado del archivo app.js.

CosmosClient se importa desde el paquete npm @azure/cosmos.

const CosmosClient = require("@azure/cosmos").CosmosClient;

Se inicializa un nuevo objeto CosmosClient.

const client = new CosmosClient({ endpoint, key });

Seleccione la base de datos "Tasks".

const database = client.database(databaseId);

Seleccione el contenedor o la colección "Items".

const container = database.container(containerId);

Seleccione todos los elementos del contenedor "Items".

// query to return all items
const querySpec = {
  query: "SELECT * from c"
};

const { resources: items } = await container.items
  .query(querySpec)
  .fetchAll();

Creación de un elemento

const { resource: createdItem } = await container.items.create(newItem);

Actualización de un elemento

const { id, category } = createdItem;

createdItem.isComplete = true;
const { resource: updatedItem } = await container
  .item(id, category)
  .replace(createdItem);

Eliminación de un elemento

const { resource: result } = await container.item(id, category).delete();

Nota

En los métodos "update" y "delete", el elemento debe seleccionarse de la base de datos mediante una llamada a container.item(). Los dos parámetros pasados son el identificador del elemento y la clave de partición del elemento. En este caso, la clave de partición es el valor del campo "category".

Actualización de la cadena de conexión

Ahora vuelva a Azure Portal para obtener los detalles de la cadena de conexión de su cuenta de Azure Cosmos. Copie la cadena de conexión en la aplicación para que pueda conectarse a su base de datos.

En la cuenta de Azure Cosmos DB, en Azure Portal, seleccione Claves en el panel de navegación izquierdo y, después, Claves de lectura y escritura. Use los botones de copia del lado derecho de la pantalla para copiar el URI y la clave principal en el archivo app.js en el paso siguiente.
Abra el archivo config.js.
Copie el valor del identificador URI del portal (mediante el botón de copia) y establézcalo como valor de la clave de punto de conexión en config.js.

endpoint: "<Your Azure Cosmos account URI>"
Después, copie el valor de CLAVE PRINCIPAL del portal y establézcalo como el valor de config.key en config.js. Ya ha actualizado la aplicación con toda la información que necesita para comunicarse con Azure Cosmos DB.

key: "<Your Azure Cosmos account key>"

Ejecución la aplicación

Ejecute npm install en un terminal para instalar el paquete npm "@azure/cosmos".
Ejecute node app.js en un terminal para iniciar la aplicación de nodo.
Se enumeran los dos elementos que creó anteriormente en este inicio rápido. Se crea un elemento. La marca "isComplete" de ese elemento se actualiza a "true" y, por último, se elimina el elemento.

Puede continuar experimentando con esta aplicación de ejemplo o volver al Explorador de datos, modificar y trabajar con los datos.

Revisión de los SLA en Azure Portal

Azure Portal supervisa el rendimiento, capacidad de almacenamiento, disponibilidad, latencia y coherencia de su cuenta de Cosmos DB. Los gráficos de las métricas asociadas con un Acuerdo de Nivel de Servicio (SLA) de Azure Cosmos DB muestran el rendimiento real en comparación con el valor de este acuerdo. Este conjunto de métricas hace que la supervisión de los Acuerdos de Nivel de Servicio sea transparente.

Para revisar las métricas y los Acuerdos de Nivel de Servicio:

Seleccione Métricas en el menú de navegación de la cuenta de Cosmos DB.
Seleccione una pestaña como Latencia y seleccione un período de tiempo a la derecha. Compare las líneas Real y SLA de los gráficos.
Revise las métricas de las otras pestañas.

Pasos siguientes

En este inicio rápido, ha aprendido a crear una cuenta de Azure Cosmos DB, a crear un contenedor mediante el Explorador de datos y a ejecutar una aplicación de Node.js. Ahora puede importar datos adicionales en la cuenta de Azure Cosmos DB.

¿Intenta planear la capacidad de una migración a Azure Cosmos DB? Puede usar información sobre el clúster de bases de datos existente para planear la capacidad.

Si lo único que sabe es el número de núcleos virtuales y servidores del clúster de bases de datos existente, lea sobre el cálculo de unidades de solicitud mediante núcleos o CPU virtuales.
Si conoce las tasas de solicitudes típicas de la carga de trabajo de la base de datos actual, obtenga información sobre el cálculo de unidades de solicitud mediante la herramienta de planeamiento de capacidad de Azure Cosmos DB.

Importación de datos a Azure Cosmos DB