Inicio rápido: Compilación de una aplicación de API para Table con Node.js y Azure Cosmos DB
SE APLICA A: 
Table
En este inicio rápido se crea una cuenta de Azure Cosmos DB for Table y se usa Data Explorer y una aplicación de Node.js clonada desde GitHub para crear tablas y entidades. 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.
Requisitos previos
- Una cuenta de Azure con una suscripción activa. cree una de forma gratuita.
- Node.js 0.10.29+.
- Git.
Aplicación de ejemplo
La aplicación de ejemplo de este tutorial se puede clonar o descargar desde el repositorio https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js. En el repositorio de ejemplo se incluyen tanto una aplicación de inicio como una completa.
git clone https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js
La aplicación de ejemplo usa datos meteorológicos para demostrar las funcionalidades de la API para Table. Los objetos que representan observaciones meteorológicas se almacenan y recuperan mediante la API para Table, incluido el almacenamiento de objetos con propiedades adicionales para mostrar las funcionalidades sin esquema de dicha API.
1 - Creación de una cuenta de Azure Cosmos DB
En primer lugar, debe crear una cuenta de API for Table de Azure Cosmos DB que contendrá las tablas usadas en la aplicación. Esto se puede realizar mediante Azure Portal, la CLI de Azure o Azure PowerShell.
Inicie sesión en Azure Portal y siga estos pasos para crear una cuenta de Azure Cosmos DB.
| Instrucciones | Instantánea |
|---|---|
En el Portal de Azure:
|
|
| En la página Azure Cosmos DB, seleccione +Crear. | 
|
| En la página Selección de la opción de API, elija la opción Tabla de Azure. | 
|
En la página Creación de una cuenta de Azure Cosmos DB: Tabla de Azure, rellene el formulario de la siguiente manera.
|
|
2 - Creación de una tabla
Después, debe crear una tabla dentro de la cuenta de Azure Cosmos DB que es la que usará la aplicación. A diferencia de una base de datos tradicional, solo es necesario especificar el nombre de la tabla, no las propiedades (columnas) de la tabla. A medida que se cargan datos en la tabla, las propiedades (columnas) se crean automáticamente según sea necesario.
En Azure Portal, complete los pasos siguientes para crear una tabla dentro de la cuenta de Azure Cosmos DB.
| Instrucciones | Instantánea |
|---|---|
| En Azure Portal, vaya a la página de información general de la cuenta de Azure Cosmos DB. Para ir a la página de información general de la cuenta de Azure Cosmos DB, escriba el nombre (cosmos-msdocs-tables-sdk-demo-XYZ) de la cuenta de Azure Cosmos DB en la barra de búsqueda superior y busque en el encabezado de recursos. Seleccione el nombre de la cuenta de Azure Cosmos DB para ir a la página de información general. | 
|
| En la página de información general, seleccione +Agregar tabla. El cuadro de diálogo Nueva tabla se deslizará desde el lado derecho de la página. | 
|
En el cuadro de diálogo Nueva tabla, complete el formulario de la siguiente manera.
|
|
3 - Obtención de la cadena de conexión de Azure Cosmos DB
Para acceder a las tablas de Azure Cosmos DB, la aplicación necesita la cadena de conexión de la tabla para la cuenta de almacenamiento de CosmosDB. La cadena de conexión se puede recuperar mediante Azure Portal, la CLI de Azure o Azure PowerShell.
| Instrucciones | Instantánea |
|---|---|
| En el lado izquierdo de la página de la cuenta de Azure Cosmos DB, busque el elemento de menú denominado Cadena de conexión en el encabezado Configuración y selecciónelo. Se le llevará a una página donde puede recuperar la cadena de conexión para la cuenta de Azure Cosmos DB. | 
|
| Copie el valor CADENA DE CONEXIÓN PRINCIPAL para usarlo en la aplicación. | 
|
4 - Instalación del SDK de Azure Data Tables para JS
Para acceder a Azure Cosmos DB for Table desde una aplicación de nodejs, instale el paquete del SDK de las Tablas de datos de Azure.
npm install @azure/data-tables
5 - Configuración del cliente de Table en el archivo env.js
Copie la cadena de conexión de la cuenta de Azure Cosmos DB o Storage desde Azure Portal y cree un objeto TableServiceClient con la cadena de conexión copiada. Cambie a la carpeta 1-strater-app o 2-completed-app. A continuación, agregue el valor de las variables de entorno correspondientes en el archivo configure/env.js.
const env = {
connectionString:"A connection string to an Azure Storage or Azure Cosmos DB account.",
tableName: "WeatherData",
};
Azure SDK se comunica con Azure mediante objetos de cliente para ejecutar diferentes operaciones en Azure. La clase TableClient es la que se usa para comunicarse con Azure Cosmos DB for Table. Normalmente, una aplicación creará un único objeto serviceClient por cada tabla que se usará en toda la aplicación.
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
env.connectionString,
env.tableName
);
6 - Implementación de las operaciones de tabla de Azure Cosmos DB
Todas las operaciones de tablas de Azure Cosmos DB de la aplicación de ejemplo se implementan en el objeto serviceClient ubicado en el archivo tableClient.js del directorio service.
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
env.connectionString,
env.tableName
);
Obtención de filas de una tabla
El objeto serviceClient contiene un método llamado listEntities que permite seleccionar filas de la tabla. En este ejemplo, dado que no se pasan parámetros al método, se seleccionarán todas las filas de la tabla.
const allRowsEntities = serviceClient.listEntities();
Filtrado de las filas devueltas de una tabla
Para filtrar las filas devueltas de una tabla, puede pasar una cadena de filtro de estilo OData al método listEntities. Por ejemplo, si quisiera obtener todas las lecturas meteorológicas de Chicago entre la medianoche del 1 de julio de 2021 y la medianoche del 2 de julio de 2021 (ambos incluidos), pasaría la siguiente cadena de filtro.
PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00' and RowKey le '2021-07-02 12:00'
Puede ver todos los operadores de filtrado de OData en el sitio web de OData, en la sección Opción de consulta del sistema de filtrado.
Cuando se pasa el parámetro request.args al método listEntities de la clase serviceClient, crea una cadena de filtrado para cada valor de propiedad que no sea NULL. A continuación, crea una cadena de filtrado combinada combinando todos los valores con una cláusula "and". Esta cadena de filtrado combinada se pasa al método listEntities en el objeto serviceClient y solo se devolverán las filas que coincidan con la cadena de filtrado. Puede usar un método similar en el código para construir cadenas de filtrado adecuadas según sea necesario para la aplicación.
const filterEntities = async function (option) {
/*
You can query data according to existing fields
option provides some conditions to query,eg partitionKey, rowKeyDateTimeStart, rowKeyDateTimeEnd
minTemperature, maxTemperature, minPrecipitation, maxPrecipitation
*/
const filterEntitiesArray = [];
const filters = [];
if (option.partitionKey) {
filters.push(`PartitionKey eq '${option.partitionKey}'`);
}
if (option.rowKeyDateTimeStart) {
filters.push(`RowKey ge '${option.rowKeyDateTimeStart}'`);
}
if (option.rowKeyDateTimeEnd) {
filters.push(`RowKey le '${option.rowKeyDateTimeEnd}'`);
}
if (option.minTemperature !== null) {
filters.push(`Temperature ge ${option.minTemperature}`);
}
if (option.maxTemperature !== null) {
filters.push(`Temperature le ${option.maxTemperature}`);
}
if (option.minPrecipitation !== null) {
filters.push(`Precipitation ge ${option.minPrecipitation}`);
}
if (option.maxPrecipitation !== null) {
filters.push(`Precipitation le ${option.maxPrecipitation}`);
}
const res = serviceClient.listEntities({
queryOptions: {
filter: filters.join(" and "),
},
});
for await (const entity of res) {
filterEntitiesArray.push(entity);
}
return filterEntitiesArray;
};
Inserción de datos mediante un objeto TableEntity
La manera más sencilla de agregar datos a una tabla es mediante el uso de un objeto TableEntity. En este ejemplo, los datos se asignan desde un objeto del modelo de entrada a un objeto TableEntity. Las propiedades del objeto de entrada que representan el nombre de la estación meteorológica y la fecha y hora de observación se asignan a las propiedades PartitionKey y RowKey respectivamente, que juntas forman una clave única para la fila de la tabla. A continuación, las propiedades adicionales del objeto del modelo de entrada se asignan a las propiedades del diccionario en el objeto TableEntity. Por último, se usa el método createEntity del objeto serviceClient para insertar los datos en la tabla.
Modifique la función insertEntity de la aplicación de ejemplo para que contenga el código siguiente.
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
Actualizar/insertar (upsert) datos mediante un objeto TableEntity
Si intenta insertar una fila en una tabla con una combinación de clave de partición y clave de fila que ya existe en esa tabla, recibirá un error. Por este motivo, a menudo es preferible usar upsertEntity en lugar del método createEntity al agregar filas a una tabla. Si la combinación de clave de partición y clave de fila especificada ya existe en la tabla, el método upsertEntity actualizará la fila existente. De lo contrario, se agregará la fila a la tabla.
const upsertEntity = async function (entity) {
await serviceClient.upsertEntity(entity, "Merge");
};
Insertar o actualizar/insertar (upsert) datos con propiedades variables
Una de las ventajas de usar Azure Cosmos DB for Table es que, si un objeto que se carga en una tabla contiene nuevas propiedades, esas propiedades se agregan automáticamente a la tabla y los valores almacenados en Azure Cosmos DB. No es necesario ejecutar instrucciones DDL como ALTER TABLE para agregar columnas como en una base de datos tradicional.
Este modelo proporciona flexibilidad a la aplicación cuando se trabaja con orígenes de datos que pueden agregar o modificar qué datos se deben capturar a lo largo del tiempo o cuando distintas entradas proporcionan datos diferentes a la aplicación. En la aplicación de ejemplo, podemos simular una estación meteorológica que envía no solo los datos meteorológicos básicos, sino también algunos valores adicionales. Cuando un objeto con estas nuevas propiedades se almacena en la tabla por primera vez, las propiedades correspondientes (columnas) se agregarán automáticamente a la tabla.
Para insertar o actualizar un objeto de este tipo mediante la API para Table, asigne las propiedades del objeto ampliable a un objeto TableEntity y use los métodos createEntity o upsertEntity en el objeto serviceClient según corresponda.
En la aplicación de ejemplo, la función upsertEntity también puede implementar la función de insertar o actualizar datos con propiedades de variable.
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
const upsertEntity = async function (entity) {
await serviceClient.upsertEntity(entity, "Merge");
};
Actualización de una entidad
Las entidades se pueden actualizar llamando al método updateEntity en el objeto serviceClient.
En la aplicación de ejemplo, este objeto se pasa al método upsertEntity del objeto serviceClient. Actualiza ese objeto de entidad y usa el método upsertEntity para guardar las actualizaciones en la base de datos.
const updateEntity = async function (entity) {
await serviceClient.updateEntity(entity, "Replace");
};
7 - Ejecución del código
Ejecute la aplicación de ejemplo para interactuar con Azure Cosmos DB for Table. La primera vez que ejecute la aplicación, no habrá datos porque la tabla está vacía. Use cualquiera de los botones de la parte superior de la aplicación para agregar datos a la tabla.
Al seleccionar el botón Insert using Table Entity (Insertar mediante TableEntity), se abre un cuadro de diálogo que le permite insertar o actualizar/insertar (upsert) una fila nueva mediante un objeto TableEntity.
Al seleccionar el botón Insert using Expandable Data, se abre un cuadro de diálogo que le permite insertar un objeto con propiedades personalizadas, lo que muestra cómo Azure Cosmos DB for Table agrega automáticamente propiedades (columnas) a la tabla cuando es necesario. Use el botón Add Custom Field (Agregar campo personalizado) para agregar una o varias propiedades nuevas y demostrar esta funcionalidad.
Use el botón Insertar datos de ejemplo para cargar algunos datos de ejemplo en la tabla de Azure Cosmos DB.
Seleccione el elemento Filter Results (Filtrar resultados) en el menú superior para ir a la página Filter Results (Filtrar resultados). En esta página, rellene los criterios de filtrado para mostrar cómo se puede crear y pasar una cláusula de filtro a Azure Cosmos DB for Table.
Limpieza de recursos
Cuando haya terminado con la aplicación de ejemplo, debe quitar todos los recursos de Azure relacionados con este artículo de la cuenta de Azure. Para ello, elimine el grupo de recursos.
Se puede eliminar un grupo de recursos mediante Azure Portal haciendo lo siguiente.
| Instrucciones | Instantánea |
|---|---|
| Para ir al grupo de recursos, en la barra de búsqueda, escriba el nombre del grupo de recursos. A continuación, en la pestaña Grupos de recursos, seleccione el nombre del grupo de recursos. | 
|
| Seleccione Eliminar grupo de recursos en la barra de herramientas de la parte superior de la página del grupo de recursos. | 
|
Aparecerá un cuadro de diálogo a la derecha de la pantalla en el que se le pedirá que confirme la eliminación del grupo de recursos.
|
|
Pasos siguientes
En esta guía de inicio rápido, ha obtenido información sobre cómo crear una cuenta de Azure Cosmos DB, crear una tabla mediante el Explorador de datos y ejecutar una aplicación. Ahora ya puede consultar los datos mediante la API para Table.
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de