Avvio rapido: Creare un'app Go con il client gocql per gestire i dati di Azure Cosmos DB for Apache Cassandra

SI APPLICA A: Cassandra

• .NET
• .NET Core
• Java v3
• Java v4
• Node.js
• Python
• Golang

Azure Cosmos DB è un servizio di database modello che consente di creare ed eseguire rapidamente query su database di documenti, tabelle, valori chiave e grafi, con funzionalità di scalabilità orizzontale e distribuzione globale. In questo argomento di avvio rapido si inizierà creando un account Azure Cosmos DB for Apache Cassandra. Si eseguirà quindi un'applicazione Go per creare gli elementi table e keyspace di Cassandra e quindi eseguire alcune operazioni. Questa app Go usa gocql, che è un client Cassandra per il linguaggio Go.

Prerequisiti

• Un account Azure con una sottoscrizione attiva. Crearne una gratuitamente. In alternativa, è possibile provare gratuitamente Azure Cosmos DB senza una sottoscrizione di Azure.
• Go installato nel computer e conoscenza del funzionamento di Go.
• Git.

Creare un account di database

Prima di poter creare un database, è necessario creare un account di Cassandra con Azure Cosmos DB.

1. Nel menu del portale di Azure o dalla pagina Home selezionare Crea una risorsa.

2. Nella pagina Nuovo cercare e selezionare Azure Cosmos DB.

3. Nella pagina Azure Cosmos DB selezionare Crea.

4. Nella pagina API, selezionare Crea nella sezione Cassandra.

   L'API determina il tipo di account da creare. Azure Cosmos DB mette a disposizione cinque API: NoSQL per i database di documenti, Gremlin per i database di grafi, MongoDB per i database di documenti, Azure Table e Cassandra. È necessario creare un account separato per ogni API.

   Selezionare Cassandra, poiché in questo avvio rapido si creerà una tabella che utilizza l'API per Cassandra.

   Altre informazioni sull'API per Cassandra.

5. Nella pagina Crea account Azure Cosmos DB, immettere le impostazioni di base per il nuovo account Azure Cosmos DB.

   Impostazione	valore	Descrizione
   Subscription	Sottoscrizione in uso	Selezionare la sottoscrizione di Azure da usare per l'account Azure Cosmos DB.
   Gruppo di risorse	Crea nuovo Immettere quindi lo stesso nome specificato nome dell'account.	Selezionare Crea nuovo. Immettere quindi il nome di un nuovo gruppo di risorse per l'account. Per semplicità, usare lo stesso nome usato come nome dell'account Azure Cosmos DB.
   Nome conto	Immettere un nome univoco	Immettere un nome univoco per identificare l'account Azure Cosmos DB. L'URI dell'account sarà cassandra.cosmos.azure.com e verrà aggiunto al nome dell'account univoco. Il nome dell'account può contenere solo lettere minuscole, numeri e trattini e deve avere una lunghezza compresa tra 3 e 31 caratteri.
   Ufficio	Area più vicina ai propri utenti	Selezionare una posizione geografica in cui ospitare l'account Azure Cosmos DB. Usare la località più vicina agli utenti per offrire loro la massima velocità di accesso ai dati.
   Modalità di capacità	Velocità effettiva con provisioning o Serverless	Selezionare Provisioning velocità effettiva per creare un account in modalità Provisioning velocità effettiva. Selezionare Serverless per creare un account in modalità Serverless.
   Applicare lo sconto del livello gratuito di Azure Cosmos DB	Applicare o non applicare	Il livello gratuito di Azure Cosmos DB offre i primi 1000 UR/s e 25 GB di spazio di archiviazione gratuiti per account. Altre informazioni sul livello gratuito.
   Limitare la velocità effettiva totale dell'account	Selezionare per limitare la velocità effettiva dell'account	Questa opzione è utile se si vuole limitare la velocità effettiva totale dell'account in base a un valore specifico.

   Nota

   È possibile avere fino a un account Azure Cosmos DB del livello gratuito per ogni sottoscrizione di Azure ed è necessario acconsentire esplicitamente durante la creazione dell'account. Se l'opzione per l'applicazione dello sconto per il livello gratuito non è visualizzata, un altro account nella sottoscrizione è già stato abilitato per il livello gratuito.

   

