Rychlý start: Použití služby Azure Cosmos DB for NoSQL se sadou Azure SDK pro .NET
V tomto rychlém startu nasadíte základní aplikaci Azure Cosmos DB for Table pomocí sady Azure SDK pro .NET. Azure Cosmos DB for Table je úložiště dat bez schématu, které umožňuje aplikacím ukládat strukturovaná data tabulek v cloudu. Naučíte se vytvářet tabulky, řádky a provádět základní úlohy v rámci prostředku služby Azure Cosmos DB pomocí sady Azure SDK pro .NET.
Referenční dokumentace k | rozhraní API – Balíček zdrojového kódu | knihovny (NuGet) | Azure Developer CLI
Požadavky
- Azure Developer CLI
- Docker Desktop
- .NET 9.0
Pokud nemáte účet Azure, vytvořte si bezplatný účet před tím, než začnete.
Inicializace projektu
Pomocí Azure Developer CLI (azd
) vytvořte účet Azure Cosmos DB for Table a nasaďte kontejnerizovanou ukázkovou aplikaci. Ukázková aplikace používá klientskou knihovnu ke správě, vytváření, čtení a dotazování ukázkových dat.
Otevřete terminál v prázdném adresáři.
Pokud ještě nejste ověřeni, ověřte se v Azure Developer CLI pomocí
azd auth login
. Postupujte podle kroků určených nástrojem k ověření v rozhraní příkazového řádku pomocí vašich upřednostňovaných přihlašovacích údajů Azure.azd auth login
Slouží
azd init
k inicializaci projektu.azd init --template cosmos-db-nosql-dotnet-quickstart
Během inicializace nakonfigurujte jedinečný název prostředí.
Nasaďte účet služby Azure Cosmos DB pomocí
azd up
. Šablony Bicep také nasazují ukázkovou webovou aplikaci.azd up
Během procesu zřizování vyberte své předplatné, požadované umístění a cílovou skupinu prostředků. Počkejte na dokončení procesu zřizování. Proces může trvat přibližně pět minut.
Po dokončení zřizování prostředků Azure se do výstupu zahrne adresa URL spuštěné webové aplikace.
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.
Pomocí adresy URL v konzole přejděte do webové aplikace v prohlížeči. Sledujte výstup spuštěné aplikace.
Instalace klientské knihovny
Klientská knihovna je k dispozici prostřednictvím Balíčku NuGet Microsoft.Azure.Cosmos
.
Otevřete terminál a přejděte do
/src/web
složky.cd ./src/web
Pokud ještě není nainstalovaný, nainstalujte
Microsoft.Azure.Cosmos
balíček pomocídotnet add package
.dotnet add package Microsoft.Azure.Cosmos --version 3.*
Pokud ještě není nainstalovaný, nainstalujte
Azure.Identity
balíček.dotnet add package Azure.Identity --version 1.12.*
Otevřete a zkontrolujte soubor src/web/Cosmos.Samples.NoSQL.Quickstart.Web.csproj a ověřte, že
Microsoft.Azure.Cosmos
existují oběAzure.Identity
položky.
Objektový model
Název | Popis |
---|---|
CosmosClient | Tato třída je primární klientskou třídou a slouží ke správě metadat nebo databází pro celý účet. |
Database | Tato třída představuje databázi v rámci účtu. |
Container | Tato třída se primárně používá k provádění operací čtení, aktualizace a odstraňování v kontejneru nebo v položkách uložených v kontejneru. |
PartitionKey | Tato třída představuje klíč logického oddílu. Tato třída se vyžaduje pro mnoho běžných operací a dotazů. |
Příklady kódu
- Ověření klienta
- Získání databáze
- Získání kontejneru
- Vytvoření položky
- Získání položky
- Dotazování položek
Vzorový kód v šabloně používá databázi pojmenovanou cosmicworks
a kontejner s názvem products
. Kontejner products
obsahuje podrobnosti, jako je název, kategorie, množství, jedinečný identifikátor a příznak prodeje pro každý produkt. Kontejner používá /category
vlastnost jako klíč logického oddílu.
Ověření klienta
Tato ukázka vytvoří novou instanci CosmosClient
třídy a ověří se pomocí DefaultAzureCredential
instance.
DefaultAzureCredential credential = new();
CosmosClient client = new(
accountEndpoint: "<azure-cosmos-db-nosql-account-endpoint>",
tokenCredential: new DefaultAzureCredential()
);
Získání databáze
Slouží client.GetDatabase
k načtení existující databáze s názvem cosmicworks
.
Database database = client.GetDatabase("cosmicworks");
Získání kontejneru
Načtení existujícího products
kontejneru pomocí database.GetContainer
.
Container container = database.GetContainer("products");
Vytvoření položky
Sestavte typ záznamu jazyka C# se všemi členy, které chcete serializovat do formátu JSON. V tomto příkladu má typ jedinečný identifikátor a pole pro kategorii, název, množství, cenu a prodej.
public record Product(
string id,
string category,
string name,
int quantity,
decimal price,
bool clearance
);
Vytvoření položky v kontejneru pomocí container.UpsertItem
. Tato metoda "upserts" položku účinně nahradí položku, pokud již existuje.
Product item = new(
id: "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
category: "gear-surf-surfboards",
name: "Yamba Surfboard",
quantity: 12,
price: 850.00m,
clearance: false
);
ItemResponse<Product> response = await container.UpsertItemAsync<Product>(
item: item,
partitionKey: new PartitionKey("gear-surf-surfboards")
);
Čtení položky
Proveďte operaci čtení bodu pomocí polí jedinečného identifikátoru (id
) i klíče oddílu. Slouží container.ReadItem
k efektivnímu načtení konkrétní položky.
ItemResponse<Product> response = await container.ReadItemAsync<Product>(
id: "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
partitionKey: new PartitionKey("gear-surf-surfboards")
);
Dotazování položek
Proveďte dotaz na více položek v kontejneru pomocí container.GetItemQueryIterator
. Pomocí tohoto parametrizovaného dotazu vyhledejte všechny položky v zadané kategorii:
SELECT * FROM products p WHERE p.category = @category
string query = "SELECT * FROM products p WHERE p.category = @category"
var query = new QueryDefinition(query)
.WithParameter("@category", "gear-surf-surfboards");
using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
queryDefinition: query
);
Parsujte stránkované výsledky dotazu tak, že projdete každou stránku výsledků pomocí feed.ReadNextAsync
. Slouží feed.HasMoreResults
k určení, jestli na začátku každé smyčky zbývá nějaké výsledky.
List<Product> items = new();
while (feed.HasMoreResults)
{
FeedResponse<Product> response = await feed.ReadNextAsync();
foreach (Product item in response)
{
items.Add(item);
}
}
Vyčištění prostředků
Pokud už ukázkovou aplikaci nebo prostředky nepotřebujete, odeberte odpovídající nasazení a všechny prostředky.
azd down