Quickstart: Azure Cosmos DB Table-API voor .NET

  • Artikel
  • 9 minuten om te lezen

VAN TOEPASSING OP: Table-API

In deze quickstart ziet u hoe u aan de slag gaat met de Azure Cosmos DB Table-API vanuit een .NET-toepassing. De Cosmos DB Table-API is een schemaloos gegevensarchief waarmee toepassingen gestructureerde NoSQL-gegevens kunnen opslaan in de cloud. U leert hoe u tabellen, rijen maakt en basistaken uitvoert in uw Cosmos DB-resource met behulp van het Azure.Data.Tables Package (NuGet).).

Notitie

De voorbeeldcodefragmenten zijn beschikbaar op GitHub als een .NET-project.

Naslagdocumentatie | voor table-API Pakket Azure.Data.Tables (NuGet)

Vereisten

Controle van vereisten

  • Voer in een terminal- of opdrachtvenster uit dotnet --list-sdks om te controleren of .NET 6.x een van de beschikbare versies is.
  • Voer az --version (Azure CLI) of Get-Module -ListAvailable AzureRM (Azure PowerShell) uit om te controleren of de juiste Azure-opdrachtregelprogramma's zijn geïnstalleerd.

Instellen

In deze sectie wordt uitgelegd hoe u een Azure Cosmos-account maakt en een project instelt dat gebruikmaakt van de NuGet-pakketten van de Table-API.

Maak een Azure Cosmos DB-account

In deze quickstart maakt u één Azure Cosmos DB-account met behulp van de Table-API.

  1. Maak shellvariabelen voor accountName, resourceGroupName en locatie.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-quickstart-rg"
location="westus"

# Variable for account name with a randomnly generated suffix
let suffix=$RANDOM*$RANDOM
accountName="msdocs-$suffix"

  2. Als u dat nog niet hebt gedaan, meldt u zich aan bij de Azure CLI met behulp van de az login opdracht.

  3. Gebruik de az group create opdracht om een nieuwe resourcegroep in uw abonnement te maken.

    az group create \
    --name $resourceGroupName \
    --location $location

  4. Gebruik de az cosmosdb create opdracht om een nieuw Azure Cosmos DB Table-API-account te maken met standaardinstellingen.

    az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --locations regionName=$location
    --capabilities EnableTable

Table-API-connection string ophalen

  1. Zoek de Table-API connection string uit de lijst met verbindingsreeksen voor het account met de az cosmosdb list-connection-strings opdracht.

    az cosmosdb list-connection-strings \
    --resource-group $resourceGroupName \
    --name $accountName

  2. Noteer de WAARDEN VAN DE PRIMAIRE SLEUTEL . U gebruikt deze referenties later.

Een nieuwe .NET-app maken

Maak een nieuwe .NET-toepassing in een lege map met behulp van de terminal van uw voorkeur. Gebruik de dotnet new console opdracht om een nieuwe console-app te maken.

dotnet new console -output <app-name>

Installeer het NuGet-pakket van

Voeg het NuGet-pakket Azure.Data.Tables toe aan het nieuwe .NET-project. Gebruik de dotnet add package opdracht die de naam van het NuGet-pakket opgeeft.

dotnet add package Azure.Data.Tables

Omgevingsvariabelen configureren

Als u de WAARDEN VERBINDINGSREEKS in uw code wilt gebruiken, stelt u deze waarde in op de lokale computer waarop de toepassing wordt uitgevoerd. Als u de omgevingsvariabele wilt instellen, gebruikt u de terminal van uw voorkeur om de volgende opdrachten uit te voeren:

$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"

Codevoorbeelden

Met de voorbeeldcode die in dit artikel wordt beschreven, wordt een tabel met de naam adventureworksgemaakt. Elke tabelrij bevat de details van een product, zoals naam, categorie, hoeveelheid en een verkoopindicator. Elk product bevat ook een unieke id.