6. Nella scheda Distribuzione globale configurare i dettagli seguenti. Ai fini di questa guida introduttiva è possibile lasciare i valori predefiniti:

   Impostazione	valore	Descrizione
   Ridondanza geografica	Disabilita	Abilitare o disabilitare la distribuzione globale nell'account associando la propria area a un'altra area. È possibile aggiungere altre aree al proprio account in un secondo momento.
   Scritture in più aree	Disabilita	La funzionalità Scritture in più aree consente di sfruttare la velocità effettiva di cui è stato effettuato il provisioning per i database e i contenitori in tutto il mondo.
   Zone di disponibilità	Disabilita	Le zone di disponibilità sono località isolate all'interno di un'area di Azure. Ogni zona è costituita da uno o più data center dotati di impianti indipendenti per l'alimentazione, il raffreddamento e la connettività di rete.

   Nota

   Le opzioni seguenti non sono disponibili se si seleziona Serverless come modalità di capacità:

   • Applica sconto livello gratuito
   • Ridondanza geografica
   • Scritture in più aree

7. Facoltativamente, è possibile configurare i dettagli aggiuntivi nelle schede seguenti:

   • Rete: consente di configurare l'accesso da una rete virtuale.
   • Criteri di backup: consente di configurare i criteri di backup periodici o continui.
   • Crittografia: consente di usare una chiave gestita dal servizio o una chiave gestita dal cliente.
   • Tag: i tag sono coppie nome-valore che consentono di classificare le risorse e visualizzare dati di fatturazione consolidati tramite l'applicazione dello stesso tag a più risorse e gruppi di risorse.

8. Selezionare Rivedi e crea.

9. Esaminare le impostazioni dell'account e quindi selezionare Crea. La creazione dell'account richiede alcuni minuti. Attendere che la pagina del portale visualizzi La distribuzione è stata completata.

   

10. Selezionare Vai alla risorsa per passare alla pagina dell'account Azure Cosmos DB.

Clonare l'applicazione di esempio

Per iniziare, clonare l'applicazione da GitHub.

1. Aprire un prompt dei comandi e creare una cartella denominata git-samples.

   md "C:\git-samples"
   

2. Aprire una finestra del terminale Git, ad esempio Git Bash. Usare il comando cd per passare alla nuova cartella e installare l'app di esempio.

   cd "C:\git-samples"
   

3. Eseguire il comando seguente per clonare l'archivio di esempio. Questo comando crea una copia dell'app di esempio nel computer in uso.

   git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-go-getting-started.git
   

Esaminare il codice

Questo passaggio è facoltativo. Per comprendere in che modo il codice crea le risorse del database, è possibile esaminare i frammenti di codice seguenti. In caso contrario, passare direttamente a Eseguire l'applicazione

La funzione GetSession (inclusa in utils\utils.go) restituisce un oggetto *gocql.Session usato per eseguire operazioni del cluster, ad esempio inserimento, ricerca e così via.

func GetSession(cosmosCassandraContactPoint, cosmosCassandraPort, cosmosCassandraUser, cosmosCassandraPassword string) *gocql.Session {
    clusterConfig := gocql.NewCluster(cosmosCassandraContactPoint)
    port, err := strconv.Atoi(cosmosCassandraPort)
    
    clusterConfig.Authenticator = gocql.PasswordAuthenticator{Username: cosmosCassandraUser, Password: cosmosCassandraPassword}
    clusterConfig.Port = port
    clusterConfig.SslOpts = &gocql.SslOptions{Config: &tls.Config{MinVersion: tls.VersionTLS12}}
    clusterConfig.ProtoVersion = 4
    
    session, err := clusterConfig.CreateSession()
    ...
    return session
}

L'host Cassandra di Azure Cosmos DB viene passato alla funzione gocql.NewCluster per ottenere uno struct *gocql.ClusterConfig che viene quindi configurato per usare il nome utente, la password, la porta e la versione appropriata di TLS (requisito di sicurezza della crittografia HTTPS/SSL/TLS)

La funzione GetSession viene quindi chiamata dalla funzione main (main.go).

func main() {
    session := utils.GetSession(cosmosCassandraContactPoint, cosmosCassandraPort, cosmosCassandraUser, cosmosCassandraPassword)
    defer session.Close()
    ...
}

