Démarrage rapide : Créer une application d’API Table avec le SDK .NET et Azure Cosmos DBQuickstart: Build a Table API app with .NET SDK and Azure Cosmos DB

Ce guide de démarrage rapide montre comment utiliser .NET et l’API Table d’Azure Cosmos DB pour créer une application en clonant un exemple à partir de GitHub.This quickstart shows how to use .NET and the Azure Cosmos DB Table API to build an app by cloning an example from GitHub. Ce guide de démarrage rapide vous montre également comment créer un compte Azure Cosmos DB et comment utiliser l’Explorateur de données pour créer des tables et des entités dans le portail web Azure.This quickstart also shows you how to create an Azure Cosmos DB account and how to use Data Explorer to create tables and entities in the web-based Azure portal.

PrérequisPrerequisites

Si vous n'avez pas encore installé Visual Studio 2019, vous pouvez télécharger et utiliser la version gratuite Visual Studio 2019 Community Edition.If you don’t already have Visual Studio 2019 installed, you can download and use the free Visual Studio 2019 Community Edition. Veillez à activer le développement Azure lors de l’installation de Visual Studio.Make sure that you enable Azure development during the Visual Studio setup.

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.

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

  1. Dans une nouvelle fenêtre du navigateur, connectez-vous au portail Azure.In a new browser window, sign in to the Azure portal.

  2. Dans le volet de navigation gauche, sélectionnez Créer une ressource.In the left navigation pane, select Create a resource. Sélectionnez Bases de données, puis Azure Cosmos DB.Select Databases and then select Azure Cosmos DB.

    Capture d’écran du portail Azure, mettant en surbrillance l’option Plus de services et Azure Cosmos DB

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

    ParamètreSetting ValeurValue DescriptionDescription
    SubscriptionSubscription Votre abonnementYour subscription Sélectionnez l’abonnement Azure que vous souhaitez utiliser pour ce compte Azure Cosmos DB.Select the Azure subscription that you want to use for this Azure Cosmos DB account.
    Groupe de ressourcesResource Group CréationCreate new

    Entrez ensuite le même nom unique que celui fourni dans l’IDThen enter the same unique name as provided in ID
    Sélectionnez Créer nouveau.Select Create new. Entrez ensuite le nom du nouveau groupe de ressources pour votre compte.Then enter a new resource group name for your account. Pour rester simple, utilisez le même nom que celui de votre ID.For simplicity, use the same name as your ID.
    Nom du compteAccount Name Entrez un nom uniqueEnter a unique name Entrez un nom unique pour identifier votre compte Azure Cosmos DB.Enter a unique name to identify your Azure Cosmos DB account.

    L’ID peut uniquement utiliser des lettres minuscules, des chiffres et le caractère de trait d’union (-).The ID can use only lowercase letters, numbers, and the hyphen (-) character. Il doit comprendre entre 3 et 31 caractères.It must be between 3 and 31 characters long.
    APIAPI table AzureAzure Table 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) pour les bases de données orientées document, Gremlin pour les bases de données de graphe, MongoDB pour les bases de données de document, Table Azure et Cassandra.Azure Cosmos DB provides five APIs: Core(SQL) for document databases, Gremlin for graph databases, MongoDB for document databases, 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.

    Sélectionnez Table Azure, car ce guide de démarrage rapide vous permet de créer une table qui fonctionne avec l’API Table.Select Azure Table because in this quickstart you're creating a table that works with the Table API.

    Découvrez plus d’informations sur l’API Table.Learn more about the Table API.
    LocationLocation Sélectionner la région la plus proche de vos utilisateursSelect the 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 aux données.Use the location that's closest to your users to give them the fastest access to data.

    Vous pouvez laisser les options Géoredondance et Écritures multirégions avec leur valeur par défaut (Désactiver) pour éviter des frais d’unités de requête supplémentaires.You can leave the Geo-Redundancy and Multi-region Writes options at their default values (Disable) to avoid additional RU charges. Vous pouvez ignorer les sections Réseau et Balises.You can skip the Network and Tags sections.

  4. Sélectionnez Vérifier + créer.Select Review+Create. Une fois la validation terminée, sélectionnez Créer pour créer le compte.After the validation is complete, select Create to create the account.

    Page de nouveau compte pour Azure Cosmos DB

  5. La création du compte prend quelques minutes.It takes a few minutes to create the account. Un message vous indique que Votre déploiement est en cours.You'll see a message that states Your deployment is underway. Attendez la fin du déploiement, puis sélectionnez Accéder à la ressource.Wait for the deployment to finish and then select Go to resource.

    Volet Notifications du portail Azure

