Rychlý start: Vytvoření konzolové aplikace .NET pro správu prostředků rozhraní API služby Azure Cosmos DB SQL

PLATÍ PRO: SQL API

Začínáme s klientskou knihovnou rozhraní API SQL služby Azure Cosmos DB pro .NET. Podle kroků v tomto dokumentu nainstalujte balíček .NET, sestavte aplikaci a vyzkoušejte ukázkový kód pro základní operace CRUD s daty uloženými v Azure Cosmos DB.

Azure Cosmos DB je rychlá databáze NoSQL Microsoftu s otevřenými rozhraními API pro libovolné škálování. Azure Cosmos DB můžete použít k rychlému vytváření a dotazování na klíč/hodnotu, dokument a grafové databáze. Použijte klientskou knihovnu rozhraní API služby Azure Cosmos DB SQL pro .NET k:

  • Vytvoření databáze azure Cosmos a kontejneru
  • Přidání ukázkových dat do kontejneru
  • Vytváření dotazů na data
  • Odstranění databáze

Referenční dokumentace | k rozhraní API Zdrojový kód | knihovny Balíček (NuGet)

Požadavky

Nastavení

Tato část vás provede vytvořením účtu Azure Cosmos a nastavením projektu, který ke správě prostředků používá klientskou knihovnu rozhraní API služby Azure Cosmos DB SQL. Ukázkový kód popsaný v tomto článku vytvoří FamilyDatabase databázi a členy rodiny (každý člen rodiny je položka) v této databázi. Každý člen rodiny má vlastnosti, například Id, FamilyName, FirstName, LastName, Parents, Children, Address,. Vlastnost LastName se používá jako klíč oddílu kontejneru.

Vytvoření účtu Azure Cosmos

Pokud použijete bezplatnou možnost Vyzkoušet azure Cosmos DB k vytvoření účtu Azure Cosmos, musíte vytvořit účet Azure Cosmos DB typu SQL API. Testovací účet služby Azure Cosmos DB je již vytvořený za vás. Účet nemusíte explicitně vytvářet, takže můžete tento oddíl přeskočit a přejít k další části.

Pokud máte vlastní předplatné Azure nebo jste si předplatné vytvořili zdarma, měli byste explicitně vytvořit účet Azure Cosmos. Následující kód vytvoří účet Azure Cosmos s konzistencí relace. Účet se replikuje do South Central US a North Central US.

K vytvoření účtu Azure Cosmos můžete použít Azure Cloud Shell. Azure Cloud Shell je interaktivní prostředí pro správu prostředků Azure, které je po ověření dostupné z webového prohlížeče. Umožňuje flexibilně zvolit prostředí, které nejlépe vyhovuje vašemu stylu práce – Bash nebo PowerShell. Pro účely tohoto rychlého startu zvolte režim Bash . Azure Cloud Shell také vyžaduje účet úložiště, můžete ho vytvořit po zobrazení výzvy.

Vyberte tlačítko Vyzkoušet vedle následujícího kódu, zvolte režim Bash, vyberte vytvořit účet úložiště a přihlásit se k Cloud Shell. Pak zkopírujte a vložte následující kód do Azure Cloud Shell a spusťte ho. Název účtu Azure Cosmos musí být globálně jedinečný, před spuštěním příkazu nezapomeňte hodnotu aktualizovatmysqlapicosmosdb.


# Set variables for the new SQL API account, database, and container
resourceGroupName='myResourceGroup'
location='southcentralus'

# The Azure Cosmos account name must be globally unique, make sure to update the `mysqlapicosmosdb` value before you run the command
accountName='mysqlapicosmosdb'

# Create a resource group
az group create \
    --name $resourceGroupName \
    --location $location

# Create a SQL API Cosmos DB account with session consistency and multi-region writes enabled
az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --kind GlobalDocumentDB \
    --locations regionName="South Central US" failoverPriority=0 --locations regionName="North Central US" failoverPriority=1 \
    --default-consistency-level "Session" \
    --enable-multiple-write-locations true

