Rychlý Start: Vytvoření aplikace rozhraní API pro tabulky pomocí sady .NET SDK a Azure Cosmos DBQuickstart: Build a Table API app with .NET SDK and Azure Cosmos DB

PLATÍ pro: rozhraní API pro tabulky

Tento rychlý start ukazuje, jak pomocí .NET a rozhraní Table API služby Azure Cosmos DB sestavit aplikaci naklonováním příkladu z GitHubu.This quickstart shows how to use .NET and the Azure Cosmos DB Table API to build an app by cloning an example from GitHub. Tento rychlý start také ukazuje, jak vytvořit účet služby Azure Cosmos DB a jak pomocí Průzkumníku dat vytvářet tabulky a entity na webu Azure Portal.This quickstart also shows you how to create an Azure Cosmos DB account and how to use Data Explorer to create tables and entities in the web-based Azure portal.

PožadavkyPrerequisites

Pokud ještě nemáte nainstalovanou aplikaci Visual Studio 2019, můžete si stáhnout a použít bezplatnou edici Visual Studio 2019 Community Edition.If you don’t already have Visual Studio 2019 installed, you can download and use the free Visual Studio 2019 Community Edition. Nezapomeňte při instalaci sady Visual Studio povolit možnost Azure Development.Make sure that you enable Azure development during the Visual Studio setup.

Pokud ještě nemáte předplatné Azure, vytvořte si bezplatný účet před tím, než začnete.If you don't have an Azure subscription, create a free account before you begin.

Vytvoření účtu databázeCreate a database account

  1. V novém okně prohlížeče se přihlaste k webu Azure Portal.In a new browser window, sign in to the Azure portal.

  2. V nabídce vlevo vyberte vytvořit prostředek.In the left menu, select Create a resource.

    Vytvoření prostředku na portálu Azure Portal

  3. Na stránce Nový vyberte databáze > Azure Cosmos DB.On the New page, select Databases > Azure Cosmos DB.

    Podokno Databáze na webu Azure Portal

  4. Na stránce vytvořit Azure Cosmos DB účet zadejte nastavení pro nový účet Azure Cosmos DB.On the Create Azure Cosmos DB Account page, enter the settings for the new Azure Cosmos DB account.

    NastaveníSetting HodnotaValue PopisDescription
    PředplatnéSubscription Vaše předplatnéYour subscription Vyberte předplatné Azure, které chcete pro tento účet služby Azure Cosmos DB použít.Select the Azure subscription that you want to use for this Azure Cosmos DB account.
    Skupina prostředkůResource Group Vytvořit nový a potom název účtuCreate new, then Account Name Vyberte, že chcete vytvořit novou IP adresu.Select Create new. Pak zadejte nový název skupiny prostředků pro váš účet.Then enter a new resource group name for your account. Pro jednoduchost použijte stejný název jako název účtu Azure Cosmos DB.For simplicity, use the same name as your Azure Cosmos DB account name.
    Account NameAccount Name Jedinečný názevA unique name Zadejte jedinečný název, který identifikuje váš účet služby Azure Cosmos DB.Enter a unique name to identify your Azure Cosmos DB account.

    Název účtu může obsahovat jenom malá písmena, číslice a spojovníky (-) a musí mít délku 3 až 31 znaků.The account name can use only lowercase letters, numbers, and hyphens (-), and must be between 3 and 31 characters long.
    Rozhraní APIAPI TabulkaTable Rozhraní API určuje typ účtu, který se má vytvořit.The API determines the type of account to create. Azure Cosmos DB poskytuje pět rozhraní API: Core (SQL) pro databáze dokumentů, Gremlin pro databáze grafů, MongoDB pro databáze dokumentů, tabulku Azure a Cassandra.Azure Cosmos DB provides five APIs: Core (SQL) for document databases, Gremlin for graph databases, MongoDB for document databases, Azure Table, and Cassandra. Pro každé rozhraní API musíte vytvořit samostatný účet.You must create a separate account for each API.

    Vyberte tabulka Azure, protože v tomto rychlém startu vytváříte tabulku, která funguje s rozhraní API pro tabulky.Select Azure Table, because in this quickstart you are creating a table that works with the Table API.

    Přečtěte si další informace o rozhraní API pro tabulky.Learn more about the Table API.
    UmístěníLocation Oblast nejbližší vašim uživatelůmThe region closest to your users Vyberte zeměpisné umístění, ve kterém chcete účet služby Azure Cosmos DB hostovat.Select a geographic location to host your Azure Cosmos DB account. Použijte umístění, které je vašim uživatelům nejbližší, abyste jim zajistili nejrychlejší přístup k datům.Use the location that's closest to your users to give them the fastest access to the data.
    Režim kapacityCapacity mode Zřízená propustnost nebo bez serveruProvisioned throughput or Serverless Vyberte zřízenou propustnost a vytvořte účet v režimu zřízené propustnosti .Select Provisioned throughput to create an account in provisioned throughput mode. Pokud chcete vytvořit účet v režimu bez serveru , vyberte možnost bez serveru .Select Serverless to create an account in serverless mode.

    Můžete ponechat možnosti pro zápis geografické redundance a více oblastí na Zakázat , abyste se vyhnuli dalším poplatkům, a přeskočíte části síť a značky .You can leave the Geo-Redundancy and Multi-region Writes options at Disable to avoid additional charges, and skip the Network and Tags sections.

  5. Vyberte zkontrolovat + vytvořit.Select Review+Create. Po dokončení ověření vyberte vytvořit a vytvořte účet.After the validation is complete, select Create to create the account.

    Stránka nového účtu pro službu Azure Cosmos DB

  6. Vytvoření účtu trvá několik minut.It takes a few minutes to create the account. Zobrazí se zpráva s informací o tom, že probíhá vaše nasazení.You'll see a message that states Your deployment is underway. Počkejte, až se nasazení dokončí, a pak vyberte Přejít k prostředku.Wait for the deployment to finish, and then select Go to resource.

    Podokno oznámení Azure Portal

