Démarrage rapide : Générer une application Go avec le client `gocql` pour gérer les données Azure Cosmos DB for Apache Cassandra

Article
08/15/2024

S’APPLIQUE À : Cassandra

Azure Cosmos DB est un service de base de données multimodèle qui vous permet de créer et d’interroger rapidement des bases de données de documents, de tables, de paires clé/valeur et de graphes avec des capacités de distribution mondiale et de mise à l’échelle horizontale. Dans ce guide de démarrage rapide, vous allez commencer par créer un compte Azure Cosmos DB for Apache Cassandra. Vous allez ensuite exécuter une application Go pour créer un espace de clés et une table Cassandra ainsi que pour exécuter quelques opérations. Cette application Go utilise gocql, qui est un client Cassandra pour le langage Go.

Prérequis

Compte Azure avec un abonnement actif. Créez-en un gratuitement. Vous pouvez également essayez Azure Cosmos DB gratuitement sans abonnement Azure.
Go installé sur votre ordinateur et une expérience de travail avec Go.
Git.

Création d’un compte de base de données

Pour pouvoir créer une base de données, vous devez créer un compte Cassandra avec Azure Cosmos DB.

Dans le menu du portail Azure ou dans la page d’accueil, sélectionnez Créer une ressource.
Dans la page Nouveau, recherchez et sélectionnez Azure Cosmos DB.
Dans la page Azure Cosmos DB, sélectionnez Créer.
À la page API, sélectionnez Créer dans la section Cassandra.

L’API détermine le type de compte à créer. Azure Cosmos DB propose cinq API : NoSQL pour les bases de données de documents, Gremlin pour les bases de données de graphes, MongoDB pour les bases de données de documents, Azure Table et Cassandra. Vous devez créer un compte distinct pour chaque API.

Sélectionnez Cassandra car, dans ce guide de démarrage rapide, vous allez créer une table qui fonctionne avec l’API pour Cassandra.

En savoir plus sur l’API pour Cassandra.

Sur la page Créer un compte Azure Cosmos DB, entrez les paramètres de base du nouveau compte Azure Cosmos DB.

Paramètre	valeur	Description
Abonnement	Votre abonnement	Sélectionnez l’abonnement Azure que vous souhaitez utiliser pour ce compte Azure Cosmos DB.
Groupe de ressources	Création Entrez ensuite le même nom que le nom du compte.	Sélectionnez Créer nouveau. Entrez ensuite le nom du nouveau groupe de ressources pour votre compte. Pour rester simple, utilisez le nom de votre compte Azure Cosmos DB.
Nom du compte	Entrer un nom unique	Entrez un nom unique pour identifier votre compte Azure Cosmos DB. L’URI de votre compte sera cassandra.cosmos.azure.com apposé à votre nom de compte unique. Le nom peut contenir uniquement des lettres minuscules, des chiffres et des traits d’union (-), et doit comporter entre 3 et 31 caractères.
Emplacement	La région la plus proche de vos utilisateurs	Sélectionnez la zone géographique dans laquelle héberger votre compte Azure Cosmos DB. Utilisez l’emplacement le plus proche de vos utilisateurs pour leur donner l’accès le plus rapide possible aux données.
Mode de capacité	Débit approvisionné ou serverless	Sélectionnez Débit approvisionné pour créer un compte dans mode de débit approvisionné. Sélectionnez serverless pour créer un compte en mode serverless.
Appliquer la remise de niveau gratuit Azure Cosmos DB	Appliquer ou Ne pas appliquer	Avec le niveau gratuit d’Azure Cosmos DB, vous recevez gratuitement 1 000 RU/s et 25 Go de stockage dans un compte. Découvrez-en plus sur le niveau gratuit.
Limiter le débit total du compte	Sélectionner pour limiter le débit du compte	Cela est utile si vous souhaitez limiter le débit total du compte à une valeur spécifique.

Notes

Vous pouvez avoir un seul compte Azure Cosmos DB de niveau gratuit par abonnement Azure et vous devez vous inscrire lors de la création du compte. Si vous ne voyez pas l’option permettant d’appliquer la remise de niveau gratuit, cela signifie qu’un autre compte dans l’abonnement a déjà été activé avec le niveau gratuit.

Page de nouveau compte pour Azure Cosmos DB for Apache Cassandra

