Začínáme se službou Azure Cosmos DB for NoSQL s využitím .NET

PLATÍ PRO: NoSQL

V tomto článku se dozvíte, jak se připojit ke službě Azure Cosmos DB for NoSQL pomocí sady .NET SDK. Po připojení můžete provádět operace s databázemi, kontejnery a položkami.

Referenční informace ke | zdrojovému kódu knihovny api pro balíčky (NuGet) | – | Referenční informace ke zdrojovému kódu knihovny |

Požadavky

• Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
• Účet Služby Azure Cosmos DB for NoSQL Vytvořte účet rozhraní API pro NoSQL.
• .NET 6.0 nebo novější
• Rozhraní příkazového řádku Azure (CLI) nebo Azure PowerShell

Nastavení projektu

Vytvoření konzolové aplikace .NET

Pomocí příkazu se šablonou konzoly vytvořte novou aplikaci dotnet new .NET.

dotnet new console

Importujte balíček NuGet Microsoft.Azure.Cosmos pomocí dotnet add package příkazu.

dotnet add package Microsoft.Azure.Cosmos

Sestavte projekt pomocí dotnet build příkazu.

dotnet build

Připojení do služby Azure Cosmos DB for NoSQL

Pokud se chcete připojit k rozhraní API pro NoSQL služby Azure Cosmos DB, vytvořte instanci CosmosClient třídy. Tato třída je výchozím bodem pro provádění všech operací s databázemi. Existují tři základní způsoby připojení k účtu ROZHRANÍ API pro NoSQL pomocí třídy CosmosClient :

• Připojení s využitím koncového bodu API pro NoSQL a klíče pro čtení a zápis
• Připojení s rozhraním API for NoSQL připojovací řetězec
• Připojení s ID Microsoft Entra

Připojení s koncovým bodem a klíčem

Nejběžnější konstruktor pro CosmosClient má dva parametry:

Parametr	Příklad hodnoty	Popis
accountEndpoint	COSMOS_ENDPOINT proměnná prostředí	Rozhraní API pro koncový bod NoSQL, který se má použít pro všechny požadavky
authKeyOrResourceToken	COSMOS_KEY proměnná prostředí	Klíč účtu nebo token prostředku, který se má použít při ověřování

Načtení koncového bodu a klíče účtu

Azure CLI

1. Vytvořte proměnnou prostředí pro resourceGroupName.

   # Variable for resource group name
   resourceGroupName="msdocs-cosmos-dotnet-howto-rg"
   

2. az cosmosdb list Pomocí příkazu načtěte název prvního účtu služby Azure Cosmos DB ve vaší skupině prostředků a uložte ho do proměnné prostředí accountName.

   # Retrieve most recently created account name
   accountName=$(
       az cosmosdb list \
           --resource-group $resourceGroupName \
           --query "[0].name" \
           --output tsv
   )
   

3. Pomocí příkazu získejte identifikátor URI koncového bodu API pro NoSQL pro účetaz cosmosdb show.

   az cosmosdb show \
       --resource-group $resourceGroupName \
       --name $accountName \
       --query "documentEndpoint"
   

4. Pomocí příkazu najděte PRIMÁRNÍ KLÍČ ze seznamu klíčů pro účetaz-cosmosdb-keys-list.

   az cosmosdb keys list \
       --resource-group $resourceGroupName \
       --name $accountName \
       --type "keys" \
       --query "primaryMasterKey"
   

5. Zaznamená hodnoty identifikátoru URI a PRIMÁRNÍHO KLÍČE . Tyto přihlašovací údaje použijete později.

PowerShell

1. Vytvořte proměnnou prostředí pro RESOURCE_GROUP_NAME.

   # Variable for resource group name
   $RESOURCE_GROUP_NAME = "msdocs-cosmos-dotnet-howto-rg"
   

2. Pomocí rutiny Get-AzCosmosDBAccount načtěte název prvního účtu služby Azure Cosmos DB ve vaší skupině prostředků a uložte ho do proměnné prostředí ACCOUNT_NAME .

   # Retrieve most recently created account name
   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
   }
   $ACCOUNT_NAME = (
       Get-AzCosmosDBAccount @parameters |
           Select-Object -Property Name -First 1
   ).Name
   

3. Pomocí rutiny Get-AzCosmosDBAccount získejte identifikátor URI koncového bodu API pro NoSQL pro účet.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
   }
   Get-AzCosmosDBAccount @parameters |
       Select-Object -Property "DocumentEndpoint"
   

4. Vyhledejte primární klíč ze seznamu klíčů pro účet pomocí rutinyGet-AzCosmosDBAccountKey.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "Keys"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "PrimaryMasterKey"    
   

5. Zaznamená hodnoty identifikátoru URI a PRIMÁRNÍHO KLÍČE . Tyto přihlašovací údaje použijete později.

Azure Portal

Tip