Přidání tabulkyAdd a table

Teď můžete pomocí nástroje Průzkumník dat na webu Azure Portal vytvořit databázi a tabulku.You can now use the Data Explorer tool in the Azure portal to create a database and table.

  1. Vyberte Průzkumník dat > Nová tabulka.Select Data Explorer > New Table.

    Úplně vpravo se zobrazí oblast Přidat tabulku. Pokud ji nevidíte, možná se budete muset posunout doprava.The Add Table area is displayed on the far right, you may need to scroll right to see it.

    Průzkumník dat na webu Azure Portal

  2. Na stránce Přidat tabulku zadejte nastavení pro novou tabulku.In the Add Table page, enter the settings for the new table.

    NastaveníSetting Navrhovaná hodnotaSuggested value PopisDescription
    ID tabulkyTable Id sample-tablesample-table ID vaší nové tabulky.The ID for your new table. Názvy tabulek mají stejné požadavky na znaky jako ID databází.Table names have the same character requirements as database ids. Názvy databází musí mít délku 1 až 255 znaků a nesmí obsahovat znaky / \ # ? ani koncové mezery.Database names must be between 1 and 255 characters, and cannot contain / \ # ? or a trailing space.
    PropustnostThroughput 400 RU/s400 RUs Změňte propustnost na 400 jednotek žádostí za sekundu (RU/s).Change the throughput to 400 request units per second (RU/s). Pokud budete chtít snížit latenci, můžete propustnost později navýšit.If you want to reduce latency, you can scale up the throughput later.
  3. Vyberte OK.Select OK.

  4. Průzkumník dat zobrazí novou databázi a tabulku.Data Explorer displays the new database and table.

    Průzkumník dat na webu Azure Portal zobrazující novou databázi a tabulku

Přidání ukázkových datAdd sample data

Teď můžete přidávat do nové tabulky data pomocí Průzkumníku dat.You can now add data to your new table using Data Explorer.

  1. V Průzkumník dat rozbalte položku Ukázka-Table, vyberte entity a pak vyberte Přidat entitu.In Data Explorer, expand sample-table, select Entities, and then select Add Entity.

    Vytváření nových entit v Průzkumníku dat na portálu Azure Portal

  2. Nyní přidejte data do pole hodnota PartitionKey a do pole hodnota RowKey a vyberte Přidat entitu.Now add data to the PartitionKey value box and RowKey value box, and select Add Entity.

    Nastavení klíče oddílu a klíče řádku pro novou entitu

    Teď můžete přidat další entity do tabulky, upravit si entity nebo zadat dotazy na data v Průzkumníku dat.You can now add more entities to your table, edit your entities, or query your data in Data Explorer. V Průzkumníku dat také můžete škálovat propustnost a přidat do tabulky uložené procedury, uživatelsky definované funkce a aktivační události.Data Explorer is also where you can scale your throughput and add stored procedures, user-defined functions, and triggers to your table.