Le credenziali e le informazioni sulla connettività vengono accettate sotto forma di variabili di ambiente (risolte nel metodo init)

func init() {
    cosmosCassandraContactPoint = os.Getenv("COSMOSDB_CASSANDRA_CONTACT_POINT")
    cosmosCassandraPort = os.Getenv("COSMOSDB_CASSANDRA_PORT")
    cosmosCassandraUser = os.Getenv("COSMOSDB_CASSANDRA_USER")
    cosmosCassandraPassword = os.Getenv("COSMOSDB_CASSANDRA_PASSWORD")

    if cosmosCassandraContactPoint == "" || cosmosCassandraUser == "" || cosmosCassandraPassword == "" {
        log.Fatal("missing mandatory environment variables")
    }
}

Viene quindi usata per eseguire varie operazioni (incluse in operations\setup.go) su Azure Cosmos DB a partire dalla creazione di keyspace e table.

Come suggerisce il nome, la funzione DropKeySpaceIfExists elimina l'elemento keyspace solo se esiste.

const dropKeyspace = "DROP KEYSPACE IF EXISTS %s"

func DropKeySpaceIfExists(keyspace string, session *gocql.Session) {
    err := utils.ExecuteQuery(fmt.Sprintf(dropKeyspace, keyspace), session)
    if err != nil {
        log.Fatal("Failed to drop keyspace", err)
    }
    log.Println("Keyspace dropped")
}

La funzione CreateKeySpace consente di creare l'elemento keyspace (user_profile)

const createKeyspace = "CREATE KEYSPACE %s WITH REPLICATION = { 'class' : 'NetworkTopologyStrategy', 'datacenter1' : 1 }"

func CreateKeySpace(keyspace string, session *gocql.Session) {
    err := utils.ExecuteQuery(fmt.Sprintf(createKeyspace, keyspace), session)
    if err != nil {
        log.Fatal("Failed to create keyspace", err)
    }
    log.Println("Keyspace created")
}

Questa operazione è seguita dalla creazione della tabella (user) che viene gestita dalla funzione CreateUserTable

const createTable = "CREATE TABLE %s.%s (user_id int PRIMARY KEY, user_name text, user_bcity text)"

func CreateUserTable(keyspace, table string, session *gocql.Session) {
    err := session.Query(fmt.Sprintf(createTable, keyspace, table)).Exec()
    if err != nil {
        log.Fatal("failed to create table ", err)
    }
    log.Println("Table created")
}

Dopo aver creato gli elementi keyspace e table, vengono richiamate le operazioni CRUD (incluse in operations\crud.go).

Per creare un elemento User, si usa InsertUser. Questa funzione consente di impostare le informazioni utente (ID, nome e città) come argomenti di query usando Bind

const createQuery = "INSERT INTO %s.%s (user_id, user_name , user_bcity) VALUES (?,?,?)"

func InsertUser(keyspace, table string, session *gocql.Session, user model.User) {
    err := session.Query(fmt.Sprintf(createQuery, keyspace, table)).Bind(user.ID, user.Name, user.City).Exec()
    if err != nil {
        log.Fatal("Failed to create user", err)
    }
    log.Println("User created")
}

Per cercare un utente (model\user.go) usando un ID utente specifico, si usa FindUser, mentre Scan consente di associare gli attributi utente (restituiti da Cassandra) a singole variabili (userid, name, city). Questo è solo uno dei modi in cui è possibile usare il risultato ottenuto come risultato della query di ricerca

const selectQuery = "SELECT * FROM %s.%s where user_id = ?"

func FindUser(keyspace, table string, id int, session *gocql.Session) model.User {
    var userid int
    var name, city string
    err := session.Query(fmt.Sprintf(selectQuery, keyspace, table)).Bind(id).Scan(&userid, &name, &city)

    if err != nil {
        if err == gocql.ErrNotFound {
            log.Printf("User with id %v does not exist\n", id)
        } else {
            log.Printf("Failed to find user with id %v - %v\n", id, err)
        }
    }
    return model.User{ID: userid, Name: name, City: city}
}

