Guida introduttiva: Libreria client di Azure Cosmos DB for Apache Cassandra per Python

Si applica a: ✅ Apache Cassanda

Introduzione alla libreria client di Azure Cosmos DB per Apache Cassandra per Python per archiviare, gestire ed eseguire query sui dati non strutturati. Seguire la procedura descritta in questa guida per creare un nuovo account, installare una libreria client Python, connettersi all'account, eseguire operazioni comuni ed eseguire query sui dati di esempio finali.

Documentazione | Codice sorgente | della libreriaPacchetto (PyPI)

Prerequisiti

Una sottoscrizione di Azure
- Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

Versione più recente dell'interfaccia della riga di comando di Azure in Azure Cloud Shell.
- Se si preferisce eseguire i comandi CLI di riferimento in locale, accedere all'interfaccia della riga di comando di Azure usando il comando az login.

Python 3.12 o versione successiva

Configurazione

Prima di tutto, configurare l'account e l'ambiente di sviluppo per questa guida. Questa sezione illustra il processo di creazione di un account, il recupero delle credenziali e la preparazione dell'ambiente di sviluppo.

Crea un account

Per iniziare, creare un'API per l'account Apache Cassandra. Dopo aver creato l'account, creare il keyspace e le risorse della tabella.

Interfaccia della riga di comando di Azure
Portale di Azure

Se non si ha già un gruppo di risorse di destinazione, usare il az group create comando per creare un nuovo gruppo di risorse nella sottoscrizione.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

Usare il az cosmosdb create comando per creare un nuovo account Azure Cosmos DB per Apache Cassandra con le impostazioni predefinite.

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

Creare un nuovo keyspace utilizzando az cosmosdb cassandra keyspace create denominato cosmicworks.

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

Creare un nuovo oggetto JSON per rappresentare lo schema usando un comando Bash a più righe. Usare quindi il az cosmosdb cassandra table create comando per creare una nuova tabella denominata 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"