Klonování ukázkové aplikaceClone the sample application

Teď naklonujeme aplikaci Table z GitHubu, nastavíme připojovací řetězec a spustíme ji.Now let's clone a Table app from GitHub, set the connection string, and run it. Přesvědčíte se, jak snadno se pracuje s daty prostřednictvím kódu programu.You'll see how easy it is to work with data programmatically.

  1. Otevřete příkazový řádek, vytvořte novou složku git-samples a pak příkazový řádek zavřete.Open a command prompt, create a new folder named git-samples, then close the command prompt.

    md "C:\git-samples"
    
  2. Otevřete okno terminálu Git, například Git Bash, a pomocí příkazu cd přejděte do nové složky, do které chcete nainstalovat ukázkovou aplikaci.Open a git terminal window, such as git bash, and use the cd command to change to the new folder to install the sample app.

    cd "C:\git-samples"
    
  3. Ukázkové úložiště naklonujete spuštěním následujícího příkazu.Run the following command to clone the sample repository. Tento příkaz vytvoří na vašem počítači kopii ukázkové aplikace.This command creates a copy of the sample app on your computer.

    git clone https://github.com/Azure-Samples/azure-cosmos-table-dotnet-core-getting-started.git
    

Tip

Podrobnější návod k podobnému kódu naleznete v článku ukázkový článek pro Cosmos DB rozhraní API pro tabulky .For a more detailed walkthrough of similar code, see the Cosmos DB Table API sample article.

Otevření ukázkové aplikace v sadě Visual StudioOpen the sample application in Visual Studio

  1. V sadě Visual Studio z nabídky Soubor zvolte Otevřít a pak Projekt nebo řešení.In Visual Studio, from the File menu, choose Open, then choose Project/Solution.

    Otevření řešení

  2. Přejděte do složky, do které jste naklonováni ukázkovou aplikaci, a otevřete soubor TableStorage. sln.Navigate to the folder where you cloned the sample application and open the TableStorage.sln file.

Kontrola kóduReview the code

Tento krok je volitelný.This step is optional. Pokud chcete zjistit, jak se v kódu vytvářejí prostředky databáze, můžete si prohlédnout následující fragmenty kódu.If you're interested in learning how the database resources are created in the code, you can review the following snippets. V opačném případě můžete přeskočit k části aktualizace připojovacího řetězce v tomto dokumentu.Otherwise, you can skip ahead to update the connection string section of this doc.

  • Následující kód ukazuje, jak vytvořit tabulku v rámci Azure Storage:The following code shows how to create a table within the Azure Storage:

    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;
    }
    
  • Následující kód ukazuje, jak vložit data do tabulky:The following code shows how to insert data into the table:

    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;
        }
    }
    
  • Následující kód ukazuje, jak zadávat dotazy na data z tabulky:The following code shows how to query data from the table:

    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;
        }
    }
    
  • Následující kód ukazuje, jak odstranit data z tabulky:The following code shows how to delete data from the table:

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

Aktualizace připojovacího řetězceUpdate your connection string

Teď se vraťte zpátky na portál Azure Portal, kde najdete informace o připojovacím řetězci, a zkopírujte je do aplikace.Now go back to the Azure portal to get your connection string information and copy it into the app. Tím aplikaci umožníte komunikovat s hostovanou databází.This enables your app to communicate with your hosted database.

  1. Na webu Azure Portal klikněte na Připojovací řetězec.In the Azure portal, click Connection String. Pomocí tlačítka pro kopírování na pravé straně okna zkopírujte PRIMÁRNÍ PŘIPOJOVACÍ ŘETĚZEC.Use the copy button on the right side of the window to copy the PRIMARY CONNECTION STRING.

    Zobrazení a zkopírování PRIMÁRNÍHO PŘIPOJOVACÍHO ŘETĚZCE v podokně Připojovací řetězec

  2. V aplikaci Visual Studio otevřete Settings.jsv souboru.In Visual Studio, open the Settings.json file.

  3. Vložte primární připojovací řetězec z portálu do hodnoty StorageConnectionString.Paste the PRIMARY CONNECTION STRING from the portal into the StorageConnectionString value. Řetězec vložte do uvozovek.Paste the string inside the quotes.

    {
       "StorageConnectionString": "<Primary connection string from Azure portal>"
    }
    
  4. Stisknutím kombinace kláves CTRL + S uložte Settings.jsdo souboru.Press CTRL+S to save the Settings.json file.