Sous l’onglet Distribution globale, configurez les informations suivantes. Dans le cadre de ce guide de démarrage rapide, vous pouvez conserver les valeurs par défaut :

Paramètre	valeur	Description
Géoredondance	Désactiver	Activez ou désactivez la diffusion mondiale sur votre compte en appairant votre région avec une région correspondante. Vous pourrez ajouter d’autres régions à votre compte ultérieurement.
Écritures multirégions	Désactiver	La fonctionnalité d’écritures multirégions vous permet de tirer parti du débit provisionné pour vos bases de données et conteneurs à travers le monde.
Zones de disponibilité	Désactiver	Les zones de disponibilité sont des emplacements isolés dans une région Azure. Chaque zone de disponibilité est composée d’un ou de plusieurs centres de données équipés d’une alimentation, d’un système de refroidissement et d’un réseau indépendants.

Notes

Les options suivantes ne sont pas disponibles si vous sélectionnez Serverless comme Mode de capacité :

Appliquer la remise de niveau gratuit
Géo-redondance
Écritures multirégions

Si vous le souhaitez, vous pouvez configurer des informations supplémentaires sous les onglets suivants :
- Réseau :configurez l’accès à partir d’un réseau virtuel.
- Stratégie de sauvegarde : configurez une stratégie de sauvegarde périodique ou continue.
- Chiffrement : utilisez une clé gérée par le service ou une clé gérée par le client.
- Étiquettes : les étiquettes sont des paires nom/valeur qui vous permettent de catégoriser les ressources et d’afficher une facturation centralisée en appliquant la même étiquette à plusieurs ressources et groupes de ressources.
Sélectionnez Revoir + créer.
Passez en revue les paramètres du compte, puis sélectionnez Créer. La création du compte prend quelques minutes. Attendez que la page du portail affiche Votre déploiement est terminé.
Sélectionnez Accéder à la ressource pour accéder à la page du compte Azure Cosmos DB.

Clonage de l’exemple d’application

Commencez par cloner l’application à partir de GitHub.

