Quickstart: Azure Cosmos DB for Table voor .NET

VAN TOEPASSING OP: Tabel

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

Notitie

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

API voor tabelreferentiedocumentatie | Azure.Data.Tables Package (NuGet)

Vereisten

Instellen

Implementeer de ontwikkelcontainer van dit project in uw omgeving. Gebruik vervolgens de Azure Developer CLI (azd) om een Azure Cosmos DB for Table-account te maken en een containertoepassing te implementeren. De voorbeeldtoepassing maakt gebruik van de clientbibliotheek voor het beheren, maken, lezen en opvragen van voorbeeldgegevens.

Open in GitHub Codespaces

Open in Dev Container

Belangrijk

GitHub-accounts bevatten gratis rechten voor opslag en kernuren. Zie inbegrepen opslag- en kernuren voor GitHub-accounts voor meer informatie.

  1. Open een terminal in de hoofdmap van het project.

  2. Verifiëren bij de Azure Developer CLI met behulp van azd auth login. Volg de stappen die door het hulpprogramma zijn opgegeven om te verifiëren bij de CLI met behulp van uw favoriete Azure-referenties.

    azd auth login
    
  3. Gebruik azd init dit om het project te initialiseren.

    azd init
    
  4. Configureer tijdens de initialisatie een unieke omgevingsnaam.

    Tip

    De omgevingsnaam wordt ook gebruikt als de naam van de doelresourcegroep. Voor deze quickstart kunt u overwegen .msdocs-cosmos-db

  5. Implementeer het Azure Cosmos DB-account met behulp van azd up. De Bicep-sjablonen implementeren ook een voorbeeldwebtoepassing.

    azd up
    
  6. Selecteer tijdens het inrichtingsproces uw abonnement en gewenste locatie. Wacht tot het inrichtingsproces is voltooid. Het proces kan ongeveer vijf minuten duren.

  7. Zodra het inrichten van uw Azure-resources is voltooid, wordt er een URL naar de actieve webtoepassing opgenomen in de uitvoer.

    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. Gebruik de URL in de console om naar uw webtoepassing in de browser te navigeren. Bekijk de uitvoer van de actieve app.

    Screenshot of the running web application.

De clientbibliotheek installeren

De clientbibliotheek is beschikbaar via NuGet, als pakket Microsoft.Azure.Cosmos .

  1. Open een terminal en navigeer naar de /src/web map.

    cd ./src/web
    
  2. Als dit nog niet is geïnstalleerd, installeert u het Microsoft.Azure.Cosmos pakket met behulp van dotnet add package.

    dotnet add package Microsoft.Azure.Cosmos
    
  3. Installeer ook het Azure.Identity pakket als dat nog niet is geïnstalleerd.

    dotnet add package Azure.Identity
    
  4. Open en controleer het bestand src/web/Cosmos.Samples.Table.Quickstart.Web.csproj om te valideren dat de Microsoft.Azure.Cosmos en Azure.Identity beide vermeldingen bestaan.

Codevoorbeelden

Met de voorbeeldcode die in dit artikel wordt beschreven, wordt een tabel gemaakt met de naam adventureworks. 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 API voor Tabelklassen om te communiceren met deze resources:

  • TableServiceClient - Deze klasse biedt methoden voor het uitvoeren van bewerkingen op serviceniveau met Azure Cosmos DB for Table.
  • 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 het Program.cs bestand vanuit de projectmap. 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 verbindingsreeks 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. Met deze methode wordt een verwijzing naar de bestaande of nieuwe tabel geretourneerd.

// 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 ophalen uit een tabel met behulp van de TableEntity.GetEntityAsync<T> methode. Geef de partitionKey en rowKey als parameters op om de juiste rij te identificeren om een snelle leesbewerking van dat item uit te voeren.

// 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 behulp van Linq-syntaxis . Dit is een voordeel van het gebruik van 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 Tabel-API-tabel van Azure Cosmos DB. In het voorbeeld wordt vervolgens een item gemaakt en wordt precies hetzelfde item teruggelezen. Ten slotte maakt het voorbeeld een tweede item en voert vervolgens een query uit die meerdere items moet retourneren. Bij elke stap voert het voorbeeld metagegevens uit naar de console 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 er ongeveer uitzien als in dit voorbeeld:

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

Resources opschonen

Wanneer u het Azure Cosmos DB for Table-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 for Table-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 geavanceerdere gegevensquery's en beheertaken in uw Azure Cosmos DB voor tabelresources.