Bevezetés az Azure Cosmos DB Table API és az Azure Table Storage a .NET SDK-val való használatába

A következőkre vonatkozik: Table API

Tipp

A cikk tartalma az Azure Table Storage-ra és az Azure Cosmos DB Table API-ra vonatkozik. Az Azure Cosmos DB Table API olyan prémium táblatároló-ajánlat, amely teljesítményoptimalizált táblákat, globális elosztást és automatikus másodlagos indexeket kínál.

A Azure Cosmos DB Table API vagy az Azure Table Storage használatával strukturált NoSQL-adatmennyiségeket tárolhat a felhőben, így egy kulcs-/attribútum-tárolót biztosít a séma kisebb kialakításával. Mivel Azure Cosmos DB Table API és a Table Storage kevesebb séma, egyszerűen alkalmazkodhat az adataihoz az alkalmazás igényeinek megfelelően. Az Azure Cosmos DB Table API vagy a Table Storage használatával rugalmas adatkészleteket tárolhat, például a webalkalmazások felhasználói adatait, a címjegyzékeket, az eszköz adatait vagy a szolgáltatás által igényelt más típusú metaadatokat.

Ez az oktatóanyag egy példát mutat be, amely bemutatja, hogyan használható a .net-hez készült Microsoft Azure Cosmos db Table Library a Azure Cosmos db Table API és az Azure Table Storage forgatókönyvekkel. Az Azure-szolgáltatáshoz tartozó kapcsolódást kell használnia. Ezeket a forgatókönyveket olyan C#-példákkal vizsgáljuk, amelyek bemutatják, hogyan lehet táblákat létrehozni, adatok beszúrására/frissítésére, adatok lekérdezésére és a táblák törlésére használni.

Előfeltételek

A minta sikeres teljesítéséhez a következőkre lesz szüksége:

Azure Cosmos DB Table API-fiók létrehozása

  1. Egy új böngészőablakban jelentkezzen be az Azure Portalra.

  2. A bal oldali menüben válassza az erőforrás létrehozása lehetőséget.

    Erőforrás létrehozása az Azure Portalon

  3. Az új lapon válassza az adatbázisok > Azure Cosmos db elemet.

    Az Azure Portal Adatbázisok panelje

  4. A Azure Cosmos db fiók létrehozása lapon adja meg az új Azure Cosmos db-fiók beállításait.

    Beállítás Érték Leírás
    Előfizetés Az Ön előfizetése Válassza ki az Azure Cosmos DB-fiókhoz használni kívánt Azure-előfizetést.
    Erőforráscsoport Új létrehozása, majd a fiók neve Válassza az Új létrehozása lehetőséget. Ezután adjon meg egy új erőforráscsoport-nevet a fiókhoz. Az egyszerűség kedvéért használja ugyanazt a nevet, mint a Azure Cosmos DB fiók nevét.
    Fiók neve Egyedi név Adjon meg egy egyedi nevet az Azure Cosmos DB-fiók azonosításához.

    A fiók neve csak kisbetűket, számokat és kötőjeleket (-) tartalmazhat, és 3 – 31 karakter hosszúságú lehet.
    API Tábla A létrehozni kívánt fiók típusát az API határozza meg. A Azure Cosmos DB öt API-t biztosít: Core (SQL) dokumentum-adatbázisokhoz, Gremlin, MongoDB, Azure Table és Cassandra-hoz. Minden API-hoz létre kell hoznia egy külön fiókot.

    Válassza az Azure-tábla lehetőséget, mert ebben a rövid útmutatóban olyan táblát hoz létre, amely együttműködik a Table API.

    További információ a Table APIról.
    Hely A felhasználókhoz legközelebb eső régió Válassza ki az Azure Cosmos DB-fiókot üzemeltetéséhez használni kívánt földrajzi helyet. Használja a felhasználókhoz legközelebb lévő helyet, hogy a lehető leggyorsabb hozzáférést biztosítsa az adatokhoz.
    Kapacitásmód Kiosztott átviteli sebesség vagy kiszolgáló nélküli Válassza a kiépített átviteli sebesség lehetőséget egy fiók kiépített átviteli módban való létrehozásához. Kiszolgáló nélküli módban lévő fiók létrehozásához válassza a kiszolgáló nélküli lehetőséget.

    A Letiltás lehetőséggel elhagyhatja a geo-redundancia és a többrégiós írási beállításokat a további díjak elkerülése érdekében, és kihagyhatja a hálózat és a címkék szakaszt.

  5. Válassza a felülvizsgálat + létrehozás lehetőséget. Az ellenőrzés befejezése után válassza a Létrehozás lehetőséget a fiók létrehozásához.

    Az Azure Cosmos DB új fiók lapja

  6. A fiók létrehozása néhány percet vesz igénybe. Ekkor megjelenik egy üzenet, amely jelzi, hogy a telepítés folyamatban van. Várjon, amíg a telepítés befejeződik, majd válassza az erőforráshoz való ugrás lehetőséget.

    Az Azure Portal értesítések panel