Ouvrez une invite de commandes, puis créez un dossier nommé git-samples.
```
md "C:\git-samples"
```
Ouvrez une fenêtre de terminal git, comme git bash. Utilisez la commande cd pour accéder au nouveau dossier et installer l’exemple d’application.
```
cd "C:\git-samples"
```
Exécutez la commande suivante pour cloner l’exemple de référentiel : Cette commande crée une copie de l’exemple d’application sur votre ordinateur.
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-go-getting-started.git
```

Vérifier le code

Cette étape est facultative. Si vous souhaitez savoir comment le code crée les ressources de base de données, vous pouvez consulter les extraits de code suivants. Sinon, vous pouvez passer à la section Exécuter l’application

La fonction GetSession (qui fait partie de utils\utils.go) retourne un *gocql.Session qui permet d’exécuter des opérations de cluster telles que l’insertion, la recherche, etc.

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’hôte Cassandra d’Azure Cosmos DB est passé à la fonction gocql.NewCluster afin d’obtenir un struct *gocql.ClusterConfig qui est ensuite configuré pour utiliser le nom d’utilisateur, le mot de passe, le port et la version appropriée de TLS (exigence de sécurité du chiffrement HTTPS/SSL/TLS).

La fonction GetSession est ensuite appelée à partir de la fonction main (main.go).

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

Les informations de connectivité et les informations d’identification sont acceptées sous la forme de variables d’environnement (résolues dans la méthode 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")
    }
}

Cela permet ensuite d’exécuter diverses opérations (qui font partie de operations\setup.go) sur Azure Cosmos DB en commençant par la création de keyspace et table.

Comme son nom l’indique, la fonction DropKeySpaceIfExists supprime keyspace seulement s’il existe.

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 fonction CreateKeySpace sert à créer le 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")
}

Cela donne lieu ensuite à la création de table (user), qui est effectuée par la fonction 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")
}

Une fois que l’espace de clés et la table sont créés, nous appelons les opérations CRUD (qui font partie de operations\crud.go).

InsertUser est utilisé pour créer un User. Il définit les informations utilisateur (ID, nom et ville) en tant qu’arguments de requête à l’aide de 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")
}

FindUser est utilisé pour rechercher un utilisateur (model\user.go) à l’aide d’un identifiant utilisateur spécifique alors que Scan lie les attributs utilisateur (retournés par Cassandra) à des variables individuelles (userid, name, city). Il ne s’agit là que d’une des façons dont vous pouvez utiliser le résultat obtenu en tant que résultat de la requête de recherche

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}
}

FindAllUsers est utilisé pour extraire tous les utilisateurs. SliceMap est utilisé en tant que raccourci pour obtenir toutes les informations de l’utilisateur sous la forme d’un segment de map. Imaginez chaque map sous forme de paires clé-valeur, où le nom de colonne (par exemple user_id) représente la clé avec sa valeur respective.

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
}

Chaque map d’informations utilisateur est converti en User à l’aide de la fonction mapToUser, qui extrait simplement la valeur de sa colonne respective et l’utilise pour créer une instance du 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}
}

Exécution de l'application

Comme indiqué, l’application accepte les informations de connectivité et les informations d’identification sous la forme de variables d’environnement.

Dans votre compte Azure Cosmos DB, sur le portail Azure, sélectionnez Chaîne de connexion.

Copiez les valeurs des attributs suivants (CONTACT POINT, PORT, USERNAME et PRIMARY PASSWORD), puis affectez-leur les variables d’environnement respectives

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">

Dans la fenêtre de terminal, accédez au dossier approprié. Par exemple :

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

Dans le terminal, exécutez la commande suivante pour démarrer l’application.

go run main.go

La fenêtre de terminal affiche des notifications pour les différentes opérations, notamment la configuration de l’espace de clés et de la table, la création des utilisateurs, etc.
Dans le portail Azure, ouvrez l’Explorateur de données pour interroger, modifier et utiliser ces nouvelles données.

Vérification des contrats SLA dans le portail Azure

Le portail Azure surveille le débit, le stockage, la disponibilité, la latence et la cohérence de votre compte Azure Cosmos DB. Des graphiques de métriques associées à un contrat de niveau Service (SLA) Azure Cosmos DB montrent la valeur des contrats SLA par rapport aux performances réelles. Cette suite de métriques vous permet de superviser vos contrats SLA de manière transparente.

Pour consulter les métriques et les contrats SLA :

Sélectionnez Métriques dans le menu de navigation de votre compte Azure Cosmos DB.
Sélectionnez un onglet comme Latence, puis sélectionnez un intervalle de temps à droite. Comparez les lignes Réel et SLA des graphiques.
Consultez les métriques des autres onglets.

Nettoyer les ressources

Quand vous en avez terminé avec votre application et votre compte Azure Cosmos DB, vous pouvez supprimer les ressources Azure que vous avez créées afin d’éviter des frais supplémentaires. Pour supprimer les ressources :

Depuis la barre de recherche du portail Azure, recherchez et sélectionnez Groupes de ressources.
Dans la liste, sélectionnez le groupe de ressources créé pour ce guide de démarrage rapide.
Dans la page Vue d’ensemble du groupe de ressources, sélectionnez Supprimer un groupe de ressources.
Dans la fenêtre suivante, entrez le nom du groupe de ressources à supprimer, puis sélectionnez Supprimer.

Étapes suivantes

Dans ce guide de démarrage rapide, vous avez appris à créer un compte Azure Cosmos DB avec l’API pour Cassandra. De plus, vous avez appris à exécuter une application Go, qui crée une base de données et un conteneur Cassandra. Vous pouvez maintenant importer des données supplémentaires dans votre compte Azure Cosmos DB.

Importer des données Cassandra dans Azure Cosmos DB

Partage via

Démarrage rapide : Générer une application Go avec le client `gocql` pour gérer les données Azure Cosmos DB for Apache Cassandra

Prérequis

Création d’un compte de base de données

Clonage de l’exemple d’application

Vérifier le code

Exécution de l'application

Vérification des contrats SLA dans le portail Azure

Nettoyer les ressources

Étapes suivantes

Commentaires

Ressources supplémentaires

Partage via

Démarrage rapide : Générer une application Go avec le client gocql pour gérer les données Azure Cosmos DB for Apache Cassandra

Prérequis

Création d’un compte de base de données

Clonage de l’exemple d’application

Vérifier le code

Exécution de l'application

Vérification des contrats SLA dans le portail Azure

Nettoyer les ressources

Étapes suivantes

Commentaires

Ressources supplémentaires

Démarrage rapide : Générer une application Go avec le client `gocql` pour gérer les données Azure Cosmos DB for Apache Cassandra