Ajouter une tableAdd a table

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

  1. Cliquez sur Explorateur de données > Nouvelle table.Click Data Explorer > New Table.

    La zone Ajouter une table est affichée à l’extrême droite. Il peut donc être nécessaire de faire défiler à droite pour l’afficher.The Add Table area is displayed on the far right, you may need to scroll right to see it.

    Explorateur de données dans le portail Azure

  2. Dans la page Ajouter une table, entrez les paramètres de la nouvelle table.In the Add Table page, enter the settings for the new table.

    ParamètreSetting Valeur suggéréeSuggested value DescriptionDescription
    ID de la tableTable Id sample-databasesample-table L’ID de votre nouvelle table.The ID for your new table. Les noms de tables sont soumis aux mêmes exigences de nombre de caractères que les ID de bases de données.Table names have the same character requirements as database ids. Les noms de base de données doivent inclure entre 1 et 255 caractères et ne peuvent pas contenir / \ # ? ni d’espace de fin.Database names must be between 1 and 255 characters, and cannot contain / \ # ? or a trailing space.
    DébitThroughput 400 unités de requête400 RUs Changez le débit en indiquant 400 unités de requête par seconde (RU/s).Change the throughput to 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.
  3. Cliquez sur OK.Click OK.

  4. L’Explorateur de données affiche la nouvelle base de données et la nouvelle table.Data Explorer displays the new database and table.

    L’Explorateur de données du portail Azure, affichant la nouvelle base de données et la nouvelle collection

Ajouter un exemple de donnéesAdd sample data

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

  1. Dans l’Explorateur de données, développez exemple de table, cliquez sur Entités, puis cliquez sur Ajouter une entité.In Data Explorer, expand sample-table, click Entities, and then click Add Entity.

    Créer des entités dans l’Explorateur de données, dans le portail Azure

  2. À présent, ajoutez des données à la zone de valeur PartitionKey et à la zone de valeur RowKey, puis cliquez sur Ajouter une entité.Now add data to the PartitionKey value box and RowKey value box, and click Add Entity.

    Définir la clé de Partition et la clé de ligne pour une nouvelle entité

    Vous pouvez maintenant ajouter des entités supplémentaires à votre table, éditer vos entités, ou interroger vos données dans l’Explorateur de données.You can now add more entities to your table, edit your entities, or query your data in Data Explorer. À partir de l’Explorateur de données, vous pouvez également faire évoluer votre débit et ajouter des procédures stockées, des fonctions définies par l’utilisateur, et ajouter à votre table des déclencheurs.Data Explorer is also where you can scale your throughput and add stored procedures, user-defined functions, and triggers to your table.

Clonage de l’exemple d’applicationClone the sample application

À présent, nous allons cloner une application Table à partir de GitHub, configurer la chaîne de connexion et l’exécuter.Now let's clone a Table 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. Ouvrez une invite de commandes, créez un nouveau dossier nommé git-samples, puis fermez l’invite de commandes.Open a command prompt, create a new folder named git-samples, then close the command prompt.

    md "C:\git-samples"
    
  2. 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.Open a git terminal window, such as git bash, and use the cd command to change to the new folder to install the sample app.

    cd "C:\git-samples"
    
  3. 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-table-dotnet-core-getting-started.git
    

Ouvrir l’exemple d’application dans Visual StudioOpen the sample application in Visual Studio

  1. Dans Visual Studio, à partir du menu Fichier, choisissez Ouvrir, puis Projet/Solution.In Visual Studio, from the File menu, choose Open, then choose Project/Solution.

    Ouvrir la solution

  2. Accédez au dossier où vous avez cloné l’exemple d’application et ouvrez le fichier TableStorage.sln.Navigate to the folder where you cloned the sample application and open the TableStorage.sln file.

Mise à jour de votre chaîne de connexionUpdate your connection string

Maintenant, retournez dans le portail Azure afin d’obtenir les informations de votre chaîne de connexion et de les copier dans l’application.Now go back to the Azure portal to get your connection string information and copy it into the app. 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 le portail Azure, cliquez sur Chaîne de connexion.In the Azure portal, click Connection String. Utilisez les boutons de copie sur le côté droit de la fenêtre pour copier la CHAÎNE DE CONNEXION PRINCIPALE.Use the copy button on the right side of the window to copy the PRIMARY CONNECTION STRING.

    Afficher et copier la CHAÎNE DE CONNEXION PRINCIPALE dans le volet Chaîne de connexion

  2. Dans Visual Studio, ouvrez le fichier Settings.json.In Visual Studio, open the Settings.json file.

  3. Collez la CHAÎNE DE CONNEXION PRINCIPALE du portail dans la valeur StorageConnectionString.Paste the PRIMARY CONNECTION STRING from the portal into the StorageConnectionString value. Collez la chaîne entre les guillemets.Paste the string inside the quotes.

    {
       "StorageConnectionString": "<Primary connection string from Azure portal>"
    }
    
  4. Appuyez sur Ctrl+S pour enregistrer le fichier Settings.json.Press CTRL+S to save the Settings.json file.

Vous venez de mettre à jour votre application avec toutes les informations nécessaires pour communiquer avec Azure Cosmos DB.You've now updated your app with all the info it needs to communicate with Azure Cosmos DB.