.NET-konzol projekt létrehozása

Hozzon létre egy új .NET-konzol alkalmazást a Visual Studióban. A következő lépések bemutatják, hogyan hozhat létre egy Console-alkalmazást a Visual Studio 2019-ben. A Azure Cosmos DB Table Library bármilyen típusú .NET-alkalmazásban használható, beleértve az Azure Cloud Service-t vagy a webalkalmazást, valamint az asztali és mobil alkalmazásokat is. Ebben az útmutatóban az egyszerűség kedvéért egy konzolalkalmazást használunk.

  1. Válassza a fájl > új > projekt lehetőséget.

  2. Válassza a Console app (.net Core) lehetőséget, majd kattintson a tovább gombra.

  3. A projekt neve mezőben adja meg az alkalmazás nevét, például CosmosTableSamples. (Szükség szerint más nevet is megadhat.)

  4. Válassza a Létrehozás lehetőséget.

Az ebben a mintában szereplő összes példa felvehető a konzol alkalmazás program. cs fájljának Main () metódusára.

A szükséges NuGet-csomag telepítése

A NuGet csomag beszerzéséhez kövesse az alábbi lépéseket:

  1. Kattintson a jobb gombbal a projektjére a Megoldáskezelőben, és válassza a Manage NuGet Packages (NuGet-csomagok kezelése) lehetőséget.

  2. Keresse meg a, a, a Microsoft.Azure.Cosmos.Table Microsoft.Extensions.Configuration Microsoft.Extensions.Configuration.Json Microsoft.Extensions.Configuration.Binder és a telepítés lehetőséget a Microsoft Azure Cosmos db Table Library telepítéséhez.

A tárolási kapcsolati sztring konfigurálása

  1. A Azure Portalnavigáljon az Azure Cosmos-fiókjához vagy a Table Storage-fiókhoz.

  2. Nyissa meg a kapcsolati karakterlánc vagy a hozzáférési kulcsok panelt. Az ablak jobb oldalán található Másolás gomb használatával másolja a vágólapra a PRIMARY CONNECTION STRING (Elsődleges kapcsolati sztring) értékét.

    Tekintse meg és másolja a vágólapra a PRIMARY CONNECTION STRING (Elsődleges kapcsolati sztring) értékét a Kapcsolati sztring ablaktáblán.

  3. A kapcsolódási karakterlánc konfigurálásához a Visual studióból kattintson a jobb gombbal a projekt CosmosTableSamples.

  4. Válassza a Hozzáadás , majd az új elem lehetőséget. Hozzon létre egy új fájlt, Settings.jsa fájltípust írógéppel JSON konfigurációs fájlként.

  5. Cserélje le a Settings.jsfájl kódját a következő kódra, és rendelje hozzá az elsődleges kapcsolatok karakterláncát:

    {
    "StorageConnectionString": <Primary connection string of your Azure Cosmos DB account>
    }
    
  6. Kattintson a jobb gombbal a projekt CosmosTableSamples. Válassza a Hozzáadás, új elem lehetőséget, és adjon hozzá egy appSettings. cs nevű osztályt.

  7. Adja hozzá a következő kódot a AppSettings. cs fájlhoz. Ez a fájl beolvassa a Settings.jsfájlból a kapcsolódási karakterláncot, és hozzárendeli azt a konfigurációs paraméterhez:

namespace CosmosTableSamples
{
    using Microsoft.Extensions.Configuration;

    public class AppSettings
    {
        public string StorageConnectionString { get; set; }

        public static AppSettings LoadAppSettings()
        {
            IConfigurationRoot configRoot = new ConfigurationBuilder()
                .AddJsonFile("Settings.json")
                .Build();
            AppSettings appSettings = configRoot.Get<AppSettings>();
            return appSettings;
        }
    }
}

