Compartir vía

Inicio rápido: Uso de Azure Cosmos DB for Table con Azure SDK para Node.js

  • Artículo
  • Se aplica a:
    ✅ Table

En este inicio rápido, implementará una aplicación básica de Azure Cosmos DB for Table mediante Azure SDK para Node.js. Azure Cosmos DB for Table es un almacén de datos sin esquema que permite a las aplicaciones almacenar datos de tabla estructurados en la nube. Aprenderá a crear tablas, filas y realizar tareas básicas en el recurso de Azure Cosmos DB mediante el SDK de Azure para Node.js.

Documentación de referencia de la API | Código fuente de la biblioteca | Paquete (npm) | Azure Developer CLI

Requisitos previos

  • CLI de desarrollo de Azure
  • Docker Desktop
  • Node.js 22 o posteriores

Antes de comenzar, si no tiene una cuenta de Azure, cree una gratuita.

Inicialización del proyecto

Use Azure Developer CLI (azd) para crear una cuenta de Azure Cosmos DB for Table e implementar una aplicación de ejemplo contenedorizada. La aplicación de ejemplo usa la biblioteca cliente para administrar, crear, leer y consultar datos de ejemplo.

  1. Abra un terminal en un directorio vacío.

  2. Si aún no está autenticado, autentíquese en Azure Developer CLI mediante azd auth login. Siga los pasos especificados por la herramienta para autenticarse en la CLI mediante sus credenciales de Azure preferidas.

    azd auth login

  3. Ejecute azd init para inicializar el proyecto.

    azd init --template cosmos-db-table-nodejs-quickstart

  4. Durante la inicialización, configure un nombre de entorno único.

  5. Implemente la cuenta de Azure Cosmos DB mediante azd up. Las plantillas de Bicep también implementan una aplicación web de muestra.

    azd up

  6. Durante el proceso de aprovisionamiento, seleccione la suscripción, la ubicación deseada y el grupo de recursos de destino. Espere a que se complete el proceso de aprovisionamiento. El proceso puede tardar aproximadamente cinco minutos.

  7. Una vez realizado el aprovisionamiento de los recursos de Azure, se incluye una dirección URL a la aplicación web en ejecución en la salida.

    Deploying services (azd deploy)

  (✓) Done: Deploying service web
- Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>

SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.

  8. Use la dirección URL de la consola para ir a la aplicación web en el explorador. Observe la salida de la aplicación en ejecución.

Captura de pantalla de la aplicación web en ejecución.

Captura de pantalla de la aplicación web en ejecución.

Instalación de la biblioteca cliente

La biblioteca cliente está disponible a través de npm, como paquete de @azure/data-tables.

  1. Abra un terminal y vaya a la carpeta /src/ts.

    cd ./src/ts

  2. Si aún no está instalado, instale el paquete @azure/data-tables mediante npm install.

    npm install --save @azure/data-tables

  3. Abra y revise el archivo src/ts/package.json para validar que existe la entrada @azure/data-tables.

  1. Abra un terminal y vaya a la carpeta /src/js.

    cd ./src/js

  2. Si aún no está instalado, instale el paquete @azure/data-tables mediante npm install.

    npm install --save @azure/data-tables

  3. Abra y revise el archivo src/js/package.json para validar que existe la entrada @azure/data-tables.

Modelo de objetos

Nombre Descripción
TableServiceClient Este tipo es el tipo de cliente principal y se usa para administrar bases de datos o metadatos para toda la cuenta.
TableClient Este tipo representa el cliente de una tabla dentro de la cuenta.

Ejemplos de código

En el código de ejemplo de la plantilla se usa una tabla denominada cosmicworks-products. La tabla cosmicworks-products contiene detalles como el nombre, la categoría, la cantidad, el precio, un identificador único y una marca de venta para cada producto. El contenedor usa un identificador único como clave de fila y una categoría como clave de partición.

Autenticar el cliente

En este ejemplo se crea una nueva instancia del tipo TableServiceClient.

let client: TableServiceClient = new TableServiceClient("<azure-cosmos-db-table-account-endpoint>", "<credential>");

const credential = new DefaultAzureCredential();

let client = new TableServiceClient("<azure-cosmos-db-table-account-endpoint>", credential);

Obtención de una tabla

En este ejemplo se crea una instancia del tipo TableClient mediante la función GetTableClient del tipo TableServiceClient.

let table: TableClient = new TableClient("<azure-cosmos-db-table-account-endpoint>", "<azure-cosmos-db-table-name>", credential);

let table = new TableClient("<azure-cosmos-db-table-account-endpoint>", "<azure-cosmos-db-table-name>", credential);

Crear una entidad

La manera más fácil de crear una entidad en una tabla consiste en derivar una nueva interfaz de TableEntity y, después, crear un objeto de ese tipo.

export interface Product extends TableEntity {
    name: string;
    quantity: number;
    price: number;
    clearance: boolean;
}

const entity: Product = {
    rowKey: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    partitionKey: 'gear-surf-surfboards',
    name: 'Yamba Surfboard',
    quantity: 12,
    price: 850.00,
    clearance: false
};

La manera más fácil de crear un nuevo elemento en una tabla es crear un objeto JSON.

const entity = {
    rowKey: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    partitionKey: 'gear-surf-surfboards',
    name: 'Yamba Surfboard',
    quantity: 12,
    price: 850.00,
    clearance: false
};

Cree una entidad en la tabla mediante el método upsertEntity desde la instancia de TableService.

await table.upsertEntity<Product>(entity, "Replace"); 

await table.upsertEntity(entity, "Replace");

Obtención de una entidad

Puede recuperar una entidad específica de una tabla mediante el método getEntity, la clave de fila para la entidad y la clave de partición de la entidad.

const response: GetTableEntityResponse<TableEntityResult<Product>> = await table.getEntity<Product>(partitionKey, rowKey);

const entity: Product = response as Product;

const entity = await table.getEntity(partitionKey, rowKey);

Consulta de entidades

Después de insertar una entidad, también puede ejecutar una consulta para obtener todas las entidades que coinciden con un filtro específico mediante listEntities con un filtro OData.

const partitionKey: string = 'gear-surf-surfboards';

const filter: string = `PartitionKey eq '${partitionKey}'`

const queryOptions: TableEntityQueryOptions = { filter: filter }

const entities: PagedAsyncIterableIterator<TableEntityResult<Product>, TableEntityResultPage<Product>> = table.listEntities<Product>({ queryOptions: queryOptions });

const partitionKey = 'gear-surf-surfboards';

const entities = table.listEntities({
    queryOptions: {
        filter: `PartitionKey eq '${partitionKey}'`
    }
});

Analice los resultados paginados de la consulta mediante un bucle asincrónico for await en el conjunto paginado de entities.

for await(const entity of entities) {
    // Do something
}

for await(const entity of entities) {
    // Do something
}

Limpieza de recursos

Cuando ya no necesite la aplicación o los recursos de ejemplo, quite la implementación correspondiente y todos los recursos.

azd down

Contenido relacionado