Démarrage rapide : Créer une application Java pour gérer les données de l’API SQL d’Azure Cosmos DBQuickstart: Build a Java app to manage Azure Cosmos DB SQL API data

Ce guide de démarrage rapide vous montre comment utiliser une application Java pour créer et gérer une base de données de documents à partir de votre compte Azure d’API SQL Azure Cosmos DB.This quickstart shows you how to use a Java application to create and manage a document database from your Azure Cosmos DB SQL API account. Tout d’abord, vous créez un compte d’API SQL Azure Cosmos DB à l’aide du portail Azure, vous créez ensuite une application Java en utilisant le SDK Java SQL, puis vous ajoutez des ressources à votre compte Cosmos DB à l’aide de l’application Java.First, you create an Azure Cosmos DB SQL API account using the Azure portal, create a Java app using the SQL Java SDK, and then add resources to your Cosmos DB account by using the Java application. Les instructions de ce guide de démarrage rapide s’appliquent à tous les systèmes d’exploitation pouvant exécuter Java.The instructions in this quickstart can be followed on any operating system that is capable of running Java. Après avoir suivi ce guide de démarrage rapide, vous saurez comment créer et modifier des bases de données Cosmos DB et des conteneurs soit dans l’interface utilisateur, soit par programmation, selon la méthode que vous préférez.After completing this quickstart you'll be familiar with creating and modifying Cosmos DB databases, containers in either the UI or programmatically, whichever is your preference.

PrérequisPrerequisites

Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.If you don't have an Azure subscription, create a free account before you begin.

Vous pouvez essayer Azure Cosmos DB gratuitement sans abonnement Azure, libre de tous frais et engagements.You can Try Azure Cosmos DB for free without an Azure subscription, free of charge and commitments. Vous pouvez également utiliser l’émulateur Azure Cosmos DB avec un URI de https://localhost:8081.Or, you can use the Azure Cosmos DB Emulator with a URI of https://localhost:8081. Pour obtenir la clé à utiliser avec l’émulateur, consultez Authentification des demandes.For the key to use with the emulator, see Authenticating requests.

Par ailleurs :In addition:

  • Kit de développement Java (JDK), version 8Java Development Kit (JDK) version 8
    • Veillez à définir la variable d’environnement JAVA_HOME pour qu’elle pointe vers le dossier dans lequel le JDK est installé.Be sure to set the JAVA_HOME environment variable to point to the folder where the JDK is installed.
  • Téléchargement et installation d’une archive binaire MavenDownload and install a Maven binary archive
    • Sur Ubuntu, vous pouvez exécuter apt-get install maven pour installer Maven.On Ubuntu, you can run apt-get install maven to install Maven.
  • GitGit
    • Sur Ubuntu, vous pouvez exécuter sudo apt-get install git pour installer Git.On Ubuntu, you can run sudo apt-get install git to install Git.

Création d’un compte de base de donnéesCreate a database account

