Inicio rápido: Biblioteca cliente de Azure Cosmos DB para Apache Cassandra en Python

Se aplica a: ✅ Apache Cassanda

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

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

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 .

Python 3.12 o posterior

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 un directorio vacío.
Importe el cassandra-driver paquete desde el índice de paquetes de Python (PyPI).
```
pip install cassandra-driver
```
Abra el archivo app.py.

Modelo de objetos

	Descripción
`Cluster`	Representa una conexión específica a un clúster

Autenticar cliente

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

Abra el archivo app.py en el entorno de desarrollo integrado (IDE).
Importe los siguientes tipos desde el cassandra-driver módulo:
- cassandra.cluster.Cluster
- cassandra.auth.PlainTextAuthProvider
```
from cassandra.cluster import Cluster
from cassandra.auth import PlainTextAuthProvider
```
Importe los siguientes tipos desde el ssl módulo:
- ssl.PROTOCOL_TLS_CLIENT
- ssl.SSLContext
- ssl.CERT_NONE
```
from ssl import PROTOCOL_TLS_CLIENT, SSLContext, CERT_NONE
```
Cree variables de cadena para las credenciales recopiladas anteriormente en esta guía. Asigne un nombre a las variables username, passwordy contactPoint.
```
username = "<username>"
password = "<password>"
contactPoint = "<contact-point>"
```
Configure el SSLContext creando una nueva variable denominada ssl_context, estableciendo el protocolo a PROTOCOL_TLS_CLIENT, deshabilitando la comprobación del nombre de host y configurando el modo de verificación en CERT_NONE.
```
ssl_context = SSLContext(PROTOCOL_TLS_CLIENT)
ssl_context.check_hostname = False
ssl_context.verify_mode = CERT_NONE
```
Cree un nuevo PlainTextAuthProvider objeto con las credenciales especificadas en los pasos anteriores. Almacene el resultado en una variable denominada auth_provider.
```
auth_provider = PlainTextAuthProvider(username=username, password=password)
```
Cree un Cluster objeto con las variables de configuración y credenciales creadas en los pasos anteriores. Almacene el resultado en una variable denominada cluster.
```
cluster = Cluster([contactPoint], port=10350, auth_provider=auth_provider, ssl_context=ssl_context)
```

Conéctese al clúster.

session = cluster.connect("cosmicworks")

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 una nueva variable de cadena denominada insertQuery con la consulta del lenguaje de consulta cassandra (CQL) para insertar una nueva fila.

insertQuery = """
INSERT INTO
    product (id, name, category, quantity, price, clearance)
VALUES
    (%(id)s, %(name)s, %(category)s, %(quantity)s, %(price)s, %(clearance)s)
"""

Cree un nuevo objeto con varias propiedades de un nuevo producto y almacénelo en una variable denominada params.

params = {
    "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    "name": "Yamba Surfboard",
    "category": "gear-surf-surfboards",
    "quantity": 12,
    "price": 850.00,
    "clearance": False
}

Use la execute función para ejecutar la consulta con los parámetros especificados.
```
session.execute(insertQuery, params)
```

Leer datos

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

Cree una nueva variable de cadena denominada readQuery con una consulta CQL que coincida con los elementos con el mismo id campo.
```
readQuery = "SELECT * FROM product WHERE id = %s LIMIT 1"
```
Cree una variable de cadena denominada id con el mismo valor que el producto creado anteriormente en esta guía.
```
id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
```
Utilice la función execute para ejecutar la consulta almacenada en readQuery, pasando la variable id como argumento. Almacene el resultado en una variable denominada readResults.
```
readResults = session.execute(readQuery, (id,))
```
Use la one función para obtener el resultado único esperado. Almacene este único resultado en una variable denominada matchedProduct.
```
matchedProduct = readResults.one()
```

Consultar datos

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

Cree variables de cadena denominadas findQuery y category con la consulta CQL y el parámetro requerido.

findQuery = "SELECT * FROM product WHERE category = %s ALLOW FILTERING"
category = "gear-surf-surfboards"

Use las dos variables de cadena y la execute función para consultar varios resultados. Almacene el resultado de esta consulta en una variable denominada findResults.
```
findResults = session.execute(findQuery, (category,))
```
Use un for bucle para recorrer en iteración los resultados de la consulta.
```
for row in findResults:
    # 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.

python app.py

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