Accedere al portale di Azure (https://portal.azure.com).
Immettere Azure Cosmos DB nella barra di ricerca globale.
In Servizi selezionare Azure Cosmos DB.
Nel riquadro Azure Cosmos DB selezionare Crea e quindi Azure Cosmos DB per Apache Cassandra nella scheda Altri .
Selezionare Account del database delle unità richieste (UR) per il tipo di account.

Nel riquadro Dati principali configurare le opzioni seguenti, quindi selezionare Rivedi e crea:

	Valore
Tipo di carico di lavoro	Attività di apprendimento
Abbonamento	Selezionare la sottoscrizione di Azure
Gruppo di risorse	Creare un nuovo gruppo di risorse o selezionare un gruppo di risorse esistente
Account Name:	Specificare un nome univoco globale
Zone di disponibilità	Disabilitare
Ubicazione	Selezionare un'area di Azure supportata per la sottoscrizione

Suggerimento

È possibile lasciare qualsiasi opzione non specificata impostata sui valori predefiniti. È anche possibile configurare l'account per limitare la velocità effettiva totale dell'account a 1.000 unità richiesta al secondo (UR/sec) o abilitare il livello gratuito per ridurre al minimo i costi.

Nel riquadro Rivedi e crea attendere il completamento della convalida dell'account e quindi selezionare Crea.
Il portale passa automaticamente al riquadro Distribuzione. Attendere il completamento della distribuzione.
Al termine della distribuzione, selezionare Vai alla risorsa per passare alla nuova API per l'account Apache Cassandra.
Nel menu delle risorse selezionare l'opzione Esplora dati .
In Esplora dati selezionare + Nuova tabella.

Nella finestra di dialogo Aggiungi tabella configurare le opzioni seguenti e quindi selezionare OK:

	Valore
Keyspace	Crea nuovo
Nome dello spazio delle chiavi	`cosmicworks`
Nome della tabella	`product`
Schema della tabella	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

Suggerimento

È possibile lasciare qualsiasi opzione non specificata impostata sui valori predefiniti.

Ottenere le credenziali

Ottenere ora la password per la libreria client da usare per creare una connessione all'account creato di recente.

Interfaccia della riga di comando di Azure
Portale di Azure

Usare az cosmosdb show per ottenere il punto di contatto e il nome utente per l'account.

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

Registrare il valore delle proprietà contactPoint e username dall'output dei comandi precedenti. Questi valori delle proprietà sono il punto di contatto e il nome utente usati più avanti in questa guida per connettersi all'account con la libreria.

Usare az cosmosdb keys list per ottenere le chiavi per l'account.

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

Registrare il valore della primaryMasterKey proprietà dall'output dei comandi precedenti. Il valore di questa proprietà è la password usata più avanti in questa guida per connettersi all'account con la libreria.

Preparare l'ambiente di sviluppo

Configurare quindi l'ambiente di sviluppo con un nuovo progetto e la libreria client. Questo passaggio è l'ultimo prerequisito necessario prima di passare al resto di questa guida.

Iniziare in una directory vuota.
Importare il cassandra-driver pacchetto dall'indice del pacchetto Python (PyPI).
```
pip install cassandra-driver
```
Creare il file app.py.

Modello a oggetti

	Descrizione
`Cluster`	Rappresenta una connessione specifica a un cluster

Autenticare il client

Per iniziare, autenticare il client usando le credenziali raccolte in precedenza in questa guida.

Aprire il file app.py nell'ambiente di sviluppo integrato (IDE).
Importare i tipi seguenti dal cassandra-driver modulo:
- cassandra.cluster.Cluster
- cassandra.auth.PlainTextAuthProvider
```
from cassandra.cluster import Cluster
from cassandra.auth import PlainTextAuthProvider
```
Importare i tipi seguenti dal ssl modulo:
- ssl.PROTOCOL_TLS_CLIENT
- ssl.SSLContext
- ssl.CERT_NONE
```
from ssl import PROTOCOL_TLS_CLIENT, SSLContext, CERT_NONE
```
Creare variabili stringa per le credenziali raccolte in precedenza in questa guida. Nomina le variabili username, password e contactPoint.
```
username = "<username>"
password = "<password>"
contactPoint = "<contact-point>"
```
SSLContext Configurare creando una nuova variabile denominata ssl_context, impostando il protocollo su PROTOCOL_TLS_CLIENT, disabilitando il controllo del nome host e impostando la modalità di verifica su CERT_NONE.
```
ssl_context = SSLContext(PROTOCOL_TLS_CLIENT)
ssl_context.check_hostname = False
ssl_context.verify_mode = CERT_NONE
```
Creare un nuovo PlainTextAuthProvider oggetto con le credenziali specificate nei passaggi precedenti. Archiviare il risultato in una variabile denominata auth_provider.
```
auth_provider = PlainTextAuthProvider(username=username, password=password)
```
Creare un Cluster oggetto usando le credenziali e le variabili di configurazione create nei passaggi precedenti. Archiviare il risultato in una variabile denominata cluster.
```
cluster = Cluster([contactPoint], port=10350, auth_provider=auth_provider, ssl_context=ssl_context)
```

Connettersi al cluster.

session = cluster.connect("cosmicworks")

Avvertimento

La convalida completa di TLS (Transport Layer Security) è disabilitata in questa guida per semplificare l'autenticazione. Per le distribuzioni di produzione, abilitare completamente la convalida.

Aggiornare o inserire i dati

Eseguire quindi l'operazione di upsert dei nuovi dati in una tabella. L'upserting garantisce che i dati vengano creati o sostituiti in modo appropriato a seconda che nella tabella esistano già gli stessi dati.

Creare una nuova variabile stringa denominata insertQuery con la query CQL (Cassandra Query Language) per inserire una nuova riga.

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

Creare un nuovo oggetto con varie proprietà di un nuovo prodotto e archiviarlo in una variabile denominata params.

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

Usare la execute funzione per eseguire la query con i parametri specificati.
```
session.execute(insertQuery, params)
```

Leggere dati

Leggere quindi i dati precedentemente inseriti nella tabella.

Creare una nuova variabile stringa denominata readQuery con una query CQL che corrisponde agli elementi con lo stesso id campo.
```
readQuery = "SELECT * FROM product WHERE id = %s LIMIT 1"
```
Creare una variabile stringa denominata id con lo stesso valore del prodotto creato in precedenza in questa guida.
```
id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
```
Usa la funzione execute per eseguire la query archiviata in readQuery, passando la variabile id come argomento. Archiviare il risultato in una variabile denominata readResults.
```
readResults = session.execute(readQuery, (id,))
```
Usare la one funzione per ottenere il risultato singolo previsto. Archiviare questo singolo risultato in una variabile denominata matchedProduct.
```
matchedProduct = readResults.one()
```

Dati di query

Usare infine una query per trovare tutti i dati corrispondenti a un filtro specifico nella tabella.

Creare variabili stringa denominate findQuery e category con la query CQL e il parametro obbligatorio.

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

Usare le due variabili stringa e la funzione execute per eseguire query su più risultati. Archiviare il risultato di questa query in una variabile denominata findResults.
```
findResults = session.execute(findQuery, (category,))
```

Usare un ciclo for per scorrere i risultati della query.

for row in findResults:
    # Do something here with each result

Eseguire il codice

Eseguire l'applicazione appena creata usando un terminale nella directory dell'applicazione.

python app.py

Pulire le risorse

Quando l'account non è più necessario, rimuovere l'account dalla sottoscrizione di Azure eliminando la risorsa.

Interfaccia della riga di comando di Azure
Portale di Azure

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

Passo successivo

Panoramica di Azure Cosmos DB per Apache Cassandra

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-07-25