Pour être en mesure de créer une base de données de documents, vous devez avoir préalablement créé un compte d’API SQL avec Azure Cosmos DB.Before you can create a document database, you need to create a SQL API account with Azure Cosmos DB.

  1. Connectez-vous au Portail Azure.Sign in to the Azure portal.

  2. Sélectionnez Créer une ressource > Bases de données > Azure Cosmos DB.Select Create a resource > Databases > Azure Cosmos DB.

    Volet Bases de données du portail Azure

  3. Dans la page Créer un compte Azure Cosmos DB, entrez les paramètres de base du nouveau compte Azure Cosmos.On the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos account.

    ParamètreSetting ValeurValue DescriptionDescription
    SubscriptionSubscription Nom d’abonnementSubscription name Sélectionnez l’abonnement Azure à utiliser pour ce compte Azure Cosmos.Select the Azure subscription that you want to use for this Azure Cosmos account.
    Groupe de ressourcesResource Group Nom de groupe ressourcesResource group name Sélectionnez un groupe de ressources ou sélectionnez Créer, puis entrez un nom unique pour le nouveau groupe de ressources.Select a resource group, or select Create new, then enter a unique name for the new resource group.
    Nom du compteAccount Name Un nom uniqueA unique name Entrez un nom pour identifier votre compte Azure Cosmos.Enter a name to identify your Azure Cosmos account. Étant donné que documents.azure.com est ajouté à l’ID que vous fournissez pour créer votre URI, utilisez un ID unique.Because documents.azure.com is appended to the ID that you provide to create your URI, use a unique ID.

    L’ID peut uniquement contenir des lettres minuscules, des chiffres et le caractère de trait d’union (-).The ID can only contain lowercase letters, numbers, and the hyphen (-) character. Sa longueur doit être comprise entre 3 et 31 caractères.It must be between 3-31 characters in length.
    APIAPI Type de compte à créerThe type of account to create Sélectionnez Core (SQL) pour créer une base de données orientée document et effectuez des requêtes à l’aide de la syntaxe SQL.Select Core (SQL) to create a document database and query by using SQL syntax.

    L’API détermine le type de compte à créer.The API determines the type of account to create. Azure Cosmos DB fournit cinq API : Core (SQL) et MongoDB pour les données de document, Gremlin pour les données de graphe, Table Azure et Cassandra.Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. Actuellement, vous devez créer un compte distinct pour chaque API.Currently, you must create a separate account for each API.

    En savoir plus sur l’API SQL.Learn more about the SQL API.
    LocationLocation La région la plus proche de vos utilisateursThe region closest to your users Sélectionnez la zone géographique dans laquelle héberger votre compte Azure Cosmos DB.Select a geographic location to host your Azure Cosmos DB account. Utilisez l’emplacement le plus proche de vos utilisateurs pour leur donner l’accès le plus rapide possible aux données.Use the location that is closest to your users to give them the fastest access to the data.

    Page de nouveau compte pour Azure Cosmos DB

  4. Sélectionnez Revoir + créer.Select Review + create. Vous pouvez ignorer les sections Réseau et Balises.You can skip the Network and Tags sections.

  5. Passez en revue les paramètres du compte, puis sélectionnez Créer.Review the account settings, and then select Create. La création du compte prend quelques minutes.It takes a few minutes to create the account. Attendez que la page du portail affiche Votre déploiement est terminé.Wait for the portal page to display Your deployment is complete.

    Volet Notifications du portail Azure

  6. Sélectionnez Accéder à la ressource pour accéder à la page du compte Azure Cosmos DB.Select Go to resource to go to the Azure Cosmos DB account page.

    Page du compte Azure Cosmos DB

Ajouter un conteneurAdd a container

