Inicio rápido: Biblioteca cliente de Azure Cosmos DB para Apache Cassandra para Node.js

Se aplica a: ✅ Apache Cassanda

Comienza con la biblioteca cliente de Azure Cosmos DB para Apache Cassandra de Node.js para almacenar, administrar y consultar datos no estructurados. Siga los pasos de esta guía para crear una cuenta, instalar una biblioteca cliente de Node.js, conectarse a la cuenta, realizar operaciones comunes y consultar los datos finales de ejemplo.

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

Prerrequisitos

Una suscripción de Azure
- Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.

La versión más reciente de Azure CLI en Azure Cloud Shell.
- Si prefiere ejecutar comandos de referencia de la CLI localmente, inicie sesión en la CLI de Azure mediante el az login comando .

Node.js 22 o posteriores

Instalación

Primero, configure la cuenta y el entorno de desarrollo para esta guía. En esta sección se explica el proceso de creación de una cuenta, la obtención de sus credenciales y la preparación del entorno de desarrollo.

Crear una cuenta

Empiece por crear una API para una cuenta de Apache Cassandra. Una vez creada la cuenta, cree los recursos de espacio de claves y tabla.

Azure CLI
Azure Portal

Si aún no tiene un grupo de recursos de destino, use el az group create comando para crear un nuevo grupo de recursos en la suscripción.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

Use el az cosmosdb create comando para crear una nueva cuenta de Azure Cosmos DB para Apache Cassandra con la configuración predeterminada.

az cosmosdb create \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --locations "regionName=<location>" \
    --capabilities "EnableCassandra"

Cree un nuevo espacio de claves usando az cosmosdb cassandra keyspace create llamado cosmicworks.

az cosmosdb cassandra keyspace create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --name "cosmicworks"

Cree un nuevo objeto JSON para representar el esquema mediante un comando bash de varias líneas. A continuación, use el az cosmosdb cassandra table create comando para crear una nueva tabla denominada products.

schemaJson=$(cat <<EOF
{
  "columns": [
    {
      "name": "id",
      "type": "text"
    },
    {
      "name": "name",
      "type": "text"
    },
    {
      "name": "category",
      "type": "text"
    },
    {
      "name": "quantity",
      "type": "int"
    },
    {
      "name": "price",
      "type": "decimal"
    },
    {
      "name": "clearance",
      "type": "boolean"
    }
  ],
  "partitionKeys": [
    {
      "name": "id"
    }
  ]
}
EOF
)

az cosmosdb cassandra table create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --keyspace-name "cosmicworks" \
    --name "product" \
    --schema "$schemaJson"