Per recuperare tutti gli utenti, si usa FindAllUsers. SliceMap è la versione abbreviata per ottenere tutte le informazioni sull'utente sotto forma di sezione dell'elemento map. Si pensi a ogni elemento map come una coppia chiave-valore in cui il nome della colonna (ad esempio user_id) rappresenta la chiave, unitamente al rispettivo valore.

const findAllUsersQuery = "SELECT * FROM %s.%s"

func FindAllUsers(keyspace, table string, session *gocql.Session) []model.User {
    var users []model.User
    results, _ := session.Query(fmt.Sprintf(findAllUsersQuery, keyspace, table)).Iter().SliceMap()

    for _, u := range results {
        users = append(users, mapToUser(u))
    }
    return users
}

Ogni elemento map delle informazioni utente viene convertito in un elemento User tramite la funzione mapToUser, che estrae semplicemente il valore dalla rispettiva colonna e lo usa per creare un'istanza dello struct User

func mapToUser(m map[string]interface{}) model.User {
    id, _ := m["user_id"].(int)
    name, _ := m["user_name"].(string)
    city, _ := m["user_bcity"].(string)

    return model.User{ID: id, Name: name, City: city}
}

Eseguire l'applicazione

Come menzionato in precedenza, l'applicazione accetta le informazioni su credenziali e connettività sotto forma di variabili di ambiente.

1. Nell'account Azure Cosmos DB nel portale di Azure selezionare Stringa di connessione.

   

Copiare i valori relativi agli attributi seguenti (CONTACT POINT, PORT, USERNAME e PRIMARY PASSWORD) e impostarli sulle rispettive variabili di ambiente

set COSMOSDB_CASSANDRA_CONTACT_POINT=<value for "CONTACT POINT">
set COSMOSDB_CASSANDRA_PORT=<value for "PORT">
set COSMOSDB_CASSANDRA_USER=<value for "USERNAME">
set COSMOSDB_CASSANDRA_PASSWORD=<value for "PRIMARY PASSWORD">

Nella finestra del terminale passare alla cartella corretta. Ad esempio:

cd "C:\git-samples\azure-cosmosdb-cassandra-go-getting-started"

2. Nel terminale eseguire il comando seguente per avviare l'applicazione.

go run main.go

3. Nella finestra del terminale vengono visualizzate le notifiche per le varie operazioni, ad esempio la configurazione di keyspace e table, la creazione dell'utente e così via.

4. Nel portale di Azure aprire Esplora dati per modificare e usare questi nuovi dati, nonché eseguire query su di essi.

   

Esaminare i contratti di servizio nel portale di Azure

Il portale di Azure monitora la velocità effettiva dell'account Azure Cosmos DB, l'archiviazione, la disponibilità, la latenza e la coerenza. I grafici per le metriche associate a un contratto di servizio di Azure Cosmos DB indicano il valore previsto dal contratto di servizio rispetto alle prestazioni effettive. Questo gruppo di metriche garantisce la trasparenza nel monitoraggio dei contratti di servizio.

Per esaminare le metriche e i contratti di servizio:

1. Selezionare Metriche nel menu di spostamento dell'account Azure Cosmos DB.

2. Selezionare una scheda, ad esempio Latenza, e quindi un intervallo di tempo sulla destra. Confrontare le righe relative ai valori effettivi e ai valori del contratto di servizio nei grafici.

   

3. Esaminare le metriche nelle altre schede.

Pulire le risorse

Dopo aver completato le operazioni con l'app e l'account Azure Cosmos DB, è possibile eliminare le risorse di Azure create in modo da non incorrere in altri costi. Per eliminare le risorse:

1. Nella barra di ricerca del portale di Azure cercare e selezionare Gruppi di risorse.

2. Selezionare nell'elenco il gruppo di risorse creato in questa guida di avvio rapido.

   

3. Nella pagina Panoramica del gruppo di risorse selezionare Elimina gruppo di risorse.

   

4. Nella finestra successiva immettere il nome del gruppo di risorse da eliminare e quindi selezionare Elimina.

Passaggi successivi

In questo argomento di avvio rapido si è appreso come creare un account Azure Cosmos DB con l'API per Cassandra e come eseguire un'app Go per creare un contenitore e un database Cassandra. È ora possibile importare dati aggiuntivi nell'account Azure Cosmos DB.

Importare i dati di Cassandra in Azure Cosmos DB