Créer une application Java pour gérer les données Azure Cosmos DB for Apache Cassandra (pilote v4)

Article
03/22/2023

S’APPLIQUE À : Cassandra

Dans le cadre de ce guide de démarrage rapide, vous allez créer un compte Azure Cosmos DB for Apache Cassandra et utiliser une application Java Cassandra clonée à partir de GitHub pour créer une base de données et un conteneur Cassandra avec les pilotes Apache Cassandra v4.x pour Java. 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.

Prérequis

Compte Azure avec un abonnement actif. Créez-en un gratuitement. Ou bien essayez Azure Cosmos DB gratuitement sans abonnement Azure.
Kit de développement Java (JDK) 8. Faites pointer la variable d’environnement JAVA_HOME vers le dossier dans lequel le JDK est installé.
Archive binaire Maven. Sur Ubuntu, exécutez apt-get install maven pour installer Maven.
Git. Sur Ubuntu, exécutez sudo apt-get install git pour installer Git.

Notes

Ceci est un simple guide de démarrage rapide qui utilise la version 4 du pilote open source Apache Cassandra pour Java. Dans la plupart des cas, vous devez être en mesure de connecter une application Java existante dépendante d’Apache Cassandra à Azure Cosmos DB for Apache Cassandra sans aucune modification de votre code existant. Nous vous recommandons cependant d’ajouter notre extension Java personnalisée, qui comprend des stratégies personnalisées de nouvelle tentative et d’équilibrage de charge ainsi que des paramètres de connexion recommandés pour une meilleure expérience globale. Ceci permet de gérer la limitation du débit et le basculement au niveau de l’application dans Azure Cosmos DB quand c’est nécessaire. Vous trouverez un exemple complet qui implémente l’extension ici.

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

Pour pouvoir créer une base de données de documents, 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

À présent, travaillons sur le code. Nous allons maintenant cloner une application Cassandra à partir de GitHub, configurer la chaîne de connexion et l’exécuter. Vous verrez combien il est facile de travailler par programmation avec des données.

Ouvrez une invite de commandes. Créez un dossier nommé git-samples. Ensuite, fermez l’invite de commandes.
```
md "C:\git-samples"
```
Ouvrez une fenêtre de terminal git comme Git Bash et utilisez la commande cd pour accéder au nouveau dossier d’installation pour 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-java-getting-started-v4.git
```

Vérifier le code

Cette étape est facultative. Si vous voulez 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 à l’étape Mise à jour de votre chaîne de connexion. Tous ces extraits de code sont tirés du fichier src/main/java/com/azure/cosmosdb/cassandra/util/CassandraUtils.java.

Le CqlSession se connecte à Azure Cosmos DB for Apache Cassandra et retourne une session pour l’accès (l’objet Cluster du pilote v3 est désormais obsolète). L’hôte, le port, le nom d’utilisateur et le mot de passe Cassandra sont définis à l’aide de la page de chaîne de connexion dans le portail Azure.
```
    this.session = CqlSession.builder().withSslContext(sc)
            .addContactPoint(new InetSocketAddress(cassandraHost, cassandraPort)).withLocalDatacenter(region)
            .withAuthCredentials(cassandraUsername, cassandraPassword).build();
