Démarrage rapide : Azure Cosmos DB for Table pour .NET

S’APPLIQUE À : Table

• .NET
• Java
• Node.JS
• Python

Ce guide de démarrage rapide montre comment accéder à Azure Cosmos DB for Table à partir d’une application .NET. Azure Cosmos DB for Table est un magasin de données sans schéma qui permet aux applications de stocker des données de table structurées dans le cloud. Vous allez apprendre à créer des tables, des lignes et à effectuer des tâches de base dans votre ressource Azure Cosmos DB à l’aide du package Azure.Data.Tables (NuGet).

Notes

Les exemples d’extraits de code sont disponibles sur GitHub en tant que projet .NET.

Documentation de référence de l’API pour Table | Package Azure.Data.Tables (NuGet)

Prérequis

• Compte Azure avec un abonnement actif. Créez un compte gratuitement.
• Compte GitHub

• Compte Azure avec un abonnement actif. Créez un compte gratuitement.
• Azure Developer CLI
• Docker Desktop

Configuration

Déployez le conteneur de développement de ce projet sur votre environnement. Utilisez ensuite l’interface Azure Developer CLI (azd) pour créer un compte Azure Cosmos DB for Table, et déployer un exemple d’application conteneurisé. L’exemple d’application utilise la bibliothèque de client pour gérer, créer, lire et interroger des exemples de données.

Important

Les comptes GitHub incluent un droit d’utilisation relatif au stockage et aux heures cœur gratuites. Pour plus d’informations, consultez Stockage et heures cœur inclus pour les comptes GitHub.

1. Ouvrez un terminal dans le répertoire racine du projet.

2. Authentifiez-vous auprès de l’interface Azure Developer CLI en utilisant azd auth login. Suivez les étapes spécifiées par l’outil pour vous authentifier auprès de l’interface CLI à l’aide de vos informations d’identification Azure préférées.

   azd auth login
   

3. Utilisez azd init pour initialiser le projet.

   azd init
   

4. Lors de l’initialisation, configurez un nom d’environnement unique.

   Conseil

   Le nom de l’environnement sera également utilisé comme nom du groupe de ressources cible. Pour ce guide de démarrage rapide, utilisez msdocs-cosmos-db.

5. Déployez le compte Azure Cosmos DB en utilisant azd up. Les modèles Bicep déploient également un exemple d’application web.

   azd up
   

6. Pendant le processus d’approvisionnement, sélectionnez votre abonnement et l’emplacement souhaité. Attendez la fin du processus de provisionnement. Le processus peut prendre environ cinq minutes.

7. Une fois le provisionnement de vos ressources Azure effectué, une URL vers l’application web en cours d’exécution est incluse dans la sortie.

   Deploying services (azd deploy)
   
     (✓) Done: Deploying service web
   - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>
   
   SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
   

8. Utilisez l’URL dans la console pour accéder à votre application web dans le navigateur. Observez la sortie de l’application en cours d’exécution.

   

Installer la bibliothèque de client

La bibliothèque cliente est disponible via NuGet, en tant que package Microsoft.Azure.Cosmos.

1. Ouvrez un terminal et accédez au dossier /src/web.

   cd ./src/web
   

2. S’il n’est pas déjà installé, installez le package Azure.Data.Tables à l’aide de dotnet add package.

   dotnet add package Azure.Data.Tables
   

3. Installez également le package Azure.Identity, s’il n’est pas déjà installé.

   dotnet add package Azure.Identity
   

4. Ouvrez et examinez le fichier src/web/Cosmos.Samples.Table.Quickstart.Web.csproj pour vérifier que les entrées Microsoft.Azure.Cosmos et Azure.Identity existent.

Exemples de code

• Authentifier le client
• Création d'une table
• Créer un élément
• Obtenir un élément
• Éléments de requête

L’exemple de code décrit dans cet article crée une table nommée adventureworks. Chaque ligne de table contient les détails d’un produit, comme le nom, la catégorie, la quantité et un indicateur de vente. Chaque produit contient également un identificateur unique.

Vous allez utiliser les classes de l’API pour Table suivantes pour interagir avec ces ressources :

• TableServiceClient - Cette classe fournit des méthodes pour effectuer des opérations de niveau de service avec Azure Cosmos DB for Table.
• TableClient - Cette classe vous permet d’interagir avec des tables hébergées dans l’API Table Azure Cosmos DB.
• TableEntity - Cette classe est une référence à une ligne d’une table qui vous permet de gérer les propriétés et les données de colonne.

Authentifier le client

À partir du répertoire de projet, ouvrez le fichier Program.cs. Dans votre éditeur, ajoutez une directive d’utilisation pour Azure.Data.Tables.

using Azure.Data.Tables;

Définissez une nouvelle instance de la classe TableServiceClient à l’aide du constructeur et Environment.GetEnvironmentVariable pour lire la chaîne de connexion définie plus tôt.