Vous pouvez désormais utiliser l’outil Explorateur de données dans le portail Azure pour créer une base de données et un conteneur.You can now use the Data Explorer tool in the Azure portal to create a database and container.

  1. Sélectionnez Explorateur de données > Nouveau conteneur.Select Data Explorer > New Container.

    La zone Ajouter un conteneur s’affiche à l’extrême droite : il peut donc être nécessaire de faire défiler à droite pour l’afficher.The Add Container area is displayed on the far right, you may need to scroll right to see it.

    Explorateur de données du portail Azure, volet Ajouter un conteneur

  2. Dans la page Ajouter un conteneur, entrez les paramètres du nouveau conteneur.In the Add container page, enter the settings for the new container.

    ParamètreSetting Valeur suggéréeSuggested value DescriptionDescription
    ID de base de donnéesDatabase ID TâchesTasks Entrez ToDoList pour le nom de la nouvelle base de données.Enter ToDoList as the name for the new database. Les noms de base de données doivent comporter entre 1 et 255 caractères, et ne peuvent pas contenir les caractères /, \\, #, ?, ni un espace de fin.Database names must contain from 1 through 255 characters, and they cannot contain /, \\, #, ?, or a trailing space. Cochez l’option Provisionner le débit de base de données qui vous permet de partager le débit provisionné pour la base de données entre tous les conteneurs au sein de la base de données.Check the Provision database throughput option, it allows you to share the throughput provisioned to the database across all the containers within the database. Cette option permet également de réduire les coûts.This option also helps with cost savings.
    DébitThroughput 400400 Laissez le débit sur 400 unités de requête par seconde (RU/s).Leave the throughput at 400 request units per second (RU/s). Si vous souhaitez réduire la latence, vous pourrez augmenter le débit par la suite.If you want to reduce latency, you can scale up the throughput later.
    ID de conteneurContainer ID ÉlémentsItems Entrez Éléments comme nom de votre nouveau conteneur.Enter Items as the name for your new container. Les ID de conteneur sont soumis aux mêmes exigences en termes de caractères que les noms de base de données.Container IDs have the same character requirements as database names.
    Clé de partitionPartition key /category/category L’exemple décrit dans cet article utilise /category comme clé de partition.The sample described in this article uses /category as the partition key.

    Outre les paramètres précédents, vous pouvez ajouter des clés uniques pour le conteneur.In addition to the preceding settings, you can optionally add Unique keys for the container. Laissez le champ vide dans cet exemple.Let's leave the field empty in this example. Les clés uniques permettent aux développeurs d’ajouter une couche d’intégrité des données à la base de données.Unique keys provide developers with the ability to add a layer of data integrity to the database. En créant une stratégie de clé unique durant la création d’un conteneur, vous garantissez l’unicité d’une ou de plusieurs valeurs par clé de partition.By creating a unique key policy while creating a container, you ensure the uniqueness of one or more values per partition key. Pour en savoir plus, référez-vous à l’article Clés uniques dans Azure Cosmos DB.To learn more, refer to the Unique keys in Azure Cosmos DB article.

    Sélectionnez OK.Select OK. L’Explorateur de données affiche la nouvelle base de données et le nouveau conteneur.The Data Explorer displays the new database and container.

Ajouter un exemple de donnéesAdd sample data

Vous pouvez maintenant ajouter des données à votre nouveau conteneur grâce à l’Explorateur de données.You can now add data to your new container using Data Explorer.

  1. Dans l’Explorateur de données, développez la base de données Tâches, puis développez le conteneur Éléments.From the Data Explorer, expand the Tasks database, expand the Items container. Sélectionnez Éléments, puis sélectionnez Nouvel élément.Select Items, and then select New Item.

    Créer des documents dans l’Explorateur de données, dans le Portail Azure

  2. À présent, ajoutez un document au conteneur avec la structure suivante.Now add a document to the container with the following structure.

    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    }
    
  3. Une fois le fichier json ajouté à l’onglet Documents, sélectionnez Enregistrer.Once you've added the json to the Documents tab, select Save.

    Copiez les données json, puis sélectionnez Enregistrer dans l’Explorateur de données dans le portail Azure.

  4. Créez et enregistrez un document supplémentaire dans lequel vous insérez une valeur unique pour la propriété id et modifiez les autres propriétés selon vos besoins.Create and save one more document where you insert a unique value for the id property, and change the other properties as you see fit. Vos nouveaux documents peuvent avoir la structure de votre choix car Azure Cosmos DB n’impose aucun schéma pour vos données.Your new documents can have any structure you want as Azure Cosmos DB doesn't impose any schema on your data.

Interroger vos donnéesQuery your data