Pro tuto příručku doporučujeme použít název msdocs-cosmos-dotnet-howto-rgskupiny prostředků .

1. Přihlaste se k portálu Azure.

2. Přejděte na existující stránku účtu Azure Cosmos DB for NoSQL.

3. Na stránce účtu Azure Cosmos DB for NoSQL vyberte možnost navigační nabídky Klíče .

   

4. Poznamenejte si hodnoty z polí identifikátoru URI a PRIMÁRNÍ KLÍČ . Tyto hodnoty použijete v pozdějším kroku.

   

Pokud chcete v kódu .NET použít hodnoty URI a PRIMARY KEY , zachovejte je do nových proměnných prostředí na místním počítači, na kterém je aplikace spuštěná.

Windows

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

Linux / macOS

export COSMOS_ENDPOINT="<cosmos-account-URI>"
export COSMOS_KEY="<cosmos-account-PRIMARY-KEY>"

Vytvoření CosmosClient s koncovým bodem účtu a klíčem

Vytvořte novou instanci třídy CosmosClient s proměnnými COSMOS_ENDPOINT prostředí a COSMOS_KEY jako parametry.

// New instance of CosmosClient class using an endpoint and key string
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    authKeyOrResourceToken: Environment.GetEnvironmentVariable("COSMOS_KEY")!
);

Připojení s připojovací řetězec

Jiný konstruktor pro CosmosClient obsahuje pouze jeden parametr:

Parametr	Příklad hodnoty	Popis
accountEndpoint	COSMOS_ENDPOINT proměnná prostředí	Rozhraní API pro koncový bod NoSQL, který se má použít pro všechny požadavky
connectionString	COSMOS_CONNECTION_STRING proměnná prostředí	řetězec Připojení pro účet ROZHRANÍ API pro NoSQL

Načtení připojovací řetězec účtu

Azure CLI

1. az cosmosdb list Pomocí příkazu načtěte název prvního účtu služby Azure Cosmos DB ve vaší skupině prostředků a uložte ho do proměnné prostředí accountName.

   # Retrieve most recently created account name
   accountName=$(
       az cosmosdb list \
           --resource-group $resourceGroupName \
           --query "[0].name" \
           --output tsv
   )
   

2. V seznamu připojovací řetězec pro účet pomocí az-cosmosdb-keys-list příkazu vyhledejte PRIMÁRNÍ PŘIPOJOVACÍ ŘETĚZEC.

   az cosmosdb keys list \
       --resource-group $resourceGroupName \
       --name $accountName \
       --type "connection-strings" \
       --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"
   

PowerShell

1. Pomocí rutiny Get-AzCosmosDBAccount načtěte název prvního účtu služby Azure Cosmos DB ve vaší skupině prostředků a uložte ho do proměnné prostředí ACCOUNT_NAME .

   # Retrieve most recently created account name
   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
   }
   $ACCOUNT_NAME = (
       Get-AzCosmosDBAccount @parameters |
           Select-Object -Property Name -First 1
   ).Name
   

2. V seznamu připojovací řetězec pro účet pomocí Get-AzCosmosDBAccountKey rutiny vyhledejte PRIMÁRNÍ PŘIPOJOVACÍ ŘETĚZEC.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "ConnectionStrings"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "Primary SQL Connection String" -First 1    
   

Azure Portal

Tip

Pro tuto příručku doporučujeme použít název msdocs-cosmos-dotnet-howto-rgskupiny prostředků .

1. Přihlaste se k portálu Azure.

2. Přejděte na existující stránku účtu Azure Cosmos DB for NoSQL.

3. Na stránce účtu Azure Cosmos DB for NoSQL vyberte možnost navigační nabídky Klíče .

4. Poznamenejte si hodnotu z pole PRIMÁRNÍ PŘIPOJOVACÍ ŘETĚZEC .

Chcete-li použít hodnotu PRIMARY CONNECTION STRING v kódu .NET, zachovejte ji do nové proměnné prostředí na místním počítači, na kterém běží aplikace.

Windows

$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"

Linux / macOS

export COSMOS_CONNECTION_STRING="<cosmos-account-PRIMARY-CONNECTION-STRING>"

Vytvoření CosmosClient pomocí připojovací řetězec

Vytvořte novou instanci třídy CosmosClient s COSMOS_CONNECTION_STRING proměnnou prostředí jako jediný parametr.

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    connectionString: Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING")!
);

Připojení s využitím platformy Microsoft Identity Platform

Pokud se chcete připojit k účtu ROZHRANÍ API for NoSQL pomocí platformy Microsoft Identity Platform a ID Microsoft Entra, použijte instanční objekt zabezpečení. Přesný typ objektu zabezpečení bude záviset na tom, kde hostujete kód aplikace. Následující tabulka slouží jako stručná referenční příručka.

Kde aplikace běží	Objekt zabezpečení
Místní počítač (vývoj a testování)	Identita uživatele nebo instanční objekt
Azure	Spravovaná identita
Servery nebo klienti mimo Azure	Instanční objekt

Import Azure.Identity

Balíček NuGet Azure.Identity obsahuje základní funkce ověřování, které se sdílí mezi všemi knihovnami sady Azure SDK.

Importujte balíček NuGet Azure.Identity pomocí dotnet add package příkazu.

dotnet add package Azure.Identity

Znovu sestavte projekt pomocí dotnet build příkazu.

dotnet build

V editoru kódu přidejte direktivy using pro Azure.Core obory názvů a Azure.Identity obory názvů.

using Azure.Core;
using Azure.Identity;

Vytvoření CosmosClient s výchozí implementací přihlašovacích údajů

Pokud testujete na místním počítači nebo vaše aplikace bude běžet na službách Azure s přímou podporou spravovaných identit, získejte token OAuth vytvořením DefaultAzureCredential instance.

V tomto příkladu jsme instanci uložili do proměnné typu TokenCredential , protože jde o obecnější typ, který je opakovaně použitelný napříč sadami SDK.

// Credential class for testing on a local machine or Azure services
TokenCredential credential = new DefaultAzureCredential();

Vytvořte novou instanci třídy CosmosClient s COSMOS_ENDPOINT proměnnou prostředí a tokenCredential objekt jako parametry.

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    tokenCredential: credential
);

Vytvoření CosmosClient s vlastní implementací přihlašovacích údajů

Pokud plánujete nasadit aplikaci z Azure, můžete token OAuth získat pomocí jiných tříd v klientské knihovně Azure.Identity pro .NET. Tyto další třídy jsou také odvozeny z TokenCredential třídy.

V tomto příkladu ClientSecretCredential vytvoříme instanci pomocí identifikátorů klienta a tenanta spolu s tajným klíčem klienta.

// Custom credential class for servers and clients outside of Azure
TokenCredential credential = new ClientSecretCredential(
    tenantId: Environment.GetEnvironmentVariable("AAD_TENANT_ID")!,
    clientId: Environment.GetEnvironmentVariable("AAD_CLIENT_ID")!,
    clientSecret: Environment.GetEnvironmentVariable("AAD_CLIENT_SECRET")!,
    options: new TokenCredentialOptions()
);

ID klienta, ID tenanta a tajný klíč klienta můžete získat při registraci aplikace v Microsoft Entra ID. Další informace o registraci aplikací Microsoft Entra naleznete v tématu Registrace aplikace na platformě Microsoft Identity Platform.

Vytvořte novou instanci třídy CosmosClient s COSMOS_ENDPOINT proměnnou prostředí a tokenCredential objekt jako parametry.

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    tokenCredential: credential
);

Sestavení aplikace

Při vytváření aplikace bude váš kód primárně pracovat se čtyřmi typy prostředků:

• Účet ROZHRANÍ API pro NoSQL, což je jedinečný obor názvů nejvyšší úrovně pro vaše data Azure Cosmos DB.

• Databáze, které uspořádají kontejnery ve vašem účtu.

• Kontejnery, které obsahují sadu jednotlivých položek v databázi.

• Položky, které představují dokument JSON ve vašem kontejneru.

Na následujícím diagramu jsou vztahy těchto prostředků.

Hierarchický diagram znázorňující účet služby Azure Cosmos DB v horní části Účet má dva podřízené databázové uzly. Jeden z databázových uzlů zahrnuje dva podřízené uzly kontejneru. Druhý databázový uzel obsahuje jeden podřízený uzel kontejneru. Tento jeden uzel kontejneru má tři podřízené uzly položek.

Každý typ prostředku je reprezentován jednou nebo více přidruženými třídami .NET. Tady je seznam nejběžnějších tříd:

Třída	Popis
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ů na službu.
Database	Tato třída je odkazem na databázi, která může nebo nemusí existovat ve službě ještě. Databáze je ověřena na straně serveru, když se pokusíte o přístup k databázi nebo provedete operaci s ní.
Container	Tato třída je odkazem na kontejner, který ještě nemusí ve službě existovat. Kontejner se ověří na straně serveru, když se s ním pokusíte pracovat.

Následující příručky vám ukážou, jak pomocí každé z těchto tříd sestavit aplikaci.

Průvodce	Popis
Vytvoření databáze	Vytvoření databází
Vytvoření kontejneru	Vytváření kontejnerů
Čtení položky	Načtení konkrétní položky
Dotazování položek	Dotazování na více položek

Viz také

• Balíček (NuGet)
• Ukázky
• Referenční materiály k rozhraní API
• Zdrojový kód knihovny
• Váš názor

Další kroky

Teď, když jste se připojili k účtu ROZHRANÍ API pro NoSQL, použijte další příručku k vytváření a správě databází.

Vytvoření databáze ve službě Azure Cosmos DB for NoSQL pomocí .NET