```

Les extraits de code suivants sont tous extraits du fichier src/main/java/com/azure/cosmosdb/cassandra/repository/UserRepository.java.

Si un espace de clés issu d’une exécution précédente existe déjà, supprimez-le.

public void dropKeyspace() {
    String query = "DROP KEYSPACE IF EXISTS "+keyspace+"";
    session.execute(query);
    LOGGER.info("dropped keyspace '"+keyspace+"'");
}

Un espace de clés est créé.

public void createKeyspace() {
    String query = "CREATE KEYSPACE "+keyspace+" WITH REPLICATION = { 'class' : 'NetworkTopologyStrategy', 'datacenter1' : 1 }";
    session.execute(query);
    LOGGER.info("Created keyspace '"+keyspace+"'");
}

Une table est créée.

  public void createTable() {
      String query = "CREATE TABLE "+keyspace+"."+table+" (user_id int PRIMARY KEY, user_name text, user_bcity text)";
      session.execute(query);
      LOGGER.info("Created table '"+table+"'");
  }

Les entités utilisateur sont insérées à l’aide d’un objet d’instruction préparé.

public String prepareInsertStatement() {
    final String insertStatement = "INSERT INTO  "+keyspace+"."+table+" (user_id, user_name , user_bcity) VALUES (?,?,?)";
    return insertStatement;
}

public void insertUser(String preparedStatement, int id, String name, String city) {
    PreparedStatement prepared = session.prepare(preparedStatement);
    BoundStatement bound = prepared.bind(id, city, name).setIdempotent(true);
    session.execute(bound);
}

Effectuez une requête pour obtenir les informations de tous les utilisateurs.

public void selectAllUsers() {
    final String query = "SELECT * FROM "+keyspace+"."+table+"";
    List<Row> rows = session.execute(query).all();

    for (Row row : rows) {
        LOGGER.info("Obtained row: {} | {} | {} ", row.getInt("user_id"), row.getString("user_name"), row.getString("user_bcity"));
    }
}

Effectuez une requête pour obtenir les informations d’un seul utilisateur.

public void selectUser(int id) {
    final String query = "SELECT * FROM "+keyspace+"."+table+" where user_id = 3";
    Row row = session.execute(query).one();

    LOGGER.info("Obtained row: {} | {} | {} ", row.getInt("user_id"), row.getString("user_name"), row.getString("user_bcity"));
}

Mise à jour de votre chaîne de connexion

Maintenant, retournez dans le portail Azure afin d’obtenir les informations de votre chaîne de connexion et de les copier dans l’application. Les détails de la chaîne de connexion permettent à votre application de communiquer avec votre base de données hébergée.

Dans votre compte Azure Cosmos DB, sur le portail Azure, sélectionnez Chaîne de connexion.
Utilisez le bouton sur le côté droit de l’écran pour copier la valeur de POINT DE CONTACT.
Ouvrez le fichier config.properties à partir du dossier C:\git-samples\azure-cosmosdb-cassandra-java-getting-started\java-examples\src\main\resources.
Collez la valeur POINT DE CONTACT à partir du portail sur <Cassandra endpoint host> à la ligne 2.

La ligne 2 du fichier config.properties doit désormais ressembler à

cassandra_host=cosmos-db-quickstart.cassandra.cosmosdb.azure.com
Revenez au portail et copiez la valeur NOM D’UTILISATEUR. Collez la valeur NOM D’UTILISATEUR à partir du portail sur <cassandra endpoint username> à la ligne 4.

La ligne 4 du fichier config.properties doit désormais ressembler à

cassandra_username=cosmos-db-quickstart
Revenez au portail et copiez la valeur MOT DE PASSE. Collez la valeur MOT DE PASSE à partir du portail sur <cassandra endpoint password> à la ligne 5.

La ligne 5 du fichier config.properties doit désormais ressembler à

cassandra_password=2Ggkr662ifxz2Mg...==
Sur la ligne 6, si vous voulez utiliser un certificat TLS/SSL spécifique, remplacez <SSL key store file location> par l’emplacement du certificat TLS/SSL. Si aucune valeur n’est renseignée, c’est le certificat JDK installé dans <JAVA_HOME>/jre/lib/security/cacerts qui est utilisé.
Si vous avez modifié la ligne 6 pour utiliser un certificat TLS/SSL spécifique, mettez à jour la ligne 7 pour utiliser le mot de passe de ce certificat.
Notez que vous devrez ajouter la région par défaut (par exemple, West US) pour le point de contact, par exemple.

region=West US

En effet, le pilote v.4x permet de coupler un contrôleur de domaine local uniquement avec le point de contact. Si vous souhaitez ajouter une région autre que celle par défaut (la région fournie à la création du compte Azure Cosmos DB), vous devez utiliser le suffixe régional quand vous ajoutez le point de contact, par exemple host-westus.cassandra.cosmos.azure.com.
Enregistrez le fichier config.properties.

Exécuter l’application Java

Dans la fenêtre de terminal git, ouvrez (cd) le dossier azure-cosmosdb-cassandra-java-getting-started-v4.
```
cd "C:\git-samples\azure-cosmosdb-cassandra-java-getting-started-v4"
```
Dans la fenêtre de terminal git, utilisez la commande suivante pour générer le fichier cosmosdb-cassandra-examples.jar.
```
mvn clean install
```
Dans la fenêtre de terminal git, exécutez la commande suivante pour démarrer l’application Java.
```
java -cp target/cosmosdb-cassandra-examples.jar com.azure.cosmosdb.cassandra.examples.UserProfile
```
La fenêtre de terminal affiche des notifications indiquant que l’espace de clé et la table sont créés. Elle sélectionne et retourne ensuite tous les utilisateurs dans la table et affiche la sortie, avant de sélectionner une ligne par ID et d’afficher sa valeur.

Appuyez sur Ctrl+C pour arrêter l’exécution du programme et fermer la fenêtre de console.
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 démarrage rapide, vous avez découvert comment créer un compte Azure Cosmos DB avec l’API pour Cassandra et exécuter une application Java Cassandra 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

Créer une application Java pour gérer les données Azure Cosmos DB for Apache Cassandra (pilote v4)

Prérequis

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

Clonage de l’exemple d’application

Vérifier le code

Mise à jour de votre chaîne de connexion

Exécuter l’application Java

Vérification des contrats SLA dans le portail Azure

Nettoyer les ressources

Étapes suivantes

Ressources supplémentaires