Inicio rápido: Biblioteca de Azure Cosmos DB for NoSQL para Node.js
SE APLICA A: NoSQL
Introducción a la biblioteca cliente de Azure Cosmos DB for NoSQL para Node.js para consultar datos en los contenedores y realizar operaciones comunes en elementos individuales. Siga estos pasos para implementar una solución mínima en su entorno mediante Azure Developer CLI.
Documentación de referencia de la API | Código fuente de la biblioteca | Paquete (npm) | Azure Developer CLI
Requisitos previos
- Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
- Cuenta de GitHub
- Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
- CLI de desarrollo de Azure
- Docker Desktop
Instalación
Implemente el contenedor de desarrollo de este proyecto en su entorno. A continuación, use la Azure Developer CLI (azd
) para crear una cuenta de Azure Cosmos DB for NoSQL e implementar una aplicación de ejemplo en contenedor. La aplicación de ejemplo usa la biblioteca cliente para administrar, crear, leer y consultar datos de ejemplo.
Importante
Las cuentas de GitHub incluyen un derecho de almacenamiento y horas de núcleo sin costo alguno. Para obtener más información, consulte el almacenamiento y las horas de núcleo incluidas para las cuentas de GitHub.
Abra un terminal en el directorio raíz del proyecto.
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
Ejecute
azd init
para inicializar el proyecto.azd init --template cosmos-db-nosql-dotnet-quickstart
Nota:
En este inicio rápido se usa el repositorio de GitHub azure-samples/cosmos-db-nosql-dotnet-quickstart plantilla. La Azure Developer CLI clonará automáticamente este proyecto en la máquina si aún no lo está.
Durante la inicialización, configure un nombre de entorno único.
Sugerencia
El nombre del entorno también se usará como nombre del grupo de recursos de destino. Para este inicio rápido, considere la posibilidad de usar
msdocs-cosmos-db
.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
Durante el proceso de aprovisionamiento, seleccione la suscripción y la ubicación deseada. Espere a que se complete el proceso de aprovisionamiento. El proceso puede tardar aproximadamente cinco minutos.
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.
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.
Instalación de la biblioteca cliente
La biblioteca cliente está disponible a través del Administrador de paquetes de Node, como paquete @azure/cosmos
.
Abra un terminal y vaya a la carpeta
/src
.cd ./src
Si aún no está instalado, instale el paquete
@azure/cosmos
mediantenpm install
.npm install --save @azure/cosmos
Además, instale el paquete
@azure/identity
si aún no está instalado.npm install --save @azure/identity
Abra y revise el archivo src/package.json para validar que existen las entradas
azure-cosmos
yazure-identity
.
Modelo de objetos
Nombre | Descripción |
---|---|
CosmosClient |
Esta clase es la clase de cliente principal y se usa para administrar bases de datos o metadatos de toda la cuenta. |
Database |
Esta clase representa una base de datos dentro de la cuenta. |
Container |
Esta clase se usa principalmente para realizar operaciones de lectura, actualización y eliminación en el contenedor o en los elementos almacenados en el contenedor. |
PartitionKey |
Esta clase representa una clave de partición lógica. Esta clase es necesaria para muchas operaciones y consultas comunes. |
SqlQuerySpec |
Esta interfaz representa una consulta SQL y cualquier parámetro de consulta. |
Ejemplos de código
- Autenticar el cliente
- Obtención de una base de datos
- Obtención de un contenedor
- Creación de un elemento
- Obtención de un elemento
- Elementos de consulta
El código de ejemplo de la plantilla usa una base de datos denominada cosmicworks
y un contenedor denominado products
. El contenedor products
contiene detalles como el nombre, la categoría, la cantidad, un identificador único y una marca de venta para cada producto. El contenedor usa la propiedad /category
como clave de partición lógica.
Autenticar el cliente
Deben autorizarse las solicitudes de aplicación a la mayor parte de servicios de Azure. Use el tipo DefaultAzureCredential
como forma preferida de implementar una conexión sin contraseña entre las aplicaciones y Azure Cosmos DB for NoSQL. DefaultAzureCredential
admite varios métodos de autenticación y determina el que se debe usar en tiempo de ejecución.
Importante
También puede autorizar directamente las solicitudes a los servicios de Azure mediante contraseñas, cadenas de conexión u otras credenciales. Sin embargo, este enfoque debe usarse con precaución. Los desarrolladores deben ser meticulosos y no exponer nunca estos secretos en una ubicación que no sea segura. Cualquier persona que obtenga acceso a la contraseña o a la clave secreta puede autenticarse en el servicio de base de datos. DefaultAzureCredential
ofrece ventajas de seguridad y administración mejoradas con respecto a la clave de cuenta para permitir la autenticación sin contraseña sin el riesgo de almacenar claves.
En este ejemplo se crea una nueva instancia del tipo CosmosClient
y se autentica mediante una instancia de DefaultAzureCredential
.
const credential = new DefaultAzureCredential();
const client = new CosmosClient({
'<azure-cosmos-db-nosql-account-endpoint>',
aadCredentials: credential
});
Obtención de una base de datos
Use client.database
para recuperar la base de datos existente denominada cosmicworks
.
const database = client.database('cosmicworks');
Obtención de un contenedor
Recupere el contenedor existente products
mediante database.container
.
const container = database.container('products');
Crear un elemento
Compile un nuevo objeto con todos los miembros que desea serializar en JSON. En este ejemplo, el tipo tiene un identificador único y campos para categoría, nombre, cantidad, precio y venta. Cree un elemento en el contenedor mediante container.items.upsert
. Este método "actualiza" eficazmente el elemento si ya existe.
const item = {
'id': '70b63682-b93a-4c77-aad2-65501347265f',
'category': 'gear-surf-surfboards',
'name': 'Yamba Surfboard',
'quantity': 12,
'price': 850.00,
'clearance': false
};
let response = await container.items.upsert(item);
Lectura de un elemento
Se puede realizar una operación de lectura de punto mediante el identificador único (id
) y los campos de clave de partición. Use container.item
para obtener un puntero a un elemento y item.read
para recuperar eficazmente el elemento específico.
const id = '70b63682-b93a-4c77-aad2-65501347265f';
const partitionKey = 'gear-surf-surfboards';
let response = await container.item(id, partitionKey).read();
let read_item = response.resource;
Elementos de consulta
Realice una consulta en varios elementos de un contenedor mediante container.items.query
. Busque todos los elementos de una categoría especificada mediante esta consulta con parámetros:
SELECT * FROM products p WHERE p.category = @category
Capture todos los resultados de la consulta mediante query.fetchAll
. Recorra los resultados de la consulta.
const querySpec = {
query: 'SELECT * FROM products p WHERE p.category = @category',
parameters: [
{
name: '@category',
value: 'gear-surf-surfboards'
}
]
};
let response = await container.items.query(querySpec).fetchAll();
for (let item of response.resources) {
// Do something
}