Génération et déploiement de l’applicationBuild and deploy the app

  1. Dans Visual Studio, cliquez avec le bouton droit sur le projet CosmosTableSamples dans l’Explorateur de solutions, puis cliquez sur Gérer les packages NuGet.In Visual Studio, right-click on the CosmosTableSamples project in Solution Explorer and then click Manage NuGet Packages.

    Gérer les packages NuGet

  2. Dans la zone Parcourir de NuGet, tapez Microsoft.Azure.Cosmos.Table.In the NuGet Browse box, type Microsoft.Azure.Cosmos.Table. Cela permet de rechercher la bibliothèque cliente API de Table Cosmos DB.This will find the Cosmos DB Table API client library. Notez que cette bibliothèque est actuellement disponible pour .NET Framework et .NET Standard.Note that this library is currently available for .NET Framework and .NET Standard.

    Onglet Parcourir de NuGet

  3. Cliquez sur Installer pour installer la bibliothèque Microsoft.Azure.Cosmos.Table.Click Install to install the Microsoft.Azure.Cosmos.Table library. Cette opération installe le package API Table d’Azure Cosmos DB et toutes les dépendances.This installs the Azure Cosmos DB Table API package and all dependencies.

  4. Lorsque vous exécutez l’application entière, les données de l’exemple sont insérées dans l’entité table et supprimées à la fin pour n’afficher aucune donnée insérée si vous exécutez l’exemple en entier.When you run the entire app, sample data is inserted into the table entity and deleted at the end so you won’t see any data inserted if you run the whole sample. Cependant, vous pouvez insérer des points d’arrêt pour visualiser les données.However you can insert some breakpoints to view the data. Ouvrez le fichier BasicSamples.cs, cliquez avec le bouton droit sur la ligne 52, sélectionnez Point d’arrêt, puis Insérer un point d’arrêt.Open BasicSamples.cs file and right-click on line 52, select Breakpoint, then select Insert Breakpoint. Insérez un autre point d’arrêt sur la ligne 55.Insert another breakpoint on line 55.

    Ajouter un point d’arrêt

  5. Appuyez sur F5 pour exécuter l'application.Press F5 to run the application. La fenêtre de console affiche le nom de la nouvelle base de données de tables (dans ce cas demoa13b1) dans Azure Cosmos DB.The console window displays the name of the new table database (in this case, demoa13b1) in Azure Cosmos DB.

    Sortie de la console

    Lorsque vous atteignez le premier point d’arrêt, revenez à l’Explorateur de données dans le portail Azure.When you hit the first breakpoint, go back to Data Explorer in the Azure portal. Cliquez sur le Actualiser bouton, développez la table demo*, puis cliquez sur Entités.Click the Refresh button, expand the demo* table, and click Entities. L’onglet Entités situé à droite affiche la nouvelle entité qui a été ajoutée pour Walter Harp.The Entities tab on the right shows the new entity that was added for Walter Harp. Notez que le numéro de téléphone de la nouvelle entité est 425-555-0101.Note that the phone number for the new entity is 425-555-0101.

    Nouvelle entité

    Si vous voyez une erreur indiquant qu’un fichier Settings.json n’a pas été trouvé pendant l’exécution du projet, vous pouvez la résoudre en ajoutant l’entrée XML suivante dans les paramètres du projet.If you receive an error that says Settings.json file can’t be found when running the project, you can resolve it by adding the following XML entry to the project settings. Cliquez avec le bouton droit sur CosmosTableSamples, sélectionnez Modifier CosmosTableSamples.csproj et ajoutez l’élément itemGroup suivant :Right click on CosmosTableSamples, select Edit CosmosTableSamples.csproj and add the following itemGroup:

      <ItemGroup>
        <None Update="Settings.json">
          <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
        </None>
      </ItemGroup>
    
  6. Fermez l’onglet Entités dans l’Explorateur de données.Close the Entities tab in Data Explorer.

  7. Appuyez sur F5 pour exécuter l’application jusqu’au point d’arrêt suivant.Press F5 to run the app to the next breakpoint.

    Lorsque vous atteignez le point d’arrêt, revenez au portail, cliquez à nouveau sur Entités pour ouvrir l’onglet Entités, et notez que le numéro de téléphone a été remplacé par 425-555-0105.When you hit the breakpoint, switch back to the Azure portal, click Entities again to open the Entities tab, and note that the phone number has been updated to 425-555-0105.

  8. Appuyez sur F5 pour exécuter l’application.Press F5 to run the app.

    L’application ajoute des entités à utiliser dans un exemple d’application avancée que l’API Table ne prend pas en charge actuellement.The app adds entities for use in an advanced sample app that the Table API currently does not support. L’application supprime ensuite la table créée par l’exemple d’application.The app then deletes the table created by the sample app.

  9. Dans la fenêtre de console, appuyez sur Entrée pour mettre fin à l’exécution de l’application.In the console window, press Enter to end the execution of the app.

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.

    Métriques dans le portail Azure

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

    Métriques dans le portail Azure

  4. Dans la fenêtre suivante, tapez le nom du groupe de ressources à supprimer, puis sélectionnez Supprimer.In the next window, type 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 DB, à créer une table à l’aide de l’Explorateur de données, et à exécuter une application.In this quickstart, you've learned how to create an Azure Cosmos DB account, create a table using the Data Explorer, and run an app. Maintenant, vous pouvez interroger vos données à l’aide de l’API Table.Now you can query your data using the Table API.