Bibliothèque de client Tables Azure pour .NET - version 12.8.1

  • Article

Le stockage Table Azure est un service qui stocke de grandes quantités de données NoSQL structurées dans le cloud, fournissant un magasin de clés/attributs avec une conception sans schéma.

Azure Cosmos DB fournit une API Table pour les applications écrites pour le stockage Table Azure qui nécessitent des fonctionnalités Premium telles que :

  • Distribution globale clé en main.
  • Un débit dédié partout dans le monde.
  • Des latences de quelques millisecondes au 99e centile.
  • Une haute disponibilité garantie.
  • Une indexation secondaire automatique.

La bibliothèque de client Tables Azure peut cibler de manière fluide les points de terminaison de service du stockage Tables Azure ou de table Azure Cosmos DB sans modification du code.

| Code sourcePackage (NuGet) | Documentation de référence sur les | APIÉchantillons | Journal des modifications

Prise en main

Installer le package

Installez la bibliothèque cliente Tables Azure pour .NET avec NuGet :

dotnet add package Azure.Data.Tables

Prérequis

  • Un abonnement Azure.
  • Un compte de stockage Azure existant ou une base de données Azure Cosmos DB avec l’API Table Azure spécifiée.

Si vous devez créer l’un de ces éléments, vous pouvez utiliser Azure CLI.

Création d’un compte de stockage

Créez un compte mystorageaccount de stockage dans le groupe MyResourceGroup de ressources de l’abonnement MySubscription dans la région USA Ouest.

az storage account create -n mystorageaccount -g MyResourceGroup -l westus --subscription MySubscription

Création d’une base de données Cosmos DB

Créez un compte MyCosmosDBDatabaseAccount Cosmos DB dans le groupe MyResourceGroup de ressources de l’abonnement MySubscription et une table nommée MyTableName dans le compte.

az cosmosdb create --name MyCosmosDBDatabaseAccount --capabilities EnableTable --resource-group MyResourceGroup --subscription MySubscription

az cosmosdb table create --name MyTableName --resource-group MyResourceGroup --account-name MyCosmosDBDatabaseAccount

Authentifier le client

Découvrez-en plus sur les options d’authentification (notamment les chaînes de connexion, la clé partagée, les signatures de clé partagée et TokenCredentials)dans nos exemples.

Concepts clés

  • TableServiceClient - Client qui fournit des méthodes pour interagir au niveau du service de table, comme la création, la liste et la suppression de tables
  • TableClient - Client qui fournit des méthodes pour interagir au niveau d’une entité de table, comme la création, l’interrogation et la suppression d’entités au sein d’une table.
  • Table - Les tables stockent les données sous forme de collections d’entités.
  • Entity - Les entités sont similaires aux lignes. Une entité possède une clé primaire et un ensemble de propriétés. Une propriété est une paire de valeur de nom, similaire à une colonne.

Voici quelques utilisations courantes du service de table :

  • Stockage des téraoctets de données structurées capables de servir des applications Web
  • Stockage de jeux de données qui ne nécessitent pas de jointures complexes, de clés étrangères ou de procédures stockées et qui peuvent être dénormalisés pour un accès rapide
  • Interrogation rapide des données par requête à l’aide d’un index cluster
  • Accès aux données à l’aide du protocole OData et des expressions de filtre LINQ

Sécurité des threads

Nous garantissons que toutes les méthodes de instance client sont thread-safe et indépendantes les unes des autres (instructions). Cela garantit que la recommandation de réutilisation des instances clientes est toujours sécurisée, même entre les threads.

Concepts supplémentaires

Options | du clientAccès à la réponse | Opérations | de longue duréeGestion des défaillances | Diagnostics | Moqueur | Durée de vie du client

Exemples

Création du client du service de Table

Tout d’abord, nous devons construire un TableServiceClient.

// Construct a new "TableServiceClient using a TableSharedKeyCredential.

var serviceClient = new TableServiceClient(
    new Uri(storageUri),
    new TableSharedKeyCredential(accountName, storageAccountKey));

Créer une table Azure

Ensuite, nous pouvons créer une table.

// Create a new table. The TableItem class stores properties of the created table.
TableItem table = serviceClient.CreateTableIfNotExists(tableName);
Console.WriteLine($"The created table's name is {table.Name}.");

Obtenir une table Azure

L’ensemble de tables Azure existantes peut être des requêtes à l’aide d’un filtre OData.

// Use the <see cref="TableServiceClient"> to query the service. Passing in OData filter strings is optional.

Pageable<TableItem> queryTableResults = serviceClient.Query(filter: $"TableName eq '{tableName}'");

Console.WriteLine("The following are the names of the tables in the query results:");

// Iterate the <see cref="Pageable"> in order to access queried tables.

foreach (TableItem table in queryTableResults)
{
    Console.WriteLine(table.Name);
}

Supprimer une table Azure

Des tables individuelles peuvent être supprimées du service.

// Deletes the table made previously.
serviceClient.DeleteTable(tableName);

Créer le client Table

Pour interagir avec les entités de table, nous devons d’abord construire un TableClient.

// Construct a new <see cref="TableClient" /> using a <see cref="TableSharedKeyCredential" />.
var tableClient = new TableClient(
    new Uri(storageUri),
    tableName,
    new TableSharedKeyCredential(accountName, storageAccountKey));

// Create the table in the service.
tableClient.Create();

Ajouter des entités de table

Nous allons définir un nouveau TableEntity afin de pouvoir l’ajouter à la table.

// Make a dictionary entity by defining a <see cref="TableEntity">.
var tableEntity = new TableEntity(partitionKey, rowKey)
{
    { "Product", "Marker Set" },
    { "Price", 5.00 },
    { "Quantity", 21 }
};

Console.WriteLine($"{tableEntity.RowKey}: {tableEntity["Product"]} costs ${tableEntity.GetDouble("Price")}.");

À l’aide de , TableClient nous pouvons maintenant ajouter notre nouvelle entité à la table.

// Add the newly created entity.
tableClient.AddEntity(tableEntity);

Interroge les entités de table

Pour inspecter l’ensemble d’entités de table existantes, nous pouvons interroger la table à l’aide d’un filtre OData.

Pageable<TableEntity> queryResultsFilter = tableClient.Query<TableEntity>(filter: $"PartitionKey eq '{partitionKey}'");

// Iterate the <see cref="Pageable"> to access all queried entities.
foreach (TableEntity qEntity in queryResultsFilter)
{
    Console.WriteLine($"{qEntity.GetString("Product")}: {qEntity.GetDouble("Price")}");
}

Console.WriteLine($"The query returned {queryResultsFilter.Count()} entities.");

Si vous préférez les expressions de requête de style LINQ, nous pouvons également interroger la table à l’aide de cette syntaxe. Pour illustrer cette syntaxe, vous aurez besoin d’un modèle fortement typé, comme celui ci-dessous :

// Define a strongly typed entity by implementing the ITableEntity interface.
public class OfficeSupplyEntity : ITableEntity
{
    public string Product { get; set; }
    public double Price { get; set; }
    public int Quantity { get; set; }
    public string PartitionKey { get; set; }
    public string RowKey { get; set; }
    public DateTimeOffset? Timestamp { get; set; }
    public ETag ETag { get; set; }
}

Compte tenu de cette définition de classe de modèle, voici comment écrire une requête :

double priceCutOff = 6.00;
Pageable<OfficeSupplyEntity> queryResultsLINQ = tableClient.Query<OfficeSupplyEntity>(ent => ent.Price >= priceCutOff);

Suppression d’entités de table

Si nous n’avons plus besoin de notre nouvelle entité de table, elle peut être supprimée.

// Delete the entity given the partition and row key.
tableClient.DeleteEntity(partitionKey, rowKey);

Dépannage

Lors de l’utilisation de la bibliothèque de tables Azure, les erreurs retournées par le service sont signalées à l’aide des mêmes codes de status HTTP retournés pour les requêtes d’API REST.

Par exemple, si vous essayez de créer une table qui existe déjà, une 409 erreur est retournée, indiquant « Conflit ».

// Construct a new TableClient using a connection string.

var client = new TableClient(
    connectionString,
    tableName);

// Create the table if it doesn't already exist.

client.CreateIfNotExists();

// Now attempt to create the same table unconditionally.

try
{
    client.Create();
}
catch (RequestFailedException ex) when (ex.Status == (int)HttpStatusCode.Conflict)
{
    Console.WriteLine(ex.ToString());
}

Configuration de la journalisation de la console

La façon la plus simple de voir les journaux consiste à activer la journalisation de la console. Pour créer un écouteur de journal du Kit de développement logiciel (SDK) Azure qui génère des messages dans la console, utilisez la méthode AzureEventSourceListener.CreateConsoleLogger.

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Pour en savoir plus sur les autres mécanismes de journalisation , consultez ici.

Étapes suivantes

Prise en main de nos exemples de table.

Problèmes connus

Vous trouverez ici la liste des problèmes connus liés aux points de terminaison de table Cosmos DB.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez cla.microsoft.com.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions