rychlý start: vytvoření konzolové aplikace pomocí sady .net V4 SDK (preview) pro správu prostředků Azure Cosmos DB SQLm účtu rozhraní API

Článek
11/24/2021
12 min ke čtení

PLATÍ PRO: SQL API

začínáme s klientskou knihovnou rozhraní API Azure Cosmos DB SQL pro .net postupujte podle kroků v tomto článku a nainstalujte balíček .net V4 (Azure. Cosmos) a sestavte aplikaci. pak vyzkoušejte ukázkový kód pro operace základních operací vytvoření, čtení, aktualizace a odstranění (CRUD) na datech uložených v Azure Cosmos DB.

Důležité

sada .net V4 SDK pro Azure Cosmos DB je aktuálně ve verzi public preview. Tato verze Preview se poskytuje bez smlouvy o úrovni služeb a nedoporučujeme ji pro produkční úlohy. Některé funkce se nemusí podporovat nebo mohou mít omezené možnosti.

Další informace najdete v dodatečných podmínkách použití pro verze Preview v Microsoft Azure.

Azure Cosmos DB je databáze microsoftu pro rychlé NoSQL s otevřenými rozhraními api pro jakékoli škálování. Azure Cosmos DB můžete použít k rychlému vytvoření a dotazování databáze klíčů/hodnot, dokumentů a grafů. použijte klientskou knihovnu Azure Cosmos DB SQL API pro rozhraní .net pro:

vytvoření databáze služby Azure Cosmos a kontejneru.
Přidejte do kontejneru ukázková data.
Dotaz na data.
Odstraňte databázi.

Zdrojový kód knihovny | Balíček (NuGet)

Požadavky

Předplatné Azure. Vytvořte si ho zdarma. můžete také vyzkoušet Azure Cosmos DB bez předplatného Azure, zdarma a závazky.
Sada SDK .NET Core 3. Spuštěním sady můžete ověřit, která verze je ve vašem prostředí k dispozici dotnet --version .

Nastavení

v této části se seznámíte s vytvořením účtu Azure Cosmos a nastavením projektu, který pro správu prostředků používá klientskou knihovnu rozhraní API Azure Cosmos DB SQL pro .net.

Vzorový kód popsaný v tomto článku vytvoří FamilyDatabase databázi a rodinné členy v rámci této databáze. Každý rodinný člen je položka a má vlastnosti Id , jako, FamilyName , FirstName , LastName , Parents , Children , a Address . LastNameVlastnost se používá jako klíč oddílu pro kontejner.

Vytvoření účtu Azure Cosmos

pokud pro vytvoření účtu azure Cosmos použijete možnost vyzkoušet Azure Cosmos DB for free , musíte vytvořit účet azure Cosmos typu SQL API. účet testování služby Azure Cosmos je už pro vás vytvořený. Účet není nutné vytvářet explicitně, takže můžete tuto část přeskočit a přejít k další části.

pokud máte vlastní předplatné azure nebo jste předplatné vytvořili zdarma, měli byste účet Azure Cosmos vytvořit explicitně. následující kód vytvoří účet Azure Cosmos s konzistencí relací. Účet je replikován v 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. Nabízí flexibilitu při výběru prostředí, které nejlépe vyhovuje způsobu, jakým pracujete: buď bash, nebo PowerShell.

Pro tento rychlý Start použijte 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řihlaste se k Cloud Shell.

Zkopírujte a vložte následující kód pro Azure Cloud Shell a spusťte jej. název účtu Azure Cosmos musí být globálně jedinečný, proto nezapomeňte mysqlapicosmosdb hodnotu aktualizovat před spuštěním příkazu.


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

# The Azure Cosmos account name must be globally unique, so be 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 trvá delší dobu. Po úspěšném provedení operace uvidíte výstup potvrzení. přihlaste se k Azure Portal a ověřte, že účet Azure Cosmos se zadaným názvem existuje. Po vytvoření prostředku můžete okno Azure Cloud Shell zavřít.

Vytvoření aplikace v .NET

Vytvořte aplikaci .NET v upřednostňovaném editoru nebo integrovaném vývojovém prostředí (IDE). 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 dotnet new příkazu vytvořte aplikaci s názvem todo . --langVersionParametr nastaví LangVersion vlastnost v souboru vytvořeného projektu.

dotnet new console --langVersion:8 -n todo

Pomocí následujících příkazů změňte adresář na nově vytvořenou složku aplikace a sestavte aplikaci:

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\netcoreapp3.0\todo.dll

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

Time Elapsed 00:00:34.17

instalace balíčku Azure Cosmos DB

i když jste stále v adresáři aplikace, nainstalujte Azure Cosmos DB klientskou knihovnu pro .net Core pomocí dotnet add package příkazu:

dotnet add package Azure.Cosmos --version 4.0.0-preview3

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

ukázková aplikace se musí ověřit pro váš účet Azure Cosmos. k ověření předejte přihlašovací údaje účtu Azure Cosmos do aplikace. pomocí následujících kroků získejte přihlašovací údaje k účtu Azure Cosmos:

Přihlaste se k webu Azure Portal.
přejít na účet Azure Cosmos.
Otevřete podokno klíče a zkopírujte hodnoty identifikátoru URI a primárního klíče pro váš účet. Do proměnné prostředí v dalším postupu přidáte identifikátor URI a klíčové hodnoty.

Informace o objektovém modelu

než budete pokračovat v sestavování aplikace, podívejme se na hierarchii prostředků v Azure Cosmos DB a objektového modelu, který se používá k vytvoření a přístup 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 entit najdete v článku Azure Cosmos DB resource model . 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 se používá ke konfiguraci a provádění požadavků na službu.
CreateDatabaseIfNotExistsAsync. Tato metoda vytvoří (Pokud neexistuje) nebo získá (Pokud již existuje) databázový prostředek jako asynchronní operaci.
CreateContainerIfNotExistsAsync. Tato metoda vytvoří (Pokud neexistuje) nebo získá (Pokud již existuje) kontejner jako asynchronní operace. Můžete zjistit stavový kód z odpovědi, abyste zjistili, zda byl kontejner nově vytvořen (201) nebo byl vrácen existující kontejner (200).
CreateItemAsync. Tato metoda vytvoří položku v rámci kontejneru.
UpsertItemAsync. Tato metoda vytvoří položku v rámci kontejneru, pokud ještě neexistuje, nebo ji nahradí, pokud již existuje.
GetItemQueryIterator. tato metoda vytvoří dotaz na položky v rámci kontejneru ve službě Azure Cosmos database pomocí příkazu SQL s parametrizovanými hodnotami.
DeleteAsync. tato metoda odstraní zadanou databázi z účtu Azure Cosmos.

Konfigurace příkladů kódu

vzorový kód popsaný v tomto článku vytvoří v Azure Cosmos DB databázi rodiny. Databáze rodiny obsahuje podrobnosti o rodině, jako je jméno, adresa, umístění, rodiče, děti a domácí.

než nasadíte data pro účet Azure Cosmos, definujte vlastnosti rodinné položky. Vytvořte novou třídu s názvem Family.cs na kořenové úrovni ukázkové aplikace a přidejte do ní následující kód:

using System.Text.Json;
using System.Text.Json.Serialization;

