Partager via

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

  • Article

S’APPLIQUE À : Table

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 et des lignes, et à effectuer des tâches de base dans votre ressource Azure Cosmos DB à l’aide du kit SDK Azure pour .NET.

Documentation de référence sur l’API | Code source de la bibliothèque | Package (NuGet) | Azure Developer CLI

Prérequis

Initialiser le projet

Utilisez 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.

  1. Ouvrez un terminal dans un répertoire vide.

  2. Si vous n’êtes pas encore authentifié, authentifiez-vous auprès d’Azure Developer CLI à l’aide de 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 --template cosmos-db-table-dotnet-quickstart

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

  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, l’emplacement souhaité et le groupe de ressources cible. 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.

    Capture d’écran de l’application web en cours d’exécution.

Installer la bibliothèque de client

La bibliothèque cliente est disponible via NuGet, en tant que package Azure.Data.Tables.

  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. Ouvrez et examinez le fichier src/web/Microsoft.Samples.Cosmos.Table.Quickstart.Web.csproj pour vérifier que l’entrée Azure.Data.Tables existe.

Modèle objet

Nom Description
TableServiceClient Il s’agit de la classe cliente principale utilisée pour gérer les métadonnées ou les bases de données à l’échelle du compte.
TableClient Cette classe représente le client d’une table dans le compte.

Exemples de code

L’exemple de code du modèle utilise une table nommée cosmicworks-products. La table cosmicworks-products contient des détails tels que le nom, la catégorie, la quantité, le prix, un identificateur unique et un indicateur de vente pour chaque produit. Le conteneur utilise un identificateur unique* en tant que clé de ligne, et une catégorie en tant que clé de partition.

Authentifier le client

Cet exemple crée une instance de la classe TableServiceClient.

TableServiceClient serviceClient = new(
    endpoint: new Uri("<azure-cosmos-db-table-account-endpoint>"),
    credential
);

Obtenir une table

Cet exemple crée une instance de la classe TableClient à l’aide de la méthode GetTableClient de la classe TableServiceClient.

TableClient client = serviceClient.GetTableClient(
    tableName: "<azure-cosmos-db-table-name>"
);

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.

public record Product : ITableEntity
{
    public string RowKey { get; set; } = $"{Guid.NewGuid()}";

    public string PartitionKey { get; set; } = String.Empty;

    public string Name { get; set; } = String.Empty;

    public int Quantity { get; set; } = 0;

    public decimal Price { get; set; } = 0.0m;

    public bool Clearance { get; set; } = false;

    public ETag ETag { get; set; } = ETag.All;

    public DateTimeOffset? Timestamp { get; set; }
};

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

Product entity = new()
{
    RowKey = "68719518391",
    PartitionKey = "gear-surf-surfboards",
    Name = "Surfboard",
    Quantity = 10,
    Price = 300.00m,
    Clearance = true
};

Response response = await client.UpsertEntityAsync<Product>(
    entity: entity,
    mode: TableUpdateMode.Replace
);

Obtenir un élément

Vous pouvez récupérer un élément spécifique à partir d’une table à l’aide de la méthode TableClient.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.

Response<Product> response = await client.GetEntityAsync<Product>(
    rowKey: "68719518391",
    partitionKey: "gear-surf-surfboards"
);

É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.

string category = "gear-surf-surfboards";

AsyncPageable<Product> results = client.QueryAsync<Product>(
    product => product.PartitionKey == category
);

Analysez les résultats paginés de la requête en parcourant chaque page de résultats à l’aide d’une boucle asynchrone.

List<Product> entities = new();
await foreach (Product product in results)
{
    entities.Add(product);
}

Nettoyer les ressources

Lorsque vous n’avez plus besoin de l’exemple d’application ou de ressources, supprimez le déploiement correspondant et toutes les ressources.

azd down

Contenu connexe