A kapcsolat részleteinek elemzése és ellenőrzése

  1. Kattintson a jobb gombbal a projekt CosmosTableSamples. Válassza a Hozzáadás, új elem lehetőséget, és adjon hozzá egy Common. cs nevű osztályt. A kapcsolat részleteinek érvényesítéséhez és az ebben az osztályban található tábla létrehozásához kódot kell írnia.

  2. Definiáljon egy metódust CreateStorageAccountFromConnectionString az alább látható módon. Ez a metódus elemzi a kapcsolati sztring részleteit, és ellenőrzi, hogy érvényes-e a fiók neve és a fiók kulcsa a "Settings.json" fájlban.

    using System;
    
    namespace CosmosTableSamples
    {
        using System.Threading.Tasks;
        using Microsoft.Azure.Cosmos.Table;
        using Microsoft.Azure.Documents;
    
        public class Common
        {
            public static CloudStorageAccount CreateStorageAccountFromConnectionString(string storageConnectionString)
            {
                CloudStorageAccount storageAccount;
                try
                {
                    storageAccount = CloudStorageAccount.Parse(storageConnectionString);
                }
                catch (FormatException)
                {
                    Console.WriteLine("Invalid storage account information provided. Please confirm the AccountName and AccountKey are valid in the app.config file - then restart the application.");
                    throw;
                }
                catch (ArgumentException)
                {
                    Console.WriteLine("Invalid storage account information provided. Please confirm the AccountName and AccountKey are valid in the app.config file - then restart the sample.");
                    Console.ReadLine();
                    throw;
                }
    
                return storageAccount;
            }
    

Tábla létrehozása

A CloudTableClient osztály segítségével lekérheti a Table Storage-ban tárolt táblákat és entitásokat. Mivel nem található táblázat a Cosmos DB Table API-fiókban, vegyük fel a CreateTableAsync metódust a Common. cs osztályba egy tábla létrehozásához:

public static async Task<CloudTable> CreateTableAsync(string tableName)
{
    string storageConnectionString = AppSettings.LoadAppSettings().StorageConnectionString;

    // Retrieve storage account information from connection string.
    CloudStorageAccount storageAccount = CreateStorageAccountFromConnectionString(storageConnectionString);

    // Create a table client for interacting with the table service
    CloudTableClient tableClient = storageAccount.CreateCloudTableClient(new TableClientConfiguration());

    Console.WriteLine("Create a Table for the demo");

    // Create a table client for interacting with the table service 
    CloudTable table = tableClient.GetTableReference(tableName);
    if (await table.CreateIfNotExistsAsync())
    {
        Console.WriteLine("Created Table named: {0}", tableName);
    }
    else
    {
        Console.WriteLine("Table {0} already exists", tableName);
    }

    Console.WriteLine();
    return table;
}

Ha "503 szolgáltatás nem érhető el" hibaüzenet jelenik meg, lehetséges, hogy a kapcsolódási mód szükséges portjait tűzfal blokkolja. A probléma megoldásához nyissa meg a szükséges portokat, vagy használja az átjáró módú kapcsolatot az alábbi kódban látható módon:

tableClient.TableClientConfiguration.UseRestExecutorForCosmosEndpoint = true;

Az entitás definiálása

Az entitások C#-objektumokhoz rendelnek egy egyéni, a TableEntityszármaztatott osztály használatával. Ha hozzá szeretne adni egy entitást egy táblához, hozzon létre egy osztályt, amely meghatározza az entitás tulajdonságait.

Kattintson a jobb gombbal a projekt CosmosTableSamples. Válassza a Hozzáadás, új mappa lehetőséget, és nevezze el modellként. A Model mappában adjon hozzá egy CustomerEntity. cs nevű osztályt, és adja hozzá a következő kódot.

namespace CosmosTableSamples.Model
{
    using Microsoft.Azure.Cosmos.Table;

    public class CustomerEntity : TableEntity
    {
        public CustomerEntity()
        {
        }

        public CustomerEntity(string lastName, string firstName)
        {
            PartitionKey = lastName;
            RowKey = firstName;
        }

        public string Email { get; set; }

        public string PhoneNumber { get; set; }
    }
}

Ez a kód olyan Entity osztályt határoz meg, amely az ügyfél utónevét használja, és a vezetéknevet adja meg a partíció kulcsaként. Egy adott entitás partíció- és sorkulcsa együttesen azonosítja az entitást a táblában. Az ugyanazzal a partíciós kulccsal rendelkező entitások gyorsabban lekérdezhető, mint a különböző partíciós kulcsokkal rendelkező entitások, de a különféle partíciós kulcsok használata lehetővé teszi a párhuzamos műveletek nagyobb méretezhetőségét. A táblákban tárolni kívánt entitásoknak támogatott típusúnak, például a TableEntity osztályból származtatottnak kell lenniük. A táblában tárolni kívánt entitástulajdonságoknak publikusnak kell lenniük, és támogatniuk kell az értékek beolvasását és beállítását is. Az entitástípusnak emellett elérhetővé kell tennie egy paraméter nélküli konstruktort is.

Entitás beszúrása vagy egyesítése

A következő mintakód létrehoz egy entitás objektumot, és hozzáadja azt a táblához. Az entitások beszúrásához vagy egyesítéséhez a TableOperation osztályon belüli InsertOrMerge metódus használható. A művelet végrehajtásához a CloudTable.ExecuteAsync metódust kell meghívni.

Kattintson a jobb gombbal a projekt CosmosTableSamples. Válassza a Hozzáadás, új elem lehetőséget, és adjon hozzá egy SamplesUtils. cs nevű osztályt. Ez az osztály tárolja az entitásokon a SZIFILISZi műveletek végrehajtásához szükséges összes kódot.

public static async Task<CustomerEntity> InsertOrMergeEntityAsync(CloudTable table, CustomerEntity entity)
{
    if (entity == null)
    {
        throw new ArgumentNullException("entity");
    }

    try
    {
        // Create the InsertOrReplace table operation
        TableOperation insertOrMergeOperation = TableOperation.InsertOrMerge(entity);

        // Execute the operation.
        TableResult result = await table.ExecuteAsync(insertOrMergeOperation);
        CustomerEntity insertedCustomer = result.Result as CustomerEntity;

        if (result.RequestCharge.HasValue)
        {
            Console.WriteLine("Request Charge of InsertOrMerge Operation: " + result.RequestCharge);
        }

        return insertedCustomer;
    }
    catch (StorageException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

Entitás beolvasása egy partícióból

Az entitásokat a TableOperation osztály lekérési metódusának használatával szerezheti be a partícióból. A következő kódrészlet a partíciós kulcs sorát, e-mail-címét és telefonszámát kéri le. Ez a példa az entitás lekérdezéséhez felhasznált kérelmek egységeit is kiírja. Az entitások lekérdezéséhez fűzze hozzá a következő kódot a SamplesUtils. cs fájlhoz:

public static async Task<CustomerEntity> RetrieveEntityUsingPointQueryAsync(CloudTable table, string partitionKey, string rowKey)
{
    try
    {
        TableOperation retrieveOperation = TableOperation.Retrieve<CustomerEntity>(partitionKey, rowKey);
        TableResult result = await table.ExecuteAsync(retrieveOperation);
        CustomerEntity customer = result.Result as CustomerEntity;
        if (customer != null)
        {
            Console.WriteLine("\t{0}\t{1}\t{2}\t{3}", customer.PartitionKey, customer.RowKey, customer.Email, customer.PhoneNumber);
        }

        if (result.RequestCharge.HasValue)
        {
            Console.WriteLine("Request Charge of Retrieve Operation: " + result.RequestCharge);
        }

        return customer;
    }
    catch (StorageException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

Entitás törlése

A lekérdezés után egyszerűen törölheti az entitásokat az entitások frissítésénél bemutatott minta alapján. Az alábbi kód lekérdez, majd töröl egy ügyfélentitást. Entitás törléséhez fűzze hozzá a következő kódot a SamplesUtils. cs fájlhoz:

public static async Task DeleteEntityAsync(CloudTable table, CustomerEntity deleteEntity)
{
    try
    {
        if (deleteEntity == null)
        {
            throw new ArgumentNullException("deleteEntity");
        }

        TableOperation deleteOperation = TableOperation.Delete(deleteEntity);
        TableResult result = await table.ExecuteAsync(deleteOperation);

        if (result.RequestCharge.HasValue)
        {
            Console.WriteLine("Request Charge of Delete Operation: " + result.RequestCharge);
        }

    }
    catch (StorageException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

A szifilisz-műveletek végrehajtása a mintaadatok alapján

Miután meghatározta a tábla létrehozásához, az entitások beszúrásához vagy egyesítéséhez szükséges metódusokat, futtassa ezeket a metódusokat a mintaadatok alapján. Ehhez kattintson a jobb gombbal a projekt CosmosTableSamples. Válassza a Hozzáadás, új elem lehetőséget, és vegyen fel egy BasicSamples. cs nevű osztályt, és adja hozzá a következő kódot. Ez a kód létrehoz egy táblát, entitásokat hoz létre hozzá.

Ha nem szeretné törölni az entitást és a táblát a projekt végén, jegyezze fel a await table.DeleteIfExistsAsync() és SamplesUtils.DeleteEntityAsync(table, customer) metódusokat a következő kódból. Érdemes kipróbálni ezeket a metódusokat, és érvényesíteni az adatellenőrzést a tábla törlése előtt.

using System;

namespace CosmosTableSamples
{
    using System.Threading.Tasks;
    using Microsoft.Azure.Cosmos.Table;
    using Model;

    class BasicSamples
    {
        public async Task RunSamples()
        {
            Console.WriteLine("Azure Cosmos DB Table - Basic Samples\n");
            Console.WriteLine();

            string tableName = "demo" + Guid.NewGuid().ToString().Substring(0, 5);

            // Create or reference an existing table
            CloudTable table = await Common.CreateTableAsync(tableName);

            try
            {
                // Demonstrate basic CRUD functionality 
                await BasicDataOperationsAsync(table);
            }
            finally
            {
                // Delete the table
                await table.DeleteIfExistsAsync();
            }
        }

        private static async Task BasicDataOperationsAsync(CloudTable table)
        {
            // Create an instance of a customer entity. See the Model\CustomerEntity.cs for a description of the entity.
            CustomerEntity customer = new CustomerEntity("Harp", "Walter")
            {
                Email = "Walter@contoso.com",
                PhoneNumber = "425-555-0101"
            };

            // Demonstrate how to insert the entity
            Console.WriteLine("Insert an Entity.");
            customer = await SamplesUtils.InsertOrMergeEntityAsync(table, customer);

            // Demonstrate how to Update the entity by changing the phone number
            Console.WriteLine("Update an existing Entity using the InsertOrMerge Upsert Operation.");
            customer.PhoneNumber = "425-555-0105";
            await SamplesUtils.InsertOrMergeEntityAsync(table, customer);
            Console.WriteLine();

            // Demonstrate how to Read the updated entity using a point query 
            Console.WriteLine("Reading the updated Entity.");
            customer = await SamplesUtils.RetrieveEntityUsingPointQueryAsync(table, "Harp", "Walter");
            Console.WriteLine();

            // Demonstrate how to Delete an entity
            Console.WriteLine("Delete the entity. ");
            await SamplesUtils.DeleteEntityAsync(table, customer);
            Console.WriteLine();
        }
    }
}

Az előző kód létrehoz egy táblázatot, amely a "demo" kezdetű, a generált GUID pedig a táblázat nevéhez lesz hozzáfűzve. Ezután hozzáadja a "hárfa Walter" nevű ügyfél-entitást és a vezetéknevét, és később frissíti a felhasználó telefonszámát.

Ebben az oktatóanyagban a Table API fiókban tárolt adatok alapszintű szifilisz-műveleteinek elvégzésére szolgáló kódot készített. Olyan speciális műveleteket is végrehajthat, mint például a – Batch adatok beszúrása, a partíción belüli összes adat lekérdezése, a partíción belüli adatok lekérdezése, a fiók azon tábláinak felsorolása, amelyek neve a megadott előtaggal kezdődik. Letöltheti a teljes minta űrlapot az Azure-Cosmos-Table-DotNet-Core-Getting-Started GitHub-tárházban. A AdvancedSamples. cs osztálynak több művelete is van, amelyeket elvégezhet az adatokon.

A projekt futtatása

A projekt CosmosTableSamples. Nyissa meg a program. cs nevű osztályt, és adja hozzá a következő kódot a BasicSamples meghívásához a projekt futtatásakor.

using System;

namespace CosmosTableSamples
{
    class Program
    {
        public static void Main(string[] args)
        {
            Console.WriteLine("Azure Cosmos Table Samples");
            BasicSamples basicSamples = new BasicSamples();
            basicSamples.RunSamples().Wait();

            AdvancedSamples advancedSamples = new AdvancedSamples();
            advancedSamples.RunSamples().Wait();

            Console.WriteLine();
            Console.WriteLine("Press any key to exit");
            Console.Read();
        }
    }
}

Most hozza létre a megoldást, és nyomja le az F5 billentyűt a projekt futtatásához. A projekt futtatásakor a következő kimenet jelenik meg a parancssorban:

Kimenet a parancssorból

Ha olyan hibaüzenetet kap, amely szerint a Settings.jsnem található a projekt futtatásakor, akkor a következő XML-bejegyzés a projekt beállításaihoz való hozzáadásával oldható meg. Kattintson a jobb gombbal a CosmosTableSamples elemre, válassza a CosmosTableSamples. csproj szerkesztése lehetőséget, és adja hozzá a következő itemGroup:

  <ItemGroup>
    <None Update="Settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
  </ItemGroup>

Most jelentkezzen be a Azure Portalba, és ellenőrizze, hogy az adatkészletek szerepelnek-e a táblában.

Eredmények a portálon

Következő lépések

Most folytassa a következő oktatóanyaggal, és megtudhatja, hogyan telepítheti át az információkat Azure Cosmos DB Table API-fiókba.