Vytvoření účtu Azure Cosmos chvíli trvá, jakmile bude operace úspěšná, zobrazí se výstup potvrzení. Po úspěšném dokončení příkazu se přihlaste k Azure Portal a ověřte, že existuje účet Azure Cosmos se zadaným názvem. Po vytvoření prostředku můžete okno Azure Cloud Shell zavřít.

Vytvoření nové aplikace .NET

V preferovaném editoru nebo integrovaném vývojovém prostředí vytvořte novou aplikaci .NET. Otevřete příkazový řádek Windows nebo okno terminálu z místního počítače. Všechny příkazy v dalších částech spustíte z příkazového řádku nebo terminálu. Spuštěním následujícího příkazu dotnet new vytvořte novou aplikaci s názvem todo. Parametr --langVersion nastaví vlastnost LangVersion v vytvořeném souboru projektu.

dotnet new console --langVersion 7.1 -n todo

Změňte adresář na nově vytvořenou složku aplikace. Aplikaci můžete sestavit pomocí:

cd todo
dotnet build

Očekávaný výstup sestavení by měl vypadat přibližně takto:

  Restore completed in 100.37 ms for C:\Users\user1\Downloads\CosmosDB_Samples\todo\todo.csproj.
  todo -> C:\Users\user1\Downloads\CosmosDB_Samples\todo\bin\Debug\netcoreapp2.2\todo.dll
  todo -> C:\Users\user1\Downloads\CosmosDB_Samples\todo\bin\Debug\netcoreapp2.2\todo.Views.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:34.17

Instalace balíčku Azure Cosmos DB

V adresáři aplikace nainstalujte klientskou knihovnu Azure Cosmos DB pro .NET Core pomocí příkazu dotnet add package.

dotnet add package Microsoft.Azure.Cosmos

Zkopírování přihlašovacích údajů účtu Azure Cosmos z Azure Portal

Ukázková aplikace se musí ověřit ve vašem účtu Azure Cosmos. K ověření byste měli aplikaci předat přihlašovací údaje účtu Azure Cosmos. Pomocí následujícího postupu získejte přihlašovací údaje účtu Azure Cosmos:

  1. Přihlaste se k webu Azure Portal.

  2. Přejděte ke svému účtu Azure Cosmos.

  3. Otevřete podokno Klíče a zkopírujte identifikátor URI a PRIMÁRNÍ KLÍČ vašeho účtu. Hodnoty identifikátoru URI a klíčů přidáte do proměnné prostředí v dalším kroku.

Nastavení proměnných prostředí

Po zkopírování identifikátoru URI a primárního klíče účtu je uložte do nové proměnné prostředí na místním počítači, na kterém běží aplikace. Pokud chcete nastavit proměnnou prostředí, otevřete okno konzoly a spusťte následující příkaz. Nezapomeňte nahradit hodnoty a <Your_Azure_Cosmos_account_PRIMARY_KEY> hodnoty<Your_Azure_Cosmos_account_URI>.

Windows

setx EndpointUrl "<Your_Azure_Cosmos_account_URI>"
setx PrimaryKey "<Your_Azure_Cosmos_account_PRIMARY_KEY>"

Linux

export EndpointUrl = "<Your_Azure_Cosmos_account_URI>"
export PrimaryKey = "<Your_Azure_Cosmos_account_PRIMARY_KEY>"

macOS

export EndpointUrl = "<Your_Azure_Cosmos_account_URI>"
export PrimaryKey = "<Your_Azure_Cosmos_account_PRIMARY_KEY>"

Objektový model

Než začnete vytvářet aplikaci, podívejme se na hierarchii prostředků v Azure Cosmos DB a na objektový model použitý k vytvoření a přístupu k těmto prostředkům. Azure Cosmos DB vytvoří prostředky v následujícím pořadí:

  • Účet Azure Cosmos
  • Databáze
  • Kontejnery
  • Položky