Vous pouvez utiliser des requêtes dans l’Explorateur de données pour récupérer et filtrer vos données.You can use queries in Data Explorer to retrieve and filter your data.

  1. Dans l’Explorateur de données, au-dessus de l’onglet Documents, examinez la requête par défaut SELECT * FROM c.At the top of the Documents tab in Data Explorer, review the default query SELECT * FROM c. Cette requête par défaut récupère et affiche tous les documents de la collection, classés par ID.This query retrieves and displays all documents in the collection in ID order.

    La requête par défaut dans l’Explorateur de données est « SELECT * FROM c »

  2. Pour modifier la requête, sélectionnez Modifier le filtre, remplacez la requête par défaut par ORDER BY c._ts DESC, puis sélectionnez Appliquer le filtre.To change the query, select Edit Filter, replace the default query with ORDER BY c._ts DESC, and then select Apply Filter.

    Modifier la requête par défaut en ajoutant ORDER BY c._ts DESC et en cliquant sur Appliquer un filtre

    Cette requête modifiée affiche les documents dans l’ordre décroissant en fonction de leur horodatage. Votre deuxième document s’affiche désormais en tête de liste.The modified query displays the documents in descending order based on their time stamp, so now your second document is listed first.

    Requête remplacée par ORDER BY c._ts DESC et sélection de l’option Appliquer le filtre

Si vous êtes à l’aise avec la syntaxe SQL, vous pouvez saisir n’importe quelle requête SQL prise en charge dans la zone du prédicat de requête.If you're familiar with SQL syntax, you can enter any supported SQL queries in the query predicate box. Vous pouvez également utiliser l’Explorateur de données pour créer des procédures stockées, des fonctions définies par l’utilisateur et des déclencheurs pour la logique métier côté serveur.You can also use Data Explorer to create stored procedures, UDFs, and triggers for server-side business logic.

L’Explorateur de données permet d’accéder facilement à toutes les fonctionnalités intégrées d’accès aux données par programmation qui sont disponibles dans les API, à partir du portail Azure.Data Explorer provides easy Azure portal access to all of the built-in programmatic data access features available in the APIs. Vous pouvez également utiliser le portail pour mettre à l’échelle le débit, pour obtenir des clés et des chaînes de connexion, ainsi que pour passer en revue les métriques et les contrats SLA de votre compte Azure Cosmos DB.You also use the portal to scale throughput, get keys and connection strings, and review metrics and SLAs for your Azure Cosmos DB account.

Clonage de l’exemple d’applicationClone the sample application

À présent, travaillons sur le code.Now let's switch to working with code. Nous allons cloner une application API SQL à partir de GitHub, configurer la chaîne de connexion et l’exécuter.Let's clone a SQL API app from GitHub, set the connection string, and run it. Vous verrez combien il est facile de travailler par programmation avec des données.You'll see how easy it is to work with data programmatically.

  1. Exécutez la commande suivante pour cloner l’exemple de référentiel :Run the following command to clone the sample repository. Cette commande crée une copie de l’exemple d’application sur votre ordinateur.This command creates a copy of the sample app on your computer.

    git clone https://github.com/Azure-Samples/azure-cosmos-db-sql-api-async-java-getting-started
    

Vérifier le codeReview the code

