Snabbstart: Azure Cosmos DB för Table för .NET

GÄLLER FÖR: Tabell

Den här snabbstarten visar hur du kommer igång med Azure Cosmos DB for Table från ett .NET-program. Azure Cosmos DB for Table är ett schemalöst datalager som gör att program kan lagra strukturerade tabelldata i molnet. Du får lära dig hur du skapar tabeller, rader och utför grundläggande uppgifter i din Azure Cosmos DB-resurs med hjälp av Azure.Data.Tables Package (NuGet).

Kommentar

Exempelkodfragmenten är tillgängliga på GitHub som ett .NET-projekt.

API for Table-referensdokumentationen | Azure.Data.Tables Package (NuGet)

Förutsättningar

Konfigurera

Distribuera projektets utvecklingscontainer till din miljö. Använd sedan Azure Developer CLI (azd) för att skapa ett Azure Cosmos DB for Table-konto och distribuera ett containerbaserat exempelprogram. Exempelprogrammet använder klientbiblioteket för att hantera, skapa, läsa och fråga efter exempeldata.

Open in GitHub Codespaces

Open in Dev Container

Viktigt!

GitHub-konton innehåller en berättigande till lagring och kärntimmar utan kostnad. Mer information finns i inkluderade lagrings- och kärntimmar för GitHub-konton.

  1. Öppna en terminal i projektets rotkatalog.

  2. Autentisera till Azure Developer CLI med .azd auth login Följ stegen som anges av verktyget för att autentisera till CLI med dina önskade Azure-autentiseringsuppgifter.

    azd auth login
    
  3. Använd azd init för att initiera projektet.

    azd init
    
  4. Under initieringen konfigurerar du ett unikt miljönamn.

    Dricks

    Miljönamnet används också som målresursgruppnamn. För den här snabbstarten bör du överväga att använda msdocs-cosmos-db.

  5. Distribuera Azure Cosmos DB-kontot med .azd up Bicep-mallarna distribuerar också ett exempelwebbprogram.

    azd up
    
  6. Under etableringsprocessen väljer du din prenumeration och önskad plats. Vänta tills etableringsprocessen har slutförts. Processen kan ta ungefär fem minuter.

  7. När etableringen av dina Azure-resurser är klar inkluderas en URL till det webbprogram som körs i utdata.

    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. Använd URL:en i konsolen för att navigera till webbprogrammet i webbläsaren. Observera utdata från appen som körs.

    Screenshot of the running web application.

Installera klientbiblioteket

Klientbiblioteket är tillgängligt via NuGet som Microsoft.Azure.Cosmos paket.

  1. Öppna en terminal och navigera till /src/web mappen.

    cd ./src/web
    
  2. Om det inte redan är installerat installerar du Microsoft.Azure.Cosmos paketet med .dotnet add package

    dotnet add package Microsoft.Azure.Cosmos
    
  3. Installera även paketet om det Azure.Identity inte redan är installerat.

    dotnet add package Azure.Identity
    
  4. Öppna och granska filen src/web/Cosmos.Samples.Table.Quickstart.Web.csproj för att verifiera att Microsoft.Azure.Cosmos båda posterna och Azure.Identity finns.

Kodexempel

Exempelkoden som beskrivs i den här artikeln skapar en tabell med namnet adventureworks. Varje tabellrad innehåller information om en produkt, till exempel namn, kategori, kvantitet och en försäljningsindikator. Varje produkt innehåller också en unik identifierare.

Du använder följande API för tabellklasser för att interagera med dessa resurser:

  • TableServiceClient – Den här klassen innehåller metoder för att utföra åtgärder på tjänstnivå med Azure Cosmos DB for Table.
  • TableClient – Med den här klassen kan du interagera med tabeller som finns i Azure Cosmos DB-tabell-API:et.
  • TableEntity – Den här klassen är en referens till en rad i en tabell som gör att du kan hantera egenskaper och kolumndata.

Autentisera klienten

Öppna filen Program.cs från projektkatalogen. I redigeringsprogrammet lägger du till ett användningsdirektiv för Azure.Data.Tables.

using Azure.Data.Tables;

Definiera en ny instans av TableServiceClient klassen med konstruktorn och Environment.GetEnvironmentVariable för att läsa anslutningssträng du angav tidigare.

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

Skapa en tabell

Hämta en instans av med hjälp TableServiceClient av TableClient klassen. TableClient.CreateIfNotExistsAsync Använd metoden på för TableClient att skapa en ny tabell om den inte redan finns. Den här metoden returnerar en referens till den befintliga eller nyligen skapade tabellen.

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

await tableClient.CreateIfNotExistsAsync();

Skapa ett objekt

Det enklaste sättet att skapa ett nytt objekt i en tabell är att skapa en klass som implementerar ITableEntity gränssnittet. Du kan sedan lägga till dina egna egenskaper i klassen för att fylla i kolumner med data i den tabellraden.

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

Skapa ett objekt i samlingen med hjälp Product av klassen genom att anropa 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);

Hämta ett objekt

Du kan hämta ett specifikt objekt från en tabell med hjälp av TableEntity.GetEntityAsync<T> metoden . Ange parametrarna partitionKey och rowKey för att identifiera rätt rad för att utföra en snabbpunktsläsning av objektet.

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

Frågeobjekt

När du har infogat ett objekt kan du också köra en fråga för att hämta alla objekt som matchar ett visst filter med hjälp TableClient.Query<T> av metoden. Det här exemplet filtrerar produkter efter kategori med linq-syntax, vilket är en fördel med att använda typade ITableEntity modeller som Product klassen.

Kommentar

Du kan också köra frågor mot objekt med hjälp av OData-syntax . Du kan se ett exempel på den här metoden i självstudien Frågedata .

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

Kör koden

Den här appen skapar en Tabell-API-tabell för Azure Cosmos DB. Exemplet skapar sedan ett objekt och läser sedan exakt samma objekt tillbaka. Slutligen skapar exemplet ett andra objekt och utför sedan en fråga som ska returnera flera objekt. Med varje steg matar exemplet ut metadata till konsolen om de steg som den har utfört.

Om du vill köra appen använder du en terminal för att navigera till programkatalogen och köra programmet.

dotnet run

Utdata från appen bör likna det här exemplet:

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

Rensa resurser

När du inte längre behöver Azure Cosmos DB för tabellkontot kan du ta bort motsvarande resursgrupp.

az group delete Använd kommandot för att ta bort resursgruppen.

az group delete --name $resourceGroupName

Nästa steg

I den här snabbstarten har du lärt dig hur du skapar ett Azure Cosmos DB för tabellkonto, skapar en tabell och hanterar poster med hjälp av .NET SDK. Nu kan du fördjupa dig i SDK för att lära dig hur du utför mer avancerade datafrågor och hanteringsuppgifter i Azure Cosmos DB för tabellresurser.