Inicie sesión en Azure Portal (https://portal.azure.com).
Introduzca Azure Cosmos DB en la barra de búsqueda global.
En Servicios, seleccione Azure Cosmos DB.
En el panel Azure Cosmos DB , seleccione Crear y, después, Azure Cosmos DB para Apache Cassandra en la pestaña Otros .
Seleccione Cuenta de base de datos de unidad de solicitud (RU) para el tipo de cuenta.

En el panel Aspectos básicos, configure las siguientes opciones y, a continuación, seleccione Revisar y crear:

	Importancia
Tipo de carga de trabajo	Aprendizaje
Suscripción	Seleccione su suscripción a Azure.
Grupo de recursos	Cree un grupo de recursos nuevo o seleccione uno existente
Nombre de cuenta	Proporcione un nombre único global.
Zonas de disponibilidad	Deshabilitar
Ubicación	Seleccione una región de Azure compatible para su suscripción

Sugerencia

Puede dejar cualquier opción no especificada con sus valores predeterminados. También puede configurar la cuenta para limitar el rendimiento total de la cuenta a 1000 unidades de solicitud por segundo (RU/s) o habilitar el nivel gratis para minimizar los costos.

En el panel Revisar y crear, espere a que la validación de la cuenta finalice correctamente y seleccione Crear.
El portal navega automáticamente al panel Implementación. Espere a que la implementación se complete.
Una vez completada la implementación, seleccione Ir al recurso para ir a la nueva API para la cuenta de Apache Cassandra.
En el menú de recursos, seleccione la opción Explorador de datos .
En el Explorador de datos, seleccione + Nueva tabla.

En el cuadro de diálogo Agregar tabla , configure las opciones siguientes y, a continuación, seleccione Aceptar:

	Importancia
Keyspace	Crear nuevo
Nombre del Keyspace	`cosmicworks`
Nombre de la tabla	`product`
Esquema de tabla	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

Sugerencia

Puede dejar cualquier opción no especificada con sus valores predeterminados.

Obtener credenciales

Ahora, obtenga la contraseña de la biblioteca cliente que se usará para crear una conexión a la cuenta creada recientemente.

Azure CLI
Azure Portal

Use az cosmosdb show para obtener el punto de contacto y el nombre de usuario de la cuenta.

az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "{username:name,contactPoint:documentEndpoint}"

Registre el valor de las propiedades contactPoint y username de la salida de los comandos anteriores. Los valores de estas propiedades son el punto de contacto y el nombre de usuario que usa más adelante en esta guía para conectarse a la cuenta con la biblioteca.

Use az cosmosdb keys list para obtener las claves de la cuenta.

az cosmosdb keys list \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --type "keys"

Registre el valor de la propiedad primaryMasterKey de la salida de los comandos anteriores. El valor de esta propiedad es la contraseña que se usa más adelante en esta guía para conectarse a la cuenta con la biblioteca.

Preparación del entorno de desarrollo

A continuación, configure el entorno de desarrollo con un nuevo proyecto y la biblioteca cliente. Este paso es el último requisito previo necesario antes de pasar al resto de esta guía.

Inicie en una carpeta vacía.
Inicialice un nuevo módulo.
```
npm init es6 --yes
```
Instale el cassandra-driver paquete desde el Administrador de paquetes de Node (npm).
```
npm install --save cassandra-driver
```
Cree el archivo index.js .

Inicie en un directorio vacío.
Inicialice un nuevo módulo.
```
npm init es6 --yes
```
Instale el typescript paquete desde el Administrador de paquetes de Node (npm).
```
npm install --save-dev typescript
```
Instale el tsx paquete desde npm.
```
npm install --save-dev tsx
```
Instale el cassandra-driver paquete desde npm.
```
npm install --save cassandra-driver
```

Inicialice el proyecto de TypeScript mediante el compilador (tsc).

npx tsc --init --target es2017 --module es2022 --moduleResolution nodenext

Cree el archivo index.ts .

Modelo de objetos

	Descripción
`Client`	Representa una conexión específica a un clúster
`Mapper`	Cliente del lenguaje de consulta cassandra (CQL) usado para ejecutar consultas

Autenticar cliente

Empiece por autenticar al cliente con las credenciales recopiladas anteriormente en esta guía.

Abra el archivo index.js en el entorno de desarrollo integrado (IDE).

Importe los siguientes tipos desde el cassandra-driver módulo:

cassandra
cassandra.Client
cassandra.mapping.Mapper
cassandra.auth.PlainTextAuthProvider

import cassandra from 'cassandra-driver';

const { Client } = cassandra;
const { Mapper } = cassandra.mapping;
const { PlainTextAuthProvider } = cassandra.auth;

Cree variables constantes de cadena para las credenciales recopiladas anteriormente en esta guía. Asigne un nombre a las variables username, passwordy contactPoint.
```
const username = '<username>';
const password = '<password>';
const contactPoint = '<contact-point>';
```
Cree otra variable de cadena para la región donde ha creado la cuenta de Azure Cosmos DB for Apache Cassandra. Asigne a esta variable regionel nombre .
```
const region = '<azure-region>';
```
Cree un nuevo PlainTextAuthProvider objeto con las credenciales especificadas en los pasos anteriores.
```
let authProvider = new PlainTextAuthProvider(
    username,
    password
);
```

Cree un Client objeto con las variables de configuración y credenciales creadas en los pasos anteriores.

let client = new Client({
    contactPoints: [`${contactPoint}:10350`],
    authProvider: authProvider,
    localDataCenter: region,
    sslOptions: {
        secureProtocol: 'TLSv1_2_method'
    },
});

Conéctese de forma asincrónica al clúster.
```
await client.connect();
```

Cree un nuevo mapeador que tenga como destino el cosmicworks espacio de claves y la product tabla. Asigne al asignador Productel nombre .

const mapper = new Mapper(client, {
    models: {
        'Product': {
            tables: ['product'],
            keyspace: 'cosmicworks'
        }
    }
});

Genere una instancia del mapeador mediante la función forModel y el nombre del mapeador Product.
```
const productMapper = mapper.forModel('Product');
```

Abra el archivo index.ts en el entorno de desarrollo integrado (IDE).
Importe los siguientes tipos desde el cassandra-driver módulo:
- cassandra.auth
- cassandra.mapping
- cassandra.types
- cassandra.Client
- cassandra.ClientOptions
- cassandra.mapping.Mapper
- cassandra.auth.PlainTextAuthProvider
```
import { auth, mapping, types, Client, ClientOptions } from 'cassandra-driver';

const { Mapper } = mapping;
const { PlainTextAuthProvider } = auth;
```
Cree variables constantes de cadena para las credenciales recopiladas anteriormente en esta guía. Asigne un nombre a las variables username, passwordy contactPoint.
```
const username: string = '<username>';
const password: string = '<password>';
const contactPoint: string = '<contact-point>';
```
Cree otra variable de cadena para la región donde ha creado la cuenta de Azure Cosmos DB for Apache Cassandra. Asigne a esta variable regionel nombre .
```
const region: string = '<azure-region>';
```
Cree un nuevo PlainTextAuthProvider objeto con las credenciales especificadas en los pasos anteriores.
```
let authProvider = new PlainTextAuthProvider(
    username,
    password
);
```
Cree un objeto anónimo con opciones que garantice el uso del protocolo de seguridad de la capa de transporte (TLS) 1.2.
```
let sslOptions = {
    secureProtocol: 'TLSv1_2_method'
};
```

Cree un ClientOptions objeto con las variables de configuración y credenciales creadas en los pasos anteriores.

let clientOptions: ClientOptions = {
    contactPoints: [`${contactPoint}:10350`],
    authProvider: authProvider,
    localDataCenter: region,
    sslOptions: sslOptions
};

Cree un Client objeto mediante la clientOptions variable en el constructor.
```
let client = new Client(clientOptions);
```
Conéctese de forma asincrónica al clúster.
```
await client.connect();
```

Cree un nuevo mapeador que tenga como destino el cosmicworks espacio de claves y la product tabla. Asigne al asignador Productel nombre .

const mapper = new Mapper( client, {
    models: {
        'Product': {
            tables: ['product'],
            keyspace: 'cosmicworks'
        }
    }
});

Genere una instancia del mapeador mediante la función forModel y el nombre del mapeador Product.
```
const productMapper = mapper.forModel('Product');
```

Advertencia

La validación completa de la seguridad de la capa de transporte (TLS) está deshabilitada en esta guía para simplificar la autenticación. Para las implementaciones de producción, habilite completamente la validación.

Inserción o actualización de datos

A continuación, actualice los datos nuevos en una tabla. Upserting garantiza que los datos se creen o reemplacen adecuadamente en función de si los mismos datos ya existen en la tabla.

Cree un nuevo objeto en una variable denominada product.

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

Invoque de forma asincrónica la insert función pasando la product variable creada en el paso anterior.
```
await productMapper.insert(product);
```

Defina una nueva interfaz denominada Product con campos correspondientes a la tabla creada anteriormente en esta guía.

Tipo

Id string

Name string

Category string

Quantity int

Price decimal

Clearance bool
```
interface Product {
    id: string;
    name: string;
    category: string;
    quantity: number;
    price: number;
    clearance: boolean;
}
```
Sugerencia

En Node.js, puede crear este tipo en otro archivo o crearlo al final del archivo existente.

	Tipo
`Id`	`string`
`Name`	`string`
`Category`	`string`
`Quantity`	`int`
`Price`	`decimal`
`Clearance`	`bool`

Cree un nuevo objeto de tipo Product. Almacene el objeto en una variable denominada product.

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

Invoque de forma asincrónica la insert función pasando la product variable creada en el paso anterior.
```
await productMapper.insert(product);
```

Leer datos

A continuación, lea los datos que se han insertado o actualizado anteriormente en la tabla.

Cree un objeto anónimo denominado filter. En este objeto, incluya una propiedad denominada id con el mismo valor que el producto creado anteriormente en esta guía.
```
const filter = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};
```
Invoque la función get del mapper pasando la variable filter. Almacene el resultado en una variable denominada matchedProduct.
```
let matchedProduct = await productMapper.get(filter);
```

Cree un objeto anónimo denominado filter. En este objeto, incluya una propiedad denominada id con el mismo valor que el producto creado anteriormente en esta guía.
```
const filter = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};
```
Invoque la función get del mapper pasando la variable filter. Almacene el resultado en una variable denominada matchedProduct de tipo Product.
```
let matchedProduct: Product = await productMapper.get(filter);
```

Consultar datos

Por último, use una consulta para buscar todos los datos que coincidan con un filtro específico de la tabla.

Cree una nueva variable de cadena denominada query con una consulta CQL que coincida con los elementos con el mismo category campo.
```
const query = `
SELECT
    *
FROM
    cosmicworks.product
WHERE
    category = :category
ALLOW FILTERING
`;
```
Cree un objeto anónimo denominado params. En este objeto, incluya una propiedad denominada category con el mismo valor que el producto creado anteriormente en esta guía.
```
const params = {
    category: 'gear-surf-surfboards'
};
```
Invoque de forma asincrónica la execute función pasando las query variables y params como argumentos. Almacene la propiedad del rows resultado como una variable denominada matchedProducts.
```
let { rows: matchedProducts } = await client.execute(query, params);
```
Iteración de los resultados de la consulta invocando el foreach método en la matriz de productos.
```
matchedProducts.forEach(product => {
    // Do something here with each result
});
```

Cree una nueva variable de cadena denominada query con una consulta CQL que coincida con los elementos con el mismo category campo.
```
const query: string = `
SELECT
    *
FROM
    cosmicworks.product
WHERE
    category = :category
ALLOW FILTERING
`;
```
Cree un objeto anónimo denominado params. En este objeto, incluya una propiedad denominada category con el mismo valor que el producto creado anteriormente en esta guía.
```
const params = {
    category: 'gear-surf-surfboards'
};
```
Invoque de forma asincrónica la execute función pasando las query variables y params como argumentos. Almacene el resultado en una variable denominada result de tipo types.ResultSet.
```
let result: types.ResultSet = await client.execute(query, params);
```
Almacene la propiedad del rows resultado como una variable denominada matchedProducts de tipo Product[].
```
let matchedProducts: Product[] = result.rows;
```
Iteración de los resultados de la consulta invocando el foreach método en la matriz de productos.
```
matchedProducts.forEach((product: Product) => {
    // Do something here with each result
});
```

Ejecución del código

Ejecute la aplicación recién creada mediante un terminal en el directorio de la aplicación.

node index.js

npx tsx index.ts

Limpieza de recursos

Cuando ya no necesite la cuenta, quite la cuenta de la suscripción de Azure mediante la eliminación del recurso.

Azure CLI
Azure Portal

az cosmosdb delete \
    --resource-group "<resource-group-name>" \
    --name "<account-name>"

Paso siguiente

Introducción a Azure Cosmos DB para Apache Cassandra

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-07-23