// New instance of the TableClient class
TableServiceClient tableServiceClient = new TableServiceClient(Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING"));

Créer une table

Récupérez une instance de TableClient avec la classe TableServiceClient. Utilisez la méthode TableClient.CreateIfNotExistsAsync sur le TableClient pour créer uniquement une table si elle n’existe pas déjà. Cette méthode retourne une référence à la table existante ou nouvellement créée.

// New instance of TableClient class referencing the server-side table
TableClient tableClient = tableServiceClient.GetTableClient(
    tableName: "adventureworks"
);

await tableClient.CreateIfNotExistsAsync();

Créer un élément

Le moyen le plus simple de créer un élément dans une table consiste à créer une classe qui implémente l’interface ITableEntity. Vous pouvez ensuite ajouter vos propres propriétés à la classe pour remplir des colonnes de données dans cette ligne de table.

// C# record type for items in the table
public record Product : ITableEntity
{
    public string RowKey { get; set; } = default!;

    public string PartitionKey { get; set; } = default!;

    public string Name { get; init; } = default!;

    public int Quantity { get; init; }

    public bool Sale { get; init; }

    public ETag ETag { get; set; } = default!;

    public DateTimeOffset? Timestamp { get; set; } = default!;
}

Créez un élément dans la collection à l’aide de la classe Product en appelant TableClient.AddEntityAsync<T>.

// Create new item using composite key constructor
var prod1 = new Product()
{
    RowKey = "68719518388",
    PartitionKey = "gear-surf-surfboards",
    Name = "Ocean Surfboard",
    Quantity = 8,
    Sale = true
};

// Add new item to server-side table
await tableClient.AddEntityAsync<Product>(prod1);

Obtenir un élément

Vous pouvez récupérer un élément spécifique à partir d’une table à l’aide de la méthode TableEntity.GetEntityAsync<T>. Fournissez les paramètres partitionKey et rowKey permettant d’identifier la ligne appropriée pour effectuer une lecture rapide de cet élément.

// Read a single item from container
var product = await tableClient.GetEntityAsync<Product>(
    rowKey: "68719518388",
    partitionKey: "gear-surf-surfboards"
);
Console.WriteLine("Single product:");
Console.WriteLine(product.Value.Name);

Éléments de requête

Après avoir inséré un élément, vous pouvez également exécuter une requête pour obtenir tous les éléments qui correspondent à un filtre spécifique avec la méthode TableClient.Query<T>. Cet exemple filtre les produits par catégorie à l’aide de la syntaxe Linq, qui offre l’avantage d’utiliser des modèles ITableEntity typés comme la classe Product.

Notes

Vous pouvez également interroger des éléments à l’aide de la syntaxe OData. Vous pouvez voir un exemple de cette approche dans le tutoriel Interroger les données.

// Read multiple items from container
var prod2 = new Product()
{
    RowKey = "68719518390",
    PartitionKey = "gear-surf-surfboards",
    Name = "Sand Surfboard",
    Quantity = 5,
    Sale = false
};

await tableClient.AddEntityAsync<Product>(prod2);

var products = tableClient.Query<Product>(x => x.PartitionKey == "gear-surf-surfboards");

Console.WriteLine("Multiple products:");
foreach (var item in products)
{
    Console.WriteLine(item.Name);
}

Exécuter le code

Cette application crée une table d’API Table Azure Cosmos DB. L’exemple crée ensuite un élément, puis lit exactement le même élément. Enfin, l’exemple crée un deuxième élément, puis effectue une requête qui doit retourner plusieurs éléments. Avec chaque étape, l’exemple génère des métadonnées dans la console sur les étapes qu’elle a effectuées.

Pour exécuter l’application, utilisez un terminal pour accéder au répertoire de l’application et exécuter l’application.

dotnet run

La sortie de l’application doit être similaire à l’exemple suivant :

Single product name: 
Yamba Surfboard
Multiple products:
Yamba Surfboard
Sand Surfboard

Nettoyer les ressources

Lorsque vous n’avez plus besoin du compte Azure Cosmos DB for Table, vous pouvez supprimer le groupe de ressources correspondant.

Azure CLI

Pour supprimer le groupe de ressources, utilisez la commande az group delete.

az group delete --name $resourceGroupName

PowerShell

Pour supprimer le groupe de ressources, appelez le cmdlet Remove-AzResourceGroup.

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters

Portail

1. Accédez au groupe de ressources que vous avez créé précédemment dans le Portail Azure.

   Conseil

   Dans ce guide de démarrage rapide, nous recommandons le nom msdocs-cosmos-quickstart-rg.

2. Sélectionnez Supprimer le groupe de ressources.

   

3. Dans la section Voulez-vous vraiment supprimer, tapez le nom du groupe de ressources et sélectionnez Supprimer.

   

Étapes suivantes

Dans ce guide de démarrage rapide, vous avez appris à créer un compte Azure Cosmos DB for Table, à créer une table et à gérer les entrées à l’aide du SDK .NET. Vous pouvez maintenant approfondir le kit de développement logiciel (SDK) pour découvrir comment effectuer des requêtes de données et des tâches de gestion plus avancées dans vos ressources Azure Cosmos DB for Table.

Bien démarrer avec Azure Cosmos DB for Table et .NET