Cette étape est facultative.This step is optional. Pour savoir comment les ressources de base de données sont créées dans le code, vous pouvez examiner les extraits de code suivants.If you're interested in learning how the database resources are created in the code, you can review the following snippets. Sinon, vous pouvez directement passer à la section Exécution de l’application.Otherwise, you can skip ahead to Run the app .

  • Initialisation de AsyncDocumentClient.AsyncDocumentClient initialization. AsyncDocumentClient fournit la représentation logique côté client du service de base de données Azure Cosmos.The AsyncDocumentClient provides client-side logical representation for the Azure Cosmos database service. Ce client est utilisé pour configurer et exécuter des requêtes auprès du service.This client is used to configure and execute requests against the service.

    client = new AsyncDocumentClient.Builder()
             .withServiceEndpoint(YOUR_COSMOS_DB_ENDPOINT)
             .withMasterKeyOrResourceToken(YOUR_COSMOS_DB_MASTER_KEY)
             .withConnectionPolicy(ConnectionPolicy.GetDefault())
             .withConsistencyLevel(ConsistencyLevel.Eventual)
             .build();
    
  • Création de base de données.Database creation.

    Database databaseDefinition = new Database();
    databaseDefinition.setId(databaseName);
    
    client.createDatabase(databaseDefinition, null)
            .toCompletable()
            .await();
    
  • Création de DocumentCollection.DocumentCollection creation.

    DocumentCollection collectionDefinition = new DocumentCollection();
    collectionDefinition.setId(collectionName);
    
    //...
    
    client.createCollection(databaseLink, collectionDefinition, requestOptions)
            .toCompletable()
            .await();
    
  • Création de documents à l’aide de la méthode createDocument.Document creation by using the createDocument method.

    // Any Java object within your code
    // can be serialized into JSON and written to Azure Cosmos DB
    Family andersenFamily = new Family();
    andersenFamily.setId("Andersen.1");
    andersenFamily.setLastName("Andersen");
    // More properties
    
    String collectionLink = String.format("/dbs/%s/colls/%s", databaseName, collectionName);
    client.createDocument(collectionLink, family, null, true)
            .toCompletable()
            .await();
    
    
  • Les requêtes SQL sur JSON sont effectuées à l’aide de la méthode queryDocuments.SQL queries over JSON are performed using the queryDocuments method.

    FeedOptions queryOptions = new FeedOptions();
    queryOptions.setPageSize(-1);
    queryOptions.setEnableCrossPartitionQuery(true);
    queryOptions.setMaxDegreeOfParallelism(-1);
    
    String collectionLink = String.format("/dbs/%s/colls/%s",
            databaseName,
            collectionName);
    Iterator<FeedResponse<Document>> it = client.queryDocuments(
            collectionLink,
            "SELECT * FROM Family WHERE Family.lastName = 'Andersen'",
            queryOptions).toBlocking().getIterator();
    
    System.out.println("Running SQL query...");
    while (it.hasNext()) {
        FeedResponse<Document> page = it.next();
        System.out.println(
                String.format("\tRead a page of results with %d items",
                        page.getResults().size()));
        for (Document doc : page.getResults()) {
            System.out.println(String.format("\t doc %s", doc));
        }
    }
    

Exécution de l'applicationRun the app

Maintenant, retournez dans le portail Azure afin d’obtenir les informations de votre chaîne de connexion et lancer l’application avec vos informations sur le point de terminaison.Now go back to the Azure portal to get your connection string information and launch the app with your endpoint information. Cette opération permet à votre application de communiquer avec votre base de données hébergée.This enables your app to communicate with your hosted database.

  1. Dans la fenêtre de terminal git, ouvrez cd le dossier d’exemple de code.In the git terminal window, cd to the sample code folder.

    cd azure-cosmos-db-sql-api-async-java-getting-started/azure-cosmosdb-get-started
    
  2. Dans la fenêtre de terminal git, utilisez la commande suivante pour installer les packages Java requis.In the git terminal window, use the following command to install the required Java packages.

    mvn package
    
  3. Dans la fenêtre de terminal git, utilisez la commande suivante pour démarrer l’application Java (remplacez YOUR_COSMOS_DB_HOSTNAME par la valeur d’URI entre guillemets du portail et remplacez YOUR_COSMOS_DB_MASTER_KEY par la clé primaire entre guillemets du portail)In the git terminal window, use the following command to start the Java application (replace YOUR_COSMOS_DB_HOSTNAME with the quoted URI value from the portal, and replace YOUR_COSMOS_DB_MASTER_KEY with the quoted primary key from portal)

    mvn exec:java -DACCOUNT_HOST=YOUR_COSMOS_DB_HOSTNAME -DACCOUNT_KEY=YOUR_COSMOS_DB_MASTER_KEY
    
    

    La fenêtre de terminal affiche une notification vous informant que la base de données FamilyDB a été créée.The terminal window displays a notification that the FamilyDB database was created.

  4. Appuyez sur une touche pour créer la base de données, puis sur une autre touche pour créer la collection.Press a key to create the database, and then another key to create the collection.

    Revenez à l’Explorateur de données dans votre navigateur pour voir qu’il contient maintenant une collection FamilyCollection et une base de données FamilyDB.Switch back to Data Explorer in your browser to see that it now contains a FamilyDB database, and FamilyCollection collection.

  5. Basculez vers la fenêtre de console et appuyez sur une touche pour créer le premier document, puis sur une autre touche pour créer le deuxième document.Switch to the console window and press a key to create the first document, and then another key to create the second document. Revenez ensuite à l’Explorateur de données pour les afficher.Then switch back to Data Explorer to view them.

  6. Appuyez sur une touche pour exécuter une requête et afficher la sortie dans la fenêtre de console.Press a key to run a query and see the output in the console window.

  7. L’application ne supprime pas les ressources créées.The app doesn't delete the created resources. Revenez sur le portail pour nettoyez les ressources.Switch back to the portal to clean up the resources. depuis votre compte afin d’éviter les frais.from your account so that you don't incur charges.

    Voir la sortie dans la fenêtre de console

