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

Si applica a: ✅ Apache Cassanda

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

Documentazione | Codice sorgente | della libreriaPacchetto (Go)

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.

Go 1.24 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.
Creare un nuovo modulo Go.
```
go mod init quickstart
```
Importare il github.com/apache/cassandra-gocql-driver/v2 pacchetto da Go.
```
go get github.com/apache/cassandra-gocql-driver/v2
```
Creare il file main.go .
Aggiungere il boilerplate dell'applicazione Go.
```
package main

func main() {    
}
```
Importante

I passaggi rimanenti all'interno di questa guida presuppongono che si stia aggiungendo il codice all'interno della main funzione.

Modello a oggetti

	Descrizione
`Cluster`	Rappresenta una connessione specifica a un cluster
`Session`	Entità che contengono 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 main.go nell'ambiente di sviluppo integrato (IDE).
All'interno della main funzione importare i pacchetti seguenti insieme al github.com/apache/cassandra-gocql-driver/v2 pacchetto:
- context
- crypto/tls
```
import (
    "context"
    "crypto/tls"
    "github.com/apache/cassandra-gocql-driver/v2"
)
```
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>"
```
Configurare un'istanza del PasswordAuthenticator tipo con le credenziali specificate nei passaggi precedenti. Archiviare il risultato in una variabile denominata authentication.
```
authentication := gocql.PasswordAuthenticator{
    Username: username,
    Password: password,
}
```
Configurare un'istanza di SslOptions con una versione minima di Transport Layer Security (TLS) 1.2 e la contactPoint variabile come nome del server di destinazione. Archiviare il risultato in una variabile denominata sslOptions.
```
sslOptions := &gocql.SslOptions{
    Config: &tls.Config{
        MinVersion: tls.VersionTLS12,
        ServerName: contactPoint,
    },
}
```
Creare una nuova specifica del cluster usando NewCluster e la variabile contactPoint.
```
cluster := gocql.NewCluster(contactPoint)
```
Configurare l'oggetto specifica del cluster usando le credenziali e le variabili di configurazione create nei passaggi precedenti.
```
cluster.SslOpts = sslOptions
cluster.Authenticator = authentication
```

Configurare il resto dell'oggetto specifica del cluster con questi valori statici.

cluster.Keyspace = "cosmicworks"
cluster.Port = 10350
cluster.ProtoVersion = 4

Creare una nuova sessione che si connette al cluster usando CreateSession.
```
session, _ := cluster.CreateSession()
```
Configurare la sessione per richiamare la Close funzione dopo la restituzione della main funzione.
```
defer session.Close()
```
Creare un nuovo Background oggetto di contesto e archiviarlo nella ctx variabile .
```
ctx := context.Background()
```

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.

Definire un nuovo tipo denominato Product con i campi corrispondenti alla tabella creata in precedenza in questa guida.
```
type Product struct {
    id        string
    name      string
    category  string
    quantity  int
    clearance bool
}
```
Suggerimento

In Go è possibile creare questo tipo in un altro file o crearlo alla fine del file esistente.

Creare un nuovo oggetto di tipo Product. Archiviare l'oggetto in una variabile denominata product.

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

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, clearance)
    VALUES
        (?, ?, ?, ?, ?)
`

Usare le funzioni di Query e ExecContext per eseguire la query. Passa varie proprietà della variabile product come parametri di query.

_ = session.Query(
    insertQuery,
    product.id, 
    product.name, 
    product.category, 
    product.quantity, 
    product.clearance,
).ExecContext(ctx)

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
        id,
        name,
        category,
        quantity,
        clearance
    FROM
        product
    WHERE id = ?
    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" 
```
Creare un'altra variabile denominata matchedProduct in cui archiviare il risultato di questa operazione.
```
var matchedProduct Product
```

Usare le Queryfunzioni , ConsistencyIterContext, e Scan insieme per trovare il singolo elemento che corrisponde alla query e assegnarne le proprietà alla matchedProduct variabile .

session.Query(
    readQuery,
    &id,
).Consistency(gocql.One).IterContext(ctx).Scan(
    &matchedProduct.id,
    &matchedProduct.name,
    &matchedProduct.category,
    &matchedProduct.quantity,
    &matchedProduct.clearance,
)

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
        id,
        name,
        category,
        quantity,
        clearance
    FROM
        product
    WHERE
        category = ?
    ALLOW FILTERING
`

category := "gear-surf-surfboards"

Usare le funzioni Query, Consistency, IterContext e Scanner insieme per creare uno scanner che possa iterare su più elementi che corrispondono alla query.
```
queriedProducts := session.Query(
    findQuery, 
    &category,
).Consistency(gocql.All).IterContext(ctx).Scanner()
```

Usare le funzioni Next e Scan per scorrere i risultati della query e assegnare le proprietà di ogni risultato alla variabile interna queriedProduct.

for queriedProducts.Next() {
    var queriedProduct Product
    queriedProducts.Scan(
        &queriedProduct.id,
        &queriedProduct.name,
        &queriedProduct.category,
        &queriedProduct.quantity,
        &queriedProduct.clearance,
    )
    // Do something here with each result
}

Eseguire il codice

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

go run .

Pulire le risorse