Rövid útmutató: Az Azure Cosmos DB for Table for .NET

A KÖVETKEZŐKRE VONATKOZIK: Táblázat

Ez a rövid útmutató bemutatja, hogyan kezdheti meg az Azure Cosmos DB for Table használatát egy .NET-alkalmazásból. Az Azure Cosmos DB for Table egy séma nélküli adattár, amely lehetővé teszi, hogy az alkalmazások strukturált táblaadatokat tároljanak a felhőben. Megtudhatja, hogyan hozhat létre táblákat, sorokat, és hogyan hajthat végre alapvető feladatokat az Azure Cosmos DB-erőforrásban az Azure.Data.Tables Package (NuGet) használatával.

Feljegyzés

A példakódrészletek .NET-projektként érhetők el a GitHubon.

Api for Table reference documentation | Azure.Data.Tables Package (NuGet)

Előfeltételek

Beállítás

Helyezze üzembe a projekt fejlesztési tárolóját a környezetében. Ezután az Azure Developer CLI (azd) használatával hozzon létre egy Azure Cosmos DB-t a Table-fiókhoz, és helyezzen üzembe egy tárolóalapú mintaalkalmazást. A mintaalkalmazás az ügyfélkódtárat használja a mintaadatok kezelésére, létrehozására, olvasására és lekérdezésére.

Open in GitHub Codespaces

Open in Dev Container

Fontos

A GitHub-fiókok magukban foglalják a tárterületre és az alapórákra való jogosultságot díjmentesen. További információkért tekintse meg a GitHub-fiókokhoz tartozó tárterületet és alapórákat.

  1. Nyisson meg egy terminált a projekt gyökérkönyvtárában.

  2. Hitelesítés az Azure Developer CLI-vel azd auth logina . Kövesse az eszköz által megadott lépéseket a parancssori felületre való hitelesítéshez az ön által előnyben részesített Azure-hitelesítő adatokkal.

    azd auth login
    
  3. A projekt inicializálására használható azd init .

    azd init
    
  4. Az inicializálás során konfiguráljon egy egyedi környezetnevet.

    Tipp.

    A rendszer a környezet nevét is használja a célerőforráscsoport neveként. Ebben a rövid útmutatóban fontolja meg a használatát msdocs-cosmos-db.

  5. Az Azure Cosmos DB-fiók üzembe helyezése a következő használatával azd up: . A Bicep-sablonok egy minta webalkalmazást is üzembe helyeznek.

    azd up
    
  6. A kiépítési folyamat során válassza ki az előfizetést és a kívánt helyet. Várja meg, amíg a kiépítési folyamat befejeződik. A folyamat körülbelül öt percet vehet igénybe.

  7. Az Azure-erőforrások kiépítése után a kimenet tartalmazza a futó webalkalmazás URL-címét.

    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. A konzol URL-címével keresse meg a webalkalmazást a böngészőben. Figyelje meg a futó alkalmazás kimenetét.

    Screenshot of the running web application.

Telepítse az ügyfélkódtárat

Az ügyfélkódtár csomagként Microsoft.Azure.Cosmos a NuGeten keresztül érhető el.

  1. Nyisson meg egy terminált, és keresse meg a /src/web mappát.

    cd ./src/web
    
  2. Ha még nincs telepítve, telepítse a csomagot a Microsoft.Azure.Cosmos következővel dotnet add package: .

    dotnet add package Microsoft.Azure.Cosmos
    
  3. Emellett telepítse a Azure.Identity csomagot, ha még nincs telepítve.

    dotnet add package Azure.Identity
    
  4. Nyissa meg és tekintse át az src/web/Cosmos.Samples.Table.Quickstart.Web.csproj fájlt annak ellenőrzéséhez, hogy a bejegyzések és Azure.Identity a Microsoft.Azure.Cosmos bejegyzések is léteznek-e.

Kódpéldák

A cikkben ismertetett mintakód létrehoz egy táblát .adventureworks Minden táblázatsor tartalmazza egy termék részleteit, például a nevet, a kategóriát, a mennyiséget és az értékesítési mutatót. Minden termék egyedi azonosítót is tartalmaz.