Teď jste aktualizovali aplikaci a zadali do ní všechny informace potřebné ke komunikaci s Azure Cosmos DB.You've now updated your app with all the info it needs to communicate with Azure Cosmos DB.

Sestavení a nasazení aplikaceBuild and deploy the app

  1. V aplikaci Visual Studio klikněte pravým tlačítkem na projekt CosmosTableSamples v Průzkumník řešení a pak klikněte na Spravovat balíčky NuGet.In Visual Studio, right-click on the CosmosTableSamples project in Solution Explorer and then click Manage NuGet Packages.

    Správa balíčků NuGet

  2. Do pole Procházet NuGet zadejte Microsoft. Azure. Cosmos. Table.In the NuGet Browse box, type Microsoft.Azure.Cosmos.Table. Vyhledá se klientská knihovna rozhraní Cosmos DB Table API.This will find the Cosmos DB Table API client library. Všimněte si, že tato knihovna je aktuálně dostupná pro .NET Framework a .NET Standard.Note that this library is currently available for .NET Framework and .NET Standard.

    Karta Procházet NuGet

  3. Kliknutím na nainstalovat nainstalujte knihovnu Microsoft. Azure. Cosmos. Table .Click Install to install the Microsoft.Azure.Cosmos.Table library. Tím se nainstaluje balíček rozhraní Azure Cosmos DB Table API a všechny závislosti.This installs the Azure Cosmos DB Table API package and all dependencies.

  4. Když spustíte celou aplikaci, ukázková data se vloží do entity tabulky a odstraní se na konci, takže se žádná data nevloží, pokud spustíte celou ukázku.When you run the entire app, sample data is inserted into the table entity and deleted at the end so you won’t see any data inserted if you run the whole sample. Můžete však vložit některé zarážky k zobrazení dat.However you can insert some breakpoints to view the data. Otevřete soubor BasicSamples. cs a klikněte pravým tlačítkem na řádek 52, vyberte zarážku a pak vyberte Vložit zarážku.Open BasicSamples.cs file and right-click on line 52, select Breakpoint, then select Insert Breakpoint. Vložte další zarážku na řádku 55.Insert another breakpoint on line 55.

    Přidání zarážky

  5. Stisknutím klávesy F5 spusťte aplikaci.Press F5 to run the application. V okně konzoly se zobrazí název nové databáze tabulek (v tomto případě demoa13b1) v Azure Cosmos DB.The console window displays the name of the new table database (in this case, demoa13b1) in Azure Cosmos DB.

    Výstup konzoly

    Až se dostanete k první zarážce, přejděte zpět do Průzkumníku dat na webu Azure Portal.When you hit the first breakpoint, go back to Data Explorer in the Azure portal. Klikněte na tlačítko Aktualizovat, rozbalte tabulku demo* a klikněte na Entity.Click the Refresh button, expand the demo* table, and click Entities. Na kartě Entity na pravé straně se zobrazí nově přidaná entita pro Waltera Harpa.The Entities tab on the right shows the new entity that was added for Walter Harp. Všimněte si, že telefonní číslo nové entity je 425-555-0101.Note that the phone number for the new entity is 425-555-0101.

    Nová entita

    Pokud se zobrazí chybová zpráva oznamující, že při spuštění projektu nelze najít Settings.jspro soubor, můžete ho vyřešit přidáním následující položky XML do nastavení projektu.If you receive an error that says Settings.json file can’t be found when running the project, you can resolve it by adding the following XML entry to the project settings. Klikněte pravým tlačítkem na CosmosTableSamples, vyberte Upravit CosmosTableSamples. csproj a přidejte následující položku:Right click on CosmosTableSamples, select Edit CosmosTableSamples.csproj and add the following itemGroup:

      <ItemGroup>
        <None Update="Settings.json">
          <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
        </None>
      </ItemGroup>
    
  6. Zavřete kartu Entity v Průzkumníku dat.Close the Entities tab in Data Explorer.

  7. Stisknutím klávesy F5 spusťte aplikaci až k další zarážce.Press F5 to run the app to the next breakpoint.

    Až se dostanete k zarážce, přejděte zpět na web Azure Portal, znovu klikněte na Entity a otevřete kartu Entity. Všimněte si, že se telefonní číslo aktualizovalo na 425-555-0105.When you hit the breakpoint, switch back to the Azure portal, click Entities again to open the Entities tab, and note that the phone number has been updated to 425-555-0105.

  8. Stisknutím klávesy F5 spusťte aplikaci.Press F5 to run the app.

    Aplikace přidá entity pro použití v pokročilejší ukázkové aplikaci, kterou rozhraní Table API v současné době nepodporuje.The app adds entities for use in an advanced sample app that the Table API currently does not support. Aplikace pak odstraní tabulku vytvořenou ukázkovou aplikací.The app then deletes the table created by the sample app.

  9. V okně konzoly stiskněte Enter a ukončete aplikaci.In the console window, press Enter to end the execution of the app.

