Introducción a Azure Cosmos DB for NoSQL con JavaScript

SE APLICA A: NoSQL

En este artículo se describe cómo conectarse a Azure Cosmos DB for NoSQL mediante el SDK de JavaScript. Una vez conectado, puede realizar operaciones en bases de datos, contenedores y elementos.

Paquete (npm) | Ejemplos | Referencia de la API | Código fuente de la biblioteca | Hacer comentarios

Prerrequisitos

• Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
• Cuenta de Azure Cosmos DB for NoSQL. Creación de una API para una cuenta de NoSQL.
• LTS de Node.js
• Interfaz de la línea de comandos (CLI) de Azure o Azure PowerShell

Creación del proyecto local

1. Cree un directorio para el proyecto de JavaScript en un shell de Bash.

   mkdir cosmos-db-nosql-javascript-samples && cd ./cosmos-db-nosql-javascript-samples
   

2. Cree una nueva aplicación JavaScript mediante el comando npm init con la plantilla console.

   npm init -y
   

3. Instale la dependencia necesaria para el SDK de JavaScript de Azure Cosmos DB for NoSQL.

   npm install @azure/cosmos
   

Conexión de Azure Cosmos DB for NoSQL

Para conectarse a la API de NoSQL de Azure Cosmos DB, cree una instancia de la clase CosmosClient. Esta clase es el punto inicial para realizar todas las operaciones en bases de datos.

Para conectarse a la API para la cuenta NoSQL mediante Microsoft Entra, use una entidad de seguridad. El tipo exacto de entidad de seguridad dependerá de dónde hospede el código de la aplicación. La tabla siguiente sirve como guía de referencia rápida.

Dónde se ejecuta la aplicación	Entidad de seguridad
Máquina local (desarrollo y pruebas)	Identidad de usuario o entidad de servicio
Azure	Identidad administrada
Servidores o clientes fuera de Azure	Entidad de servicio

Importar @azure/identity

El paquete @azure/identity contiene la funcionalidad de autenticación principal que se comparte entre todas las bibliotecas del SDK de Azure.

1. Importe el paquete npm @azure/identity mediante el comando npm install.

   npm install @azure/identity
   

2. En el editor de código, agregue las dependencias.

   const { DefaultAzureCredential } = require("@azure/identity");
   

Creación de CosmosClient con la implementación de credenciales predeterminada

Si está probando en una máquina local o la aplicación se va a ejecutar en servicios de Azure con compatibilidad directa con identidades administradas, obtenga un token de OAuth mediante la creación de una instancia de DefaultAzureCredential. Cree una nueva instancia de la clase CosmosClient con la variable de entorno COSMOS_ENDPOINT y el objeto TokenCredential como parámetros.

const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();

const cosmosClient = new CosmosClient({ 
    endpoint, 
    aadCredentials: credential
});

Compilación de la aplicación

A medida que compile la aplicación, el código interactuará principalmente con cuatro tipos de recursos:

• La cuenta de la API de NoSQL, que es el espacio de nombres único de nivel superior para los datos de Azure Cosmos DB.

• Bases de datos, que organizan los contenedores de la cuenta.

• Contenedores, que contienen un conjunto de elementos individuales en la base de datos.

• Elementos, que representan un documento JSON en el contenedor.

En el siguiente diagrama se muestra la relación entre estos recursos.

Diagrama jerárquico que muestra una cuenta de Azure Cosmos DB en la parte superior. La cuenta tiene dos nodos de base de datos secundarios. Uno de los nodos de la base de datos incluye dos nodos de contenedor secundarios. El otro nodo de la base de datos incluye un único nodo de contenedor secundario. Ese nodo de contenedor único tiene tres nodos de elementos secundarios.

Cada tipo de recurso se representa mediante una o varias clases asociadas. A continuación, se muestra una lista de las clases más comunes:

Clase	Descripción
CosmosClient	Esta clase proporciona una representación lógica del cliente para el servicio Azure Cosmos DB. El objeto de cliente se usa para configurar y ejecutar solicitudes en el servicio.
Database	Esta clase es una referencia a una base de datos que podría existir o no en el servicio. La base de datos se valida en el lado servidor al intentar acceder a ella o realizar alguna una operación en ella.
Container	Esta clase es una referencia a un contenedor que podría no existir aún en el servicio. El contenedor se valida en el servidor al intentar utilizarlo.

En las siguientes guías se muestra cómo usar cada una de estas clases para compilar la aplicación.

Guía	Descripción
Creación de una base de datos	Creación de bases de datos
Creación de un contenedor	Creación de contenedores
Crear y leer un elemento	Lectura puntual de un elemento específico
Elementos de consulta	Consulta de varios elementos

Consulte también

• Paquete npm
• Muestras
• Referencia de las API
• Código fuente de la biblioteca
• Envíenos sus comentarios

Pasos siguientes

Creación de una base de datos en Azure Cosmos DB for NoSQL mediante JavaScript