A táblázatosztályokhoz készült alábbi API-val kezelheti ezeket az erőforrásokat:

  • TableServiceClient – Ez az osztály metódusokat biztosít a szolgáltatásszintű műveletek elvégzésére az Azure Cosmos DB for Table használatával.
  • TableClient – Ez az osztály lehetővé teszi az Azure Cosmos DB table API-ban üzemeltetett táblák használatát.
  • TableEntity – Ez az osztály egy tábla egy sorára mutató hivatkozás, amely lehetővé teszi a tulajdonságok és az oszlopadatok kezelését.

Az ügyfél hitelesítése

Nyissa meg a Program.cs fájlt a projektkönyvtárban. A szerkesztőben adjon hozzá egy felhasználói direktívát a következőhöz Azure.Data.Tables: .

using Azure.Data.Tables;

Definiálja az TableServiceClient osztály új példányát a konstruktor használatával, és Environment.GetEnvironmentVariable olvassa el a korábban beállított kapcsolati sztring.

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

Tábla létrehozása

Kérje le az TableClient osztály egy példányát TableServiceClient . TableClient.CreateIfNotExistsAsync Ha még nem létezik, a metódussal hozzon TableClient létre egy új táblát. Ez a metódus a meglévő vagy újonnan létrehozott táblára mutató hivatkozást ad vissza.

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

await tableClient.CreateIfNotExistsAsync();

Elem létrehozása

A legegyszerűbben úgy hozhat létre új elemet egy táblában, ha létrehoz egy osztályt, amely megvalósítja a ITableEntity felületet. Ezután hozzáadhatja saját tulajdonságait az osztályhoz az adott táblasor adatoszlopainak feltöltéséhez.

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

Hozzon létre egy elemet a gyűjteményben az Product osztály meghívásával 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);

Elem lekérése

A metódussal TableEntity.GetEntityAsync<T> egy adott elemet lekérhet egy táblából. Adja meg a partitionKey megfelelő sort a megfelelő sor azonosításához, és rowKey adja meg a paramétereket az elem gyors olvasásához .

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

Lekérdezési elemek

Miután beszúrt egy elemet, lekérdezést is futtathat az adott szűrőnek megfelelő összes elem lekéréséhez a TableClient.Query<T> metódus használatával. Ez a példa linq szintaxissal szűri a termékeket kategória szerint, ami az osztályhoz hasonló Product típusmodellek ITableEntity használatának előnye.

Feljegyzés

OData szintaxissal is lekérdezhet elemeket. Erre a megközelítésre a Lekérdezési adatok oktatóanyagban talál példát.

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

A kód futtatása

Ez az alkalmazás létrehoz egy Azure Cosmos DB Table API-táblát. A példa ezután létrehoz egy elemet, majd pontosan ugyanazt az elemet olvassa vissza. Végül a példa létrehoz egy második elemet, majd végrehajt egy lekérdezést, amely több elemet ad vissza. A példa minden lépéssel metaadatokat ad ki a konzolnak az elvégzett lépésekről.

Az alkalmazás futtatásához egy terminál használatával lépjen az alkalmazás könyvtárára, és futtassa az alkalmazást.

dotnet run

Az alkalmazás kimenetének az alábbi példához hasonlónak kell lennie:

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

Az erőforrások eltávolítása

Ha már nincs szüksége az Azure Cosmos DB for Table-fiókra, törölheti a megfelelő erőforráscsoportot.

az group delete Az erőforráscsoport törléséhez használja a parancsot.

az group delete --name $resourceGroupName

Következő lépések

Ebben a rövid útmutatóban megtanulta, hogyan hozhat létre Egy Azure Cosmos DB for Table-fiókot, hogyan hozhat létre táblát, és hogyan kezelheti a bejegyzéseket a .NET SDK használatával. Most részletesebben is megismerkedhet az SDK-val, és megtudhatja, hogyan hajthat végre fejlettebb adat lekérdezéseket és felügyeleti feladatokat az Azure Cosmos DB for Table-erőforrásokban.