Ověření smluv SLA na webu Azure PortalReview SLAs in the Azure portal

Azure Portal sleduje propustnost účtu Cosmos DB, úložiště, dostupnost, latenci a konzistenci.The Azure portal monitors your Cosmos DB account throughput, storage, availability, latency, and consistency. Grafy pro metriky přidružené k Azure Cosmos DB smlouva SLA (SLA) ukazují hodnotu SLA v porovnání s skutečným výkonem.Charts for metrics associated with an Azure Cosmos DB Service Level Agreement (SLA) show the SLA value compared to actual performance. Tato sada metrik umožňuje monitorovat SLA transparentním způsobem.This suite of metrics makes monitoring your SLAs transparent.

Postup kontroly metrik a SLA:To review metrics and SLAs:

  1. V navigační nabídce účtu Cosmos DB vyberte metriky .Select Metrics in your Cosmos DB account's navigation menu.

  2. Vyberte kartu, jako je latence, a vyberte časový rámec na pravé straně.Select a tab such as Latency, and select a timeframe on the right. Porovnejte skutečné řádky a řádky SLA v grafech.Compare the Actual and SLA lines on the charts.

    Sada metrik Azure Cosmos DB

  3. Projděte si metriky na dalších kartách.Review the metrics on the other tabs.

Vyčištění prostředkůClean up resources

Až budete s aplikací a Azure Cosmos DB účtem hotovi, můžete odstranit prostředky Azure, které jste vytvořili, abyste se neúčtují další poplatky.When you're done with your app and Azure Cosmos DB account, you can delete the Azure resources you created so you don't incur more charges. Odstranění prostředků:To delete the resources:

  1. Na panelu hledání Azure Portal vyhledejte a vyberte skupiny prostředků.In the Azure portal Search bar, search for and select Resource groups.

  2. V seznamu vyberte skupinu prostředků, kterou jste vytvořili pro tento rychlý Start.From the list, select the resource group you created for this quickstart.

    Vyberte skupinu prostředků, kterou chcete odstranit.

  3. Na stránce Přehled skupiny prostředků vyberte Odstranit skupinu prostředků.On the resource group Overview page, select Delete resource group.

    Odstranění skupiny prostředků

  4. V dalším okně zadejte název skupiny prostředků, kterou chcete odstranit, a pak vyberte Odstranit.In the next window, enter the name of the resource group to delete, and then select Delete.

Další krokyNext steps

V tomto rychlém startu jste se seznámili s postupem vytvoření databázového účtu Azure Cosmos DB, vytvoření tabulky pomocí Průzkumníka dat a spuštění aplikace.In this quickstart, you've learned how to create an Azure Cosmos DB account, create a table using the Data Explorer, and run an app. Teď můžete zadávat dotazy na svá data pomocí rozhraní API tabulky.Now you can query your data using the Table API.