Další informace o hierarchii různých entit najdete v článku o práci s databázemi, kontejnery a položkami v Azure Cosmos DB. K interakci s těmito prostředky použijete následující třídy .NET:

  • CosmosClient – Tato třída poskytuje logickou reprezentaci na straně klienta pro službu Azure Cosmos DB. Objekt klienta slouží ke konfiguraci a spouštění požadavků ve službě.

  • CreateDatabaseIfNotExistsAsync – Tato metoda vytvoří (pokud neexistuje) nebo získá (pokud již existuje) prostředek databáze jako asynchronní operaci.

  • CreateContainerIfNotExistsAsync - Tato metoda vytvoří (pokud neexistuje) nebo získá (pokud již existuje) kontejner jako asynchronní operaci. Stavový kód můžete z odpovědi zkontrolovat a zjistit, jestli byl kontejner nově vytvořen (201) nebo jestli byl vrácen existující kontejner (200).

  • CreateItemAsync – Tato metoda vytvoří položku v kontejneru.

  • UpsertItemAsync – Tato metoda vytvoří položku v kontejneru, pokud ještě neexistuje nebo nahradí položku, pokud již existuje.

  • GetItemQueryIterator – Tato metoda vytvoří dotaz na položky v kontejneru v databázi Azure Cosmos pomocí příkazu SQL s parametrizovanými hodnotami.

  • DeleteAsync – Odstraní zadanou databázi z účtu Azure Cosmos. DeleteAsync metoda odstraní pouze databázi. Cosmosclient K odstranění instance by mělo dojít samostatně (což dělá v metodě DeleteDatabaseAndCleanupAsync.

Příklady kódu

Ukázkový kód popsaný v tomto článku vytvoří databázi rodiny v Azure Cosmos DB. Rodinná databáze obsahuje podrobnosti rodiny, jako je jméno, adresa, umístění, přidružené rodiče, děti a domácí zvířata. Před naplněním dat do účtu Azure Cosmos definujte vlastnosti položky rodiny. Vytvořte novou třídu pojmenovanou Family.cs na kořenové úrovni ukázkové aplikace a přidejte do ní následující kód:

using Newtonsoft.Json;

namespace todo
{
    public class Family
    {
        [JsonProperty(PropertyName = "id")]
        public string Id { get; set; }
        public string LastName { get; set; }
        public Parent[] Parents { get; set; }
        public Child[] Children { get; set; }
        public Address Address { get; set; }
        public bool IsRegistered { get; set; }
        // The ToString() method is used to format the output, it's used for demo purpose only. It's not required by Azure Cosmos DB
        public override string ToString()
        {
            return JsonConvert.SerializeObject(this);
        }
    }

    public class Parent
    {
        public string FamilyName { get; set; }
        public string FirstName { get; set; }
    }

    public class Child
    {
        public string FamilyName { get; set; }
        public string FirstName { get; set; }
        public string Gender { get; set; }
        public int Grade { get; set; }
        public Pet[] Pets { get; set; }
    }

    public class Pet
    {
        public string GivenName { get; set; }
    }

    public class Address
    {
        public string State { get; set; }
        public string County { get; set; }
        public string City { get; set; }
    }
}

Přidání direktiv & using definující objekt klienta

V adresáři projektu otevřete Program.cs soubor v editoru a přidejte do horní části aplikace následující direktivy using:


using System;
using System.Threading.Tasks;
using System.Configuration;
using System.Collections.Generic;
using System.Net;
using Microsoft.Azure.Cosmos;

Do souboru Program.cs přidejte kód pro čtení proměnných prostředí, které jste nastavili v předchozím kroku. CosmosClientDefinujte objekty , Databasea Container objekty. Dále přidejte kód do hlavní metody, která volá metoduGetStartedDemoAsync, ve které spravujete prostředky účtu Azure Cosmos.

namespace todo
{
public class Program
{

    /// The Azure Cosmos DB endpoint for running this GetStarted sample.
    private string EndpointUrl = Environment.GetEnvironmentVariable("EndpointUrl");

    /// The primary key for the Azure DocumentDB account.
    private string PrimaryKey = Environment.GetEnvironmentVariable("PrimaryKey");

    // The Cosmos client instance
    private CosmosClient cosmosClient;

    // The database we will create
    private Database database;

    // The container we will create.
    private Container container;

    // The name of the database and container we will create
    private string databaseId = "FamilyDatabase";
    private string containerId = "FamilyContainer";

    public static async Task Main(string[] args)
    {
       try
       {
           Console.WriteLine("Beginning operations...\n");
           Program p = new Program();
           await p.GetStartedDemoAsync();

        }
        catch (CosmosException de)
        {
           Exception baseException = de.GetBaseException();
           Console.WriteLine("{0} error occurred: {1}", de.StatusCode, de);
        }
        catch (Exception e)
        {
            Console.WriteLine("Error: {0}", e);
        }
        finally
        {
            Console.WriteLine("End of demo, press any key to exit.");
            Console.ReadKey();
        }
    }
}
}

Vytvoření databáze

Definujte metodu CreateDatabaseAsync v rámci program.cs třídy. Tato metoda vytvoří, FamilyDatabase pokud ještě neexistuje.

private async Task CreateDatabaseAsync()
{
    // Create a new database
    this.database = await this.cosmosClient.CreateDatabaseIfNotExistsAsync(databaseId);
    Console.WriteLine("Created Database: {0}\n", this.database.Id);
}

Vytvoření kontejneru

Definujte metodu CreateContainerAsync v rámci program.cs třídy. Tato metoda vytvoří, FamilyContainer pokud ještě neexistuje.

/// Create the container if it does not exist. 
/// Specifiy "/LastName" as the partition key since we're storing family information, to ensure good distribution of requests and storage.
private async Task CreateContainerAsync()
{
    // Create a new container
    this.container = await this.database.CreateContainerIfNotExistsAsync(containerId, "/LastName");
    Console.WriteLine("Created Container: {0}\n", this.container.Id);
}

Vytvoření položky

Vytvořte položku rodiny přidáním AddItemsToContainerAsync metody s následujícím kódem. K vytvoření položky můžete použít tyto CreateItemAsyncUpsertItemAsync metody:

private async Task AddItemsToContainerAsync()
{
    // Create a family object for the Andersen family
    Family andersenFamily = new Family
    {
        Id = "Andersen.1",
        LastName = "Andersen",
        Parents = new Parent[]
        {
           new Parent { FirstName = "Thomas" },
           new Parent { FirstName = "Mary Kay" }
        },
        Children = new Child[]
        {
           new Child
            {
                FirstName = "Henriette Thaulow",
                Gender = "female",
                Grade = 5,
                Pets = new Pet[]
                {
                    new Pet { GivenName = "Fluffy" }
                }
            }
        },
        Address = new Address { State = "WA", County = "King", City = "Seattle" },
        IsRegistered = false
    };

    try
    {
        // Create an item in the container representing the Andersen family. Note we provide the value of the partition key for this item, which is "Andersen".
        ItemResponse<Family> andersenFamilyResponse = await this.container.CreateItemAsync<Family>(andersenFamily, new PartitionKey(andersenFamily.LastName));
        // Note that after creating the item, we can access the body of the item with the Resource property of the ItemResponse. We can also access the RequestCharge property to see the amount of RUs consumed on this request.
        Console.WriteLine("Created item in database with id: {0} Operation consumed {1} RUs.\n", andersenFamilyResponse.Resource.Id, andersenFamilyResponse.RequestCharge);
    }
    catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.Conflict)
    {
        Console.WriteLine("Item in database with id: {0} already exists\n", andersenFamily.Id);                
    }
}