U gebruikt de volgende Table-API-klassen om te communiceren met deze resources:

  • TableServiceClient - Deze klasse biedt methoden voor het uitvoeren van bewerkingen op serviceniveau met de Azure Cosmos DB Table-API.
  • TableClient - Met deze klasse kunt u communiceren met tabellen die worden gehost in de Azure Cosmos DB-tabel-API.
  • TableEntity - Deze klasse is een verwijzing naar een rij in een tabel waarmee u eigenschappen en kolomgegevens kunt beheren.

De client verifiëren

Open in de projectmap het bestand Program.cs . Voeg in uw editor een using-instructie toe voor Azure.Data.Tables.

using Azure.Data.Tables;

Definieer een nieuw exemplaar van de TableServiceClient klasse met behulp van de constructor en Environment.GetEnvironmentVariable lees de connection string die u eerder hebt ingesteld.

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

Een tabel maken

Haal een exemplaar van de TableClientTableServiceClient klasse op. Gebruik de TableClient.CreateIfNotExistsAsync methode voor het TableClient maken van een nieuwe tabel als deze nog niet bestaat. Deze methode retourneert een verwijzing naar de bestaande of zojuist gemaakte tabel.

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

await tableClient.CreateIfNotExistsAsync();

Een item maken

De eenvoudigste manier om een nieuw item in een tabel te maken, is door een klasse te maken waarmee de ITableEntity interface wordt geïmplementeerd. Vervolgens kunt u uw eigen eigenschappen toevoegen aan de klasse om kolommen met gegevens in die tabelrij te vullen.

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

Maak een item in de verzameling met behulp van de Product klasse door aan te roepen 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);

Een item ophalen

U kunt een specifiek item uit een tabel ophalen met behulp van de TableEntity.GetEntityAsync<T> methode. Geef de partitionKey en rowKey als parameters op om de juiste rij te identificeren om een snel punt van dat item te lezen .

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

Query-items

Nadat u een item hebt ingevoegd, kunt u ook een query uitvoeren om alle items op te halen die overeenkomen met een specifiek filter met behulp van de TableClient.Query<T> methode. In dit voorbeeld worden producten gefilterd op categorie met linq-syntaxis . Dit is een voordeel van het gebruik van sterk getypte ITableEntity modellen, zoals de Product klasse.

Notitie

U kunt ook query's uitvoeren op items met behulp van de OData-syntaxis . In de zelfstudie Querygegevens ziet u een voorbeeld van deze benadering.

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

De code uitvoeren

Met deze app maakt u een Azure Cosmos Table-API-tabel. In het voorbeeld wordt vervolgens een item gemaakt en wordt vervolgens exact hetzelfde item teruggelezen. Ten slotte wordt in het voorbeeld een tweede item gemaakt en wordt vervolgens een query uitgevoerd die meerdere items retourneert. Bij elke stap worden in het voorbeeld metagegevens naar de console verzonden over de stappen die deze heeft uitgevoerd.

Als u de app wilt uitvoeren, gebruikt u een terminal om naar de toepassingsmap te navigeren en de toepassing uit te voeren.

dotnet run

De uitvoer van de app moet vergelijkbaar zijn met dit voorbeeld:

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

Resources opschonen

Wanneer u het Azure Cosmos DB Table-API-account niet meer nodig hebt, kunt u de bijbehorende resourcegroep verwijderen.

Gebruik de az group delete opdracht om de resourcegroep te verwijderen.

az group delete --name $resourceGroupName

Volgende stappen

In deze quickstart hebt u geleerd hoe u een Azure Cosmos DB Table-API-account maakt, een tabel maakt en vermeldingen beheert met behulp van de .NET SDK. U kunt nu dieper ingaan op de SDK voor meer informatie over het uitvoeren van meer geavanceerde gegevensquery's en beheertaken in uw Azure Cosmos DB Table-API-resources.

Aan de slag met Azure Cosmos DB Table-API en .NET