Vérification des contrats SLA dans le portail AzureReview SLAs in the Azure portal

Le portail Azure supervise le débit, le stockage, la disponibilité, la latence et la cohérence de votre compte Cosmos DB.The Azure portal monitors your Cosmos DB account throughput, storage, availability, latency, and consistency. 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.Charts for metrics associated with an Azure Cosmos DB Service Level Agreement (SLA) show the SLA value compared to actual performance. Cette suite de métriques vous permet de superviser vos contrats SLA de manière transparente.This suite of metrics makes monitoring your SLAs transparent.

Pour consulter les métriques et les contrats SLA :To review metrics and SLAs:

  1. Sélectionnez Métriques dans le menu de navigation de votre compte Cosmos DB.Select Metrics in your Cosmos DB account's navigation menu.

  2. Sélectionnez un onglet comme Latence, puis sélectionnez un intervalle de temps à droite.Select a tab such as Latency, and select a timeframe on the right. Comparez les lignes Réel et SLA des graphiques.Compare the Actual and SLA lines on the charts.

    Suite de métriques d’Azure Cosmos DB

  3. Consultez les métriques des autres onglets.Review the metrics on the other tabs.

Supprimer des ressourcesClean up resources

Quand vous en avez terminé avec votre application web et votre compte Azure Cosmos DB, vous pouvez supprimer les ressources Azure que vous avez créées afin d’éviter des frais supplémentaires.When you're done with your web app and Azure Cosmos DB account, you can delete the Azure resources you created so you don't incur more charges. Pour supprimer les ressources :To delete the resources:

  1. Dans le portail Azure, sélectionnez Groupes de ressources tout à gauche.In the Azure portal, select Resource groups on the far left. Si le menu de gauche est réduit, sélectionnez le bouton Développer pour le développer.If the left menu is collapsed, select Expand button to expand it.

  2. Sélectionnez le groupe de ressources créé dans ce guide de démarrage rapide.Select the resource group you created for this quickstart.

    Sélectionner le groupe de ressources à supprimer

  3. Dans la nouvelle fenêtre, sélectionnez Supprimer le groupe de ressources.In the new window, select Delete resource group.

    Supprimer le groupe de ressources

  4. Dans la fenêtre suivante, entrez le nom du groupe de ressources à supprimer, puis sélectionnez Supprimer.In the next window, enter the name of the resource group to delete, and then select Delete.

Étapes suivantesNext steps

Dans ce guide de démarrage rapide, vous avez appris à créer un compte Azure Cosmos, une base de données de documents et un conteneur à l’aide de l’Explorateur de données, puis à exécuter une application pour effectuer la même opération par programmation.In this quickstart, you've learned how to create an Azure Cosmos account, document database, and container using the Data Explorer, and run an app to do the same thing programmatically. Vous pouvez maintenant importer des données supplémentaires dans votre conteneur Azure Cosmos.You can now import additional data into your Azure Cosmos container.