Dotazování položek

Po vložení položky můžete spustit dotaz, abyste získali podrobnosti o rodině Andersen. Následující kód ukazuje, jak dotaz spustit přímo pomocí dotazu SQL. Dotaz SQL pro získání podrobností rodiny "Anderson" je: SELECT * FROM c WHERE c.LastName = 'Andersen'. Definujte metodu QueryItemsAsyncprogram.cs v rámci třídy a přidejte do ní následující kód:

private async Task QueryItemsAsync()
{
    var sqlQueryText = "SELECT * FROM c WHERE c.LastName = 'Andersen'";

    Console.WriteLine("Running query: {0}\n", sqlQueryText);

    QueryDefinition queryDefinition = new QueryDefinition(sqlQueryText);
    FeedIterator<Family> queryResultSetIterator = this.container.GetItemQueryIterator<Family>(queryDefinition);

    List<Family> families = new List<Family>();

    while (queryResultSetIterator.HasMoreResults)
    {
        FeedResponse<Family> currentResultSet = await queryResultSetIterator.ReadNextAsync();
        foreach (Family family in currentResultSet)
        {
            families.Add(family);
            Console.WriteLine("\tRead {0}\n", family);
        }
    }
}

Odstranění databáze

Nakonec můžete databázi odstranit přidáním DeleteDatabaseAndCleanupAsync metody pomocí následujícího kódu:

private async Task DeleteDatabaseAndCleanupAsync()
{
   DatabaseResponse databaseResourceResponse = await this.database.DeleteAsync();
   // Also valid: await this.cosmosClient.Databases["FamilyDatabase"].DeleteAsync();

   Console.WriteLine("Deleted Database: {0}\n", this.databaseId);

   //Dispose of CosmosClient
    this.cosmosClient.Dispose();
}

Provádění operací CRUD

Jakmile definujete všechny požadované metody, spusťte je v GetStartedDemoAsync metodě. Metoda DeleteDatabaseAndCleanupAsync byla v tomto kódu zakomentována, protože pokud se tato metoda spustí, neuvidíte žádné prostředky. Po ověření, že se vaše prostředky Azure Cosmos DB vytvořily v Azure Portal, můžete ho zrušit.

public async Task GetStartedDemoAsync()
{
    // Create a new instance of the Cosmos Client
    this.cosmosClient = new CosmosClient(EndpointUrl, PrimaryKey);
    await this.CreateDatabaseAsync();
    await this.CreateContainerAsync();
    await this.AddItemsToContainerAsync();
    await this.QueryItemsAsync();
}

Po přidání všech požadovaných metod soubor uložte Program.cs .

Spuštění kódu

Dále sestavte a spusťte aplikaci a vytvořte prostředky Azure Cosmos DB. Nezapomeňte otevřít nové okno příkazového řádku, nepoužívejte stejnou instanci, jakou jste použili k nastavení proměnných prostředí. Vzhledem k tomu, že proměnné prostředí nejsou nastaveny v aktuálním otevřeném okně. Abyste mohli zobrazit aktualizace, budete muset otevřít nový příkazový řádek.

dotnet build
dotnet run

Při spuštění aplikace se vygeneruje následující výstup. Můžete se také přihlásit k Azure Portal a ověřit, že jsou vytvořené prostředky:

Created Database: FamilyDatabase

Created Container: FamilyContainer

Created item in database with id: Andersen.1 Operation consumed 11.62 RUs.

Running query: SELECT * FROM c WHERE c.LastName = 'Andersen'

        Read {"id":"Andersen.1","LastName":"Andersen","Parents":[{"FamilyName":null,"FirstName":"Thomas"},{"FamilyName":null,"FirstName":"Mary Kay"}],"Children":[{"FamilyName":null,"FirstName":"Henriette Thaulow","Gender":"female","Grade":5,"Pets":[{"GivenName":"Fluffy"}]}],"Address":{"State":"WA","County":"King","City":"Seattle"},"IsRegistered":false}

End of demo, press any key to exit.

Data můžete ověřit přihlášením k Azure Portal a zobrazením požadovaných položek v účtu Azure Cosmos.

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

Pokud už ho nepotřebujete, můžete pomocí Azure CLI nebo Azure PowerShell odebrat účet Azure Cosmos a odpovídající skupinu prostředků. Následující příkaz ukazuje, jak odstranit skupinu prostředků pomocí Azure CLI:

az group delete -g "myResourceGroup"

Další kroky

V tomto rychlém startu jste zjistili, jak vytvořit účet Azure Cosmos, vytvořit databázi a kontejner pomocí aplikace .NET Core. Teď můžete importovat další data do účtu Azure Cosmos s pokyny v následujícím článku.

Pokoušíte se naplánovat kapacitu migrace do azure Cosmos DB? Informace o stávajícím databázovém clusteru můžete použít k plánování kapacity.