Introducción a Azure Cosmos DB for NoSQL con JavaScript

  • Artículo

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

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. Hay tres formas principales de conectarse a una cuenta de API de NoSQL mediante la clase CosmosClient:

Conexión con un punto de conexión y una clave

El constructor más común para CosmosClient tiene dos parámetros:

Parámetro Valor de ejemplo Descripción
accountEndpoint La variable de entorno COSMOS_ENDPOINT Punto de conexión de API de NoSQL que se va a usar para todas las solicitudes
authKeyOrResourceToken La variable de entorno COSMOS_KEY Clave de cuenta o token de recurso que se va a usar en la autenticación

Recuperación del punto de conexión y clave de la cuenta

  1. Cree una variable de shell para resourceGroupName.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-javascript-howto-rg"

  2. Use el comando az cosmosdb list para recuperar el nombre de la primera cuenta de Azure Cosmos DB del grupo de recursos y almacenarlo en la variable de shell accountName.

    # Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

  3. Obtenga el URI del punto de conexión de la API de NoSQL para la cuenta mediante el comando az cosmosdb show.

    az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "documentEndpoint"

  4. Busque la CLAVE PRINCIPAL en la lista de claves de la cuenta con el comando az-cosmosdb-keys-list.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

  5. Registre los valores de URI y CLAVE PRINCIPAL. Necesitará estas credenciales más adelante.

Para usar los valores de URI y CLAVE PRINCIPAL en el código, consérvelas en nuevas variables de entorno del equipo local que ejecuta la aplicación.

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

Creación de CosmosClient con el punto de conexión y la clave de la cuenta

Cree una nueva instancia de la clase CosmosClient con las variables de entorno COSMOS_ENDPOINT y COSMOS_KEY como parámetros.

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

Conexión con una cadena de conexión

Otro constructor para CosmosClient solo contiene un único parámetro:

Parámetro Valor de ejemplo Descripción
accountEndpoint La variable de entorno COSMOS_ENDPOINT Punto de conexión de API de NoSQL que se va a usar para todas las solicitudes
connectionString La variable de entorno COSMOS_CONNECTION_STRING Cadena de conexión a la cuenta de la API de NoSQL

Recuperación de la cadena de conexión de la cuenta

  1. Use el comando az cosmosdb list para recuperar el nombre de la primera cuenta de Azure Cosmos DB del grupo de recursos y almacenarlo en la variable de shell accountName.

    # Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

  2. Busque la CADENA DE CONEXIÓN PRINCIPAL en la lista de cadenas de conexión para la cuenta con el comando az-cosmosdb-keys-list.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "connection-strings" \
    --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"

Para usar el valor de CADENA DE CONEXIÓN PRINCIPAL en el código, consérvelo en una nueva variable de entorno del equipo local que ejecuta la aplicación.

$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"

Creación de CosmosClient con cadena de conexión

Cree una nueva instancia de la clase CosmosClient con la variable de entorno COSMOS_CONNECTION_STRING como el único parámetro.

// New instance of CosmosClient class using a connection string
const cosmosClient = new CosmosClient(process.env.COSMOS_CONNECTION_STRING);

Conexión mediante la Plataforma de identidad de Microsoft

Para conectarse a la API de la cuenta de NoSQL mediante la Plataforma de identidad de Microsoft y Microsoft Entra ID, 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
});

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

Si tiene previsto implementar la aplicación fuera de Azure, puede obtener un token de OAuth mediante otras clases de la biblioteca cliente @azure/identity para JavaScript. Estas otras clases también se derivan de la clase TokenCredential.

En este ejemplo, se crea una instancia de ClientSecretCredential mediante identificadores de cliente e inquilino, junto con un secreto de cliente.

Puede obtener el id. de cliente, el id. de inquilino y el secreto de cliente al registrar una aplicación en Microsoft Entra ID. Para más información sobre el registro de aplicaciones de Microsoft Entra, vea Registro de una aplicación con la Plataforma de identidad de Microsoft.

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 ClientSecretCredential(
    tenantId: process.env.AAD_TENANT_ID,
    clientId: process.env.AAD_CLIENT_ID,
    clientSecret: process.env.AAD_CLIENT_SECRET
);

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.

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, containers, and items.

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

Pasos siguientes

Ahora que se ha conectado a una cuenta de API para NoSQL, use la guía siguiente para crear y administrar bases de datos.

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