Erste Schritte mit Azure Cosmos DB for Table unter Verwendung von .NET

GILT FÜR: Tabelle

In diesem Artikel erfahren Sie, wie Sie mithilfe des .NET SDK eine Verbindung mit Azure Cosmos DB for Table herstellen. Sobald die Verbindung hergestellt ist, können Sie Vorgänge auf Tabellen und Elemente anwenden.

Paket (NuGet) | Beispiele | API-Dokumentation | Bibliotheksquellcode | Feedback einreichen |

Voraussetzungen

• Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
• Azure Cosmos DB for Table-Konto. Erstellen eines „API für Table“-Kontos.
• .NET 6.0 oder höher
• Azure-Befehlszeilenschnittstelle (CLI) oder Azure PowerShell

Einrichten des Projekts

Erstellen Sie die .NET-Konsolenanwendung

Erstellen Sie eine neue .NET-Anwendung mithilfe des Befehls mit der dotnet new Vorlage Konsole.

dotnet new console

Importieren Sie das NuGet-Paket Azure.Data.Tables mit dem Befehl dotnet add package.

dotnet add package Azure.Data.Tables

Erstellen Sie das Projekt mit dem dotnet build-Befehl.

dotnet build

Herstellen einer Verbindung mit Azure Cosmos DB for Table

Um eine Verbindung mit der API für Table von Azure Cosmos DB herzustellen, erstellen Sie eine Instanz der TableServiceClient-Klasse. Diese Klasse ist der Ausgangspunkt für das Anwenden aller Vorgänge auf Tabellen. Es gibt zwei primäre Methoden zum Herstellen einer Verbindung mit einem „API für Table“-Konto mithilfe der TableServiceClient-Klasse:

• Verbinden mit einer „API für Table“-Verbindungszeichenfolge

Verbinden mit einer Verbindungszeichenfolge

Der am häufigsten verwendete Konstruktor für TableServiceClient weist einen einzelnen Parameter auf:

Parameter	Beispielwert	BESCHREIBUNG
connectionString	Umgebungsvariable COSMOS_CONNECTION_STRING	Verbindungszeichenfolge für das „API für Table“-Konto

Rufen Sie Ihre Kontoverbindungszeichenfolge ab

Azure-Befehlszeilenschnittstelle

1. Verwenden Sie den Befehlaz cosmosdb list, um den Namen des ersten Azure Cosmos DB-Kontos in Ihrer Ressourcengruppe abzurufen und in der Shell-Variable accountName zu speichern.

   # Retrieve most recently created account name
   accountName=$(
       az cosmosdb list \
           --resource-group $resourceGroupName \
           --query "[0].name" \
           --output tsv
   )
   

2. Suchen Sie mit dem Befehl az-cosmosdb-keys-list die PRIMÄRE VERBINDUNGSZEICHENFOLGE in der Liste der Verbindungszeichenfolgen für das Konto.

   az cosmosdb keys list \
       --resource-group $resourceGroupName \
       --name $accountName \
       --type "connection-strings" \
       --query "connectionStrings[?description == \`Primary Table Connection String\`] | [0].connectionString"
   

PowerShell

1. Verwenden Sie den BefehlGet-AzCosmosDBAccount-cmdlet, um den Namen des ersten Azure Cosmos DB-Kontos in Ihrer Ressourcengruppe abzurufen und in der Shell-Variable accountName zu speichern.

   # Retrieve most recently created account name
   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
   }
   $ACCOUNT_NAME = (
       Get-AzCosmosDBAccount @parameters |
           Select-Object -Property Name -First 1
   ).Name
   

2. Suchen Sie die PRIMÄRE VERBINDUNGSZEICHENFOLGE aus der Liste der Verbindungszeichenfolgen für das Konto mit dem Get-AzCosmosDBAccountKeyCmdlet.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "ConnectionStrings"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "Primary Table Connection String" -First 1    
   

Um den PRIMÄREN VERBINDUNGSZEICHENFOLGEN-Wert in Ihrem .NET-Code zu verwenden, halten Sie auf einer neuen Umgebungsvariable auf dem lokalen Computer, auf dem die Anwendung ausgeführt wird, fort.

Windows

$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"

Linux/macOS

export COSMOS_CONNECTION_STRING="<cosmos-account-PRIMARY-CONNECTION-STRING>"

Erstellen von TableServiceClient mithilfe einer Verbindungszeichenfolge

Erstellen Sie eine neue Instanz der TableServiceClient-Klasse mit der Umgebungsvariablen COSMOS_CONNECTION_STRING als einzigem Parameter.

// New instance of TableServiceClient class using a connection string
TableServiceClient client = new(
    connectionString: Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING")!
);

Erstellen Ihrer Anwendung

Beim Erstellen Ihrer Anwendung interagiert Ihr Code hauptsächlich mit vier Arten von Ressourcen:

• Das „API für Table“-Konto, das der eindeutige Namespace der obersten Ebene für Ihre Azure Cosmos DB-Daten ist.

• Tabellen, die eine Menge einzelner Elemente in Ihrem Konto enthalten.

• Elemente, die ein einzelnes Element in Ihrer Tabelle darstellen.

Im folgenden Diagramm ist die Beziehung zwischen diesen Ressourcen dargestellt.

Hierarchisches Diagramm mit einem Azure Cosmos DB-Konto oben. Das Konto hat zwei untergeordnete Tabellenknoten. Einer der Tabellenknoten enthält zwei untergeordnete Elemente.

Jeder Ressourcentyp wird durch eine oder mehrere zugeordnete .NET-Klassen oder -Schnittstellen dargestellt. Es folgt eine Liste der gängigsten Typen:

Klasse	Beschreibung
TableServiceClient	Diese Clientklasse bietet eine clientseitige logische Darstellung für den Azure Cosmos DB-Dienst. Das Clientobjekt wird zum Konfigurieren und Ausführen von Anforderungen für den Dienst verwendet.
TableClient	Diese Clientklasse ist ein Verweis auf eine Tabelle, die möglicherweise noch nicht im Dienst vorhanden ist. Die Tabelle wird serverseitig überprüft, wenn Sie versuchen, darauf zuzugreifen oder einen Vorgang darauf anzuwenden.
ITableEntity	Diese Schnittstelle ist die Basisschnittstelle für alle Elemente, die in der Tabelle erstellt oder abgefragt werden. Diese Schnittstelle enthält alle erforderlichen Eigenschaften für Elemente in der API für Table.
TableEntity	Diese Klasse ist eine generische Implementierung der ITableEntity-Schnittstelle als Wörterbuch von Schlüssel-Wert-Paaren.

In den folgenden Leitfäden wird gezeigt, wie Sie diese verschiedenen Klassen verwenden, um Ihre Anwendung zu erstellen.

Handbuch	BESCHREIBUNG
Erstellen einer Tabelle	Erstellen von Tabellen
Erstellen eines Elements	Erstellen von Elementen
Lesen eines Elements	Lesen von Elementen

Weitere Informationen

• Paket (NuGet)
• Beispiele
• API-Referenz
• Quellcode der Bibliothek
• Feedback geben

Nächste Schritte

Nachdem Sie eine Verbindung mit einem „API für Table“-Konto hergestellt haben, können Sie anhand der nächsten Anleitung Tabellen erstellen und verwalten.

Erstellen einer Tabelle in Azure Cosmos DB for Table mithilfe von .NET