namespace todo
{
    public class Family
    {
        [JsonPropertyName("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; }
        public override string ToString()
        {
            return JsonSerializer.Serialize(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řidejte direktivy using a definujte objekt klienta.

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

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

Do třídy přidejte následující globální proměnné Program . Tyto proměnné budou zahrnovat koncový bod a autorizační klíče, název databáze a kontejner, který vytvoříte. Nezapomeňte nahradit hodnoty koncový bod a autorizační klíč podle vašeho prostředí.

private const string EndpointUrl = "https://<your-account>.documents.azure.com:443/";
private const string AuthorizationKey = "<your-account-key>";
private const string DatabaseId = "FamilyDatabase";
private const string ContainerId = "FamilyContainer";

Nakonec nahraďte Main metodu:

static async Task Main(string[] args)
{
    
    CosmosClient cosmosClient = new CosmosClient(EndpointUrl, AuthorizationKey);
    await Program.CreateDatabaseAsync(cosmosClient);
    await Program.CreateContainerAsync(cosmosClient);
    await Program.AddItemsToContainerAsync(cosmosClient);
    await Program.QueryItemsAsync(cosmosClient);
    await Program.ReplaceFamilyItemAsync(cosmosClient);
    await Program.DeleteFamilyItemAsync(cosmosClient);
    await Program.DeleteDatabaseAndCleanupAsync(cosmosClient);
}

Vytvoření databáze

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

/// <summary>
/// Create the database if it does not exist
/// </summary>
private static async Task CreateDatabaseAsync(CosmosClient cosmosClient)
{
    // Create a new database
    CosmosDatabase database = await cosmosClient.CreateDatabaseIfNotExistsAsync(Program.DatabaseId);
    Console.WriteLine("Created Database: {0}\n", database.Id);
}

Vytvoření kontejneru

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

/// <summary>
/// Create the container if it does not exist. 
/// Specify "/LastName" as the partition key since we're storing family information, to ensure good distribution of requests and storage.
/// </summary>
/// <returns></returns>
private static async Task CreateContainerAsync(CosmosClient cosmosClient)
{
    // Create a new container
    CosmosContainer container = await cosmosClient.GetDatabase(Program.DatabaseId).CreateContainerIfNotExistsAsync(Program.ContainerId, "/LastName");
    Console.WriteLine("Created Container: {0}\n", container.Id);
}

Vytvoření položky

Vytvořte položku rodiny přidáním AddItemsToContainerAsync metody s následujícím kódem. Můžete použít CreateItemAsync UpsertItemAsync metodu nebo k vytvoření položky.

/// <summary>
/// Add Family items to the container
/// </summary>
private static async Task AddItemsToContainerAsync(CosmosClient cosmosClient)
{
    // 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
    };

    CosmosContainer container = cosmosClient.GetContainer(Program.DatabaseId, Program.ContainerId);
    try
    {
        // Read the item to see if it exists.  
        ItemResponse<Family> andersenFamilyResponse = await container.ReadItemAsync<Family>(andersenFamily.Id, new PartitionKey(andersenFamily.LastName));
        Console.WriteLine("Item in database with id: {0} already exists\n", andersenFamilyResponse.Value.Id);
    }
    catch(CosmosException ex) when (ex.Status == (int)HttpStatusCode.NotFound)
    {
        // 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 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 off the ItemResponse.
        Console.WriteLine("Created item in database with id: {0}\n", andersenFamilyResponse.Value.Id);
    }

    // Create a family object for the Wakefield family
    Family wakefieldFamily = new Family
    {
        Id = "Wakefield.7",
        LastName = "Wakefield",
        Parents = new Parent[]
        {
            new Parent { FamilyName = "Wakefield", FirstName = "Robin" },
            new Parent { FamilyName = "Miller", FirstName = "Ben" }
        },
        Children = new Child[]
        {
            new Child
            {
                FamilyName = "Merriam",
                FirstName = "Jesse",
                Gender = "female",
                Grade = 8,
                Pets = new Pet[]
                {
                    new Pet { GivenName = "Goofy" },
                    new Pet { GivenName = "Shadow" }
                }
            },
            new Child
            {
                FamilyName = "Miller",
                FirstName = "Lisa",
                Gender = "female",
                Grade = 1
            }
        },
        Address = new Address { State = "NY", County = "Manhattan", City = "NY" },
        IsRegistered = true
    };

    // Create an item in the container representing the Wakefield family. Note we provide the value of the partition key for this item, which is "Wakefield"
    ItemResponse<Family> wakefieldFamilyResponse = await container.UpsertItemAsync<Family>(wakefieldFamily, new PartitionKey(wakefieldFamily.LastName));

    // Note that after creating the item, we can access the body of the item with the Resource property off 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}\n", wakefieldFamilyResponse.Value.Id);
}

Dotazování na položky

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

/// <summary>
/// Run a query (using Azure Cosmos DB SQL syntax) against the container
/// </summary>
private static async Task QueryItemsAsync(CosmosClient cosmosClient)
{
    var sqlQueryText = "SELECT * FROM c WHERE c.LastName = 'Andersen'";

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

    CosmosContainer container = cosmosClient.GetContainer(Program.DatabaseId, Program.ContainerId);

    QueryDefinition queryDefinition = new QueryDefinition(sqlQueryText);

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

    await foreach (Family family in container.GetItemQueryIterator<Family>(queryDefinition))
    {
        families.Add(family);
        Console.WriteLine("\tRead {0}\n", family);
    }
}

Nahrazení položky

Přečtěte si položku rodiny a pak ji aktualizujte přidáním ReplaceFamilyItemAsync metody s následujícím kódem:

/// <summary>
/// Replace an item in the container
/// </summary>
private static async Task ReplaceFamilyItemAsync(CosmosClient cosmosClient)
{
    CosmosContainer container = cosmosClient.GetContainer(Program.DatabaseId, Program.ContainerId);

    ItemResponse<Family> wakefieldFamilyResponse = await container.ReadItemAsync<Family>("Wakefield.7", new PartitionKey("Wakefield"));
    Family itemBody = wakefieldFamilyResponse;
    
    // update registration status from false to true
    itemBody.IsRegistered = true;
    // update grade of child
    itemBody.Children[0].Grade = 6;

    // replace the item with the updated content
    wakefieldFamilyResponse = await container.ReplaceItemAsync<Family>(itemBody, itemBody.Id, new PartitionKey(itemBody.LastName));
    Console.WriteLine("Updated Family [{0},{1}].\n \tBody is now: {2}\n", itemBody.LastName, itemBody.Id, wakefieldFamilyResponse.Value);
}

Odstranění položky

Odstraňte položku rodiny přidáním DeleteFamilyItemAsync metody s následujícím kódem:

/// <summary>
/// Delete an item in the container
/// </summary>
private static async Task DeleteFamilyItemAsync(CosmosClient cosmosClient)
{
    CosmosContainer container = cosmosClient.GetContainer(Program.DatabaseId, Program.ContainerId);

    string partitionKeyValue = "Wakefield";
    string familyId = "Wakefield.7";

    // Delete an item. Note we must provide the partition key value and id of the item to delete
    ItemResponse<Family> wakefieldFamilyResponse = await container.DeleteItemAsync<Family>(familyId,new PartitionKey(partitionKeyValue));
    Console.WriteLine("Deleted Family [{0},{1}]\n", partitionKeyValue, familyId);
}

Odstranění databáze

Databázi můžete odstranit přidáním DeleteDatabaseAndCleanupAsync metody s následujícím kódem:

/// <summary>
/// Delete the database and dispose of the Cosmos Client instance
/// </summary>
private static async Task DeleteDatabaseAndCleanupAsync(CosmosClient cosmosClient)
{
    CosmosDatabase database = cosmosClient.GetDatabase(Program.DatabaseId);
    DatabaseResponse databaseResourceResponse = await database.DeleteAsync();

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

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

Spuštění kódu

spusťte aplikaci a vytvořte Azure Cosmos DB prostředky:

dotnet run

Při spuštění aplikace se vygeneruje následující výstup:

Created Database: FamilyDatabase

Created Container: FamilyContainer

Created item in database with id: Andersen.1

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}

Updated Family [Wakefield,Wakefield.7].
        Body is now: {"id":"Wakefield.7","LastName":"Wakefield","Parents":[{"FamilyName":"Wakefield","FirstName":"Robin"}   {"FamilyName":"Miller","FirstName":"Ben"}],"Children":[{"FamilyName":"Merriam","FirstName":"Jesse","Gender":"female","Grade":6   "Pets":[{"GivenName":"Goofy"},{"GivenName":"Shadow"}]},{"FamilyName":"Miller","FirstName":"Lisa","Gender":"female","Grade":1   "Pets":null}],"Address":{"State":"NY","County":"Manhattan","City":"NY"},"IsRegistered":true}

Deleted Family [Wakefield,Wakefield.7]

Deleted Database: FamilyDatabase

End of demo, press any key to exit.

můžete ověřit, že se data vytvoří, když se přihlásíte k Azure Portal a zobrazíte požadované položky v účtu Azure Cosmos.

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

když už účet azure Cosmos a odpovídající skupinu prostředků nepotřebujete, můžete k jejich odebrání použít azure CLI nebo Azure PowerShell. 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 vytvořit kontejner pomocí aplikace .net Core. teď můžete do účtu Azure Cosmos importovat další data pomocí pokynů v následujícím článku:

chcete se pokusit plánování kapacity pro migraci na Azure Cosmos DB? Pro plánování kapacity můžete použít informace o vašem existujícím databázovém clusteru.

Pokud znáte počet virtuální jádra a serverů v existujícím databázovém clusteru, přečtěte si téma odhadování jednotek žádostí pomocí virtuální jádra nebo vCPU .
pokud znáte typické míry požadavků pro aktuální databázovou úlohu, přečtěte si téma odhadace jednotek žádostí pomocí Azure Cosmos DB kapacity plánovače .

Importování dat do služby Azure Cosmos DB