Azure Tables-Clientbibliothek für .NET– Version 12.8.1

Azure Table Storage ist ein Dienst, der große Mengen strukturierter NoSQL-Daten in der Cloud speichert und einen Schlüssel-/Attributspeicher mit einem schemalosen Entwurf bereitstellt.

Azure Cosmos DB bietet eine Tabellen-API für Anwendungen, die für Azure Table Storage geschrieben wurden und Premium-Funktionen benötigen, z. B.:

• Globale, sofort einsatzbereite Verteilung
• Dedizierter Durchsatz weltweit.
• Einstellige Latenzzeiten im Millisekundenbereich im 99. Perzentil.
• Garantierte Hochverfügbarkeit.
• Automatische sekundäre Indizierung

Die Azure Tables-Clientbibliothek kann nahtlos auf Azure Table Storage- oder Azure Cosmos DB-Tabellendienstendpunkte ohne Codeänderungen ausgerichtet werden.

Quellcode | Paket (NuGet) | API-Referenzdokumentation | Proben | Änderungsprotokoll

Erste Schritte

Installieren des Pakets

Installieren Sie die Azure Tables-Clientbibliothek für .NET mit NuGet:

dotnet add package Azure.Data.Tables

Voraussetzungen

• Ein Azure-Abonnement.
• Ein vorhandenes Azure-Speicherkonto oder eine Azure Cosmos DB-Datenbank mit angegebener Azure-Tabellen-API.

Wenn Sie eine dieser Optionen erstellen müssen, können Sie die Azure CLI verwenden.

Erstellen eines Speicherkontos

Erstellen Sie ein Speicherkonto mystorageaccount in der Ressourcengruppe MyResourceGroup im Abonnement MySubscription in der Region "USA, Westen".

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

Erstellen einer Cosmos DB-Instanz

Erstellen Sie ein Cosmos DB-Konto MyCosmosDBDatabaseAccount in der Ressourcengruppe MyResourceGroup im Abonnement MySubscription und eine Tabelle namens MyTableName im Konto.

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

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

Authentifizieren des Clients

Weitere Informationen zu Authentifizierungsoptionen (einschließlich Verbindungszeichenfolgen, freigegebener Schlüssel, Shared Key Signatures und TokenCredentials)finden Sie in unseren Beispielen.

Wichtige Begriffe

• TableServiceClient - Client, der Methoden für die Interaktion auf Tabellendienstebene bereitstellt, z. B. Erstellen, Auflisten und Löschen von Tabellen
• TableClient - Client, der Methoden für die Interaktion auf Tabellenentitätsebene bereitstellt, z. B. erstellen, abfragen und löschen von Entitäten innerhalb einer Tabelle.
• Table – Tabellen speichern Daten als Sammlungen von Entitäten.
• Entity - Entitäten ähneln Zeilen. Eine Entität besitzt einen Primärschlüssel und einen Satz von Eigenschaften. Eine Eigenschaft ist ein Name-Wert-Paar, ähnlich einer Spalte.

Der Tabellenspeicherdienst wird hauptsächlich für folgende Zwecke verwendet:

• Speicherung strukturierter Daten in TB-Größe zur Verarbeitung webbasierter Anwendungen
• Speichern von Datasets, die keine komplexen Joins, Fremdschlüssel oder gespeicherten Prozeduren erfordern und für den schnellen Zugriff denormisiert werden können
• Schnelle Datenabfrage mithilfe eines gruppierten Index
• Zugreifen auf Daten mit dem OData-Protokoll und LINQ-Filterausdrücken

Threadsicherheit

Wir garantieren, dass alle Client-instance Methoden threadsicher und unabhängig voneinander sind (Richtlinie). Dadurch wird sichergestellt, dass die Empfehlung, Clientinstanzen wiederzuverwenden, immer sicher ist, auch über Threads hinweg.

Zusätzliche Konzepte

Clientoptionen | Zugreifen auf die Antwort | Vorgänge | mit langer AusführungsdauerBehandeln von Fehlern | Diagnose | Spott | Clientlebensdauer

Beispiele

• Erstellen des Tabellendienstclients
  • Erstellen einer Azure-Tabelle
  • Abrufen einer Azure-Tabelle
  • Löschen einer Azure-Tabelle
• Erstellen des Tabellenclients
  • Hinzufügen von Tabellenentitäten
  • Abfragen von Tabellenentitäten
  • Löschen von Tabellenentitäten

Erstellen des Tabellenspeicherdienst-Clients

Zunächst müssen wir einen TableServiceClienterstellen.

// Construct a new "TableServiceClient using a TableSharedKeyCredential.

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

Erstellen einer Azure-Tabelle

Als Nächstes können wir eine neue Tabelle erstellen.

// 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}.");

Abrufen einer Azure-Tabelle

Bei den vorhandenen Azure-Tabellen können Abfragen mit einem OData-Filter verwendet werden.

// 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);
}

Löschen einer Azure-Tabelle

Einzelne Tabellen können aus dem Dienst gelöscht werden.

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

Erstellen des Tabellenclients

Um mit Tabellenentitäten zu interagieren, müssen wir zuerst eine TableClienterstellen.

// 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();

Hinzufügen von Tabellenentitäten

Definieren wir ein neues TableEntity , damit wir es der Tabelle hinzufügen können.

// 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")}.");

Mithilfe von TableClient können wir jetzt der Tabelle unsere neue Entität hinzufügen.

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

Zum Abfragen von Tabellenentitäten

Um den Satz vorhandener Tabellenentitäten zu untersuchen, können wir die Tabelle mithilfe eines OData-Filters abfragen.

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.");

Wenn Sie Abfrageausdrücke im LINQ-Stil bevorzugen, können wir die Tabelle auch mit dieser Syntax abfragen. Um diese Syntax zu veranschaulichen, benötigen Sie ein stark typisiertes Modell wie das folgende:

// 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; }
}

Bei dieser Modellklassendefinition wird beschrieben, wie Sie eine Abfrage schreiben würden:

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

Löschen von Tabellenentitäten

Wenn die neue Tabellenentität nicht mehr benötigt wird, kann sie gelöscht werden.

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

Problembehandlung

Bei Verwendung der Azure-Tabellenbibliothek werden vom Dienst zurückgegebene Fehler mithilfe der gleichen HTTP-status-Codes gemeldet, die für REST-API-Anforderungen zurückgegeben werden.

Wenn Sie beispielsweise versuchen, eine bereits vorhandene Tabelle zu erstellen, wird ein 409 Fehler zurückgegeben, der auf "Conflict" hinweist.

// 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());
}

Einrichten der Konsolenprotokollierung

Die einfachste Möglichkeit, die Protokolle anzuzeigen, besteht darin, die Konsolenprotokollierung zu aktivieren. Verwenden Sie die AzureEventSourceListener.CreateConsoleLogger-Methode, um einen Azure SDK-Protokolllistener zu erstellen, der Nachrichten an die Konsole ausgibt.

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

Weitere Informationen zu anderen Protokollierungsmechanismen finden Sie hier.

Nächste Schritte

Erste Schritte mit unseren Tabellenbeispielen.

Bekannte Probleme

Eine Liste der derzeit bekannten Probleme im Zusammenhang mit Cosmos DB-Tabellenendpunkten finden Sie hier.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter cla.microsoft.com.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.