Az Azure Cosmos DB for NoSQL használatának első lépései a .NET használatával

A KÖVETKEZŐRE VONATKOZIK: NoSQL

Ez a cikk bemutatja, hogyan csatlakozhat az Azure Cosmos DB for NoSQL-hez a .NET SDK használatával. A csatlakozás után műveleteket hajthat végre adatbázisokon, tárolókon és elemeken.

Package (NuGet) | Samples | API reference | Library source code | Give Feedback

Előfeltételek

• Egy Azure-fiók, aktív előfizetéssel. Fiók ingyenes létrehozása.
• Azure Cosmos DB for NoSQL-fiók. Hozzon létre egy API-t a NoSQL-fiókhoz.
• .NET 6.0 vagy újabb
• Azure Parancssori felület (CLI) vagy Azure PowerShell

A projekt beállítása

A .NET-konzolalkalmazás létrehozása

Hozzon létre egy új .NET-alkalmazást a dotnet new konzolsablon parancsával.

dotnet new console

Importálja a Microsoft.Azure.Cosmos NuGet-csomagot a dotnet add package paranccsal.

dotnet add package Microsoft.Azure.Cosmos

Hozza létre a projektet a dotnet build paranccsal.

dotnet build

Csatlakozás az Azure Cosmos DB for NoSQL-be

Az Azure Cosmos DB NoSQL-hez készült API-hoz való csatlakozáshoz hozza létre az osztály egy példányát CosmosClient . Ez az osztály a kiindulópont az adatbázisokon végzett összes művelet végrehajtásához. A CosmosClient osztály használatával három alapvető módon csatlakozhat egy Api for NoSQL-fiókhoz:

• Csatlakozás api for NoSQL-végponttal és olvasási/írási kulccsal
• Csatlakozás a NoSQL-hez készült API-val kapcsolati sztring
• Csatlakozás Microsoft Entra-azonosítóval

Csatlakozás végponttal és kulccsal

A CosmosClient leggyakoribb konstruktorának két paramétere van:

Parameter	Példaérték	Leírás
accountEndpoint	COSMOS_ENDPOINT környezeti változó	Az API for NoSQL-végpont az összes kéréshez használható
authKeyOrResourceToken	COSMOS_KEY környezeti változó	A hitelesítéshez használandó fiókkulcs vagy erőforrás-jogkivonat

Fiókvégpont és kulcs lekérése

Azure CLI

1. Hozzon létre egy rendszerhéjváltozót a resourceGroupName számára.

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

2. az cosmosdb list A paranccsal lekérheti az erőforráscsoport első Azure Cosmos DB-fiókjának nevét, és tárolhatja az accountName rendszerhéj változójában.

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

3. Kérje le a noSQL-végpont URI API-jának lekérését a fiókhoz a az cosmosdb show paranccsal.

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

4. Keresse meg az ELSŐDLEGES KULCSOT a parancsot tartalmazó az-cosmosdb-keys-list fiók kulcsainak listájából.

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

5. Jegyezze fel az URI és AZ ELSŐDLEGES KULCS értékeit. Ezeket a hitelesítő adatokat később fogja használni.

PowerShell

1. Hozzon létre egy rendszerhéjváltozót RESOURCE_GROUP_NAME.

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

2. Get-AzCosmosDBAccount A parancsmaggal lekérheti az első Azure Cosmos DB-fiók nevét az erőforráscsoportban, és tárolhatja a ACCOUNT_NAME rendszerhéj változójában.

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

3. Szerezze be a fiókhoz tartozó NoSQL-végpont URI API-t a Get-AzCosmosDBAccount parancsmag használatával.

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

4. Keresse meg az ELSŐDLEGES KULCSOT a parancsmaggal rendelkező Get-AzCosmosDBAccountKey fiók kulcsainak listájából.

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

5. Jegyezze fel az URI és AZ ELSŐDLEGES KULCS értékeit. Ezeket a hitelesítő adatokat később fogja használni.

Portál

Tipp.

Ebben az útmutatóban az erőforráscsoport nevének msdocs-cosmos-dotnet-howto-rghasználatát javasoljuk.

1. Jelentkezzen be az Azure Portalra.

2. Lépjen a meglévő Azure Cosmos DB for NoSQL-fiók lapjára.

3. Az Azure Cosmos DB for NoSQL-fiók lapján válassza a Kulcsok navigációs menüt.

   

4. Jegyezze fel az URI és az ELSŐDLEGES KULCS mezők értékeit. Ezeket az értékeket egy későbbi lépésben fogja használni.

   

A .NET-kód URI- és ELSŐDLEGESKULCS-értékeinek használatához őrizze meg őket az alkalmazást futtató helyi gépen lévő új környezeti változókhoz.

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>"

CosmosClient létrehozása fiókvégponttal és kulccsal

Hozzon létre egy új CosmosClient-példányt paraméterekként a környezeti és COSMOS_KEY a COSMOS_ENDPOINT környezeti változókkal.

// 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")!
);

Csatlakozás kapcsolati sztring

A CosmosClient egy másik konstruktora csak egyetlen paramétert tartalmaz:

Parameter	Példaérték	Leírás
accountEndpoint	COSMOS_ENDPOINT környezeti változó	Az API for NoSQL-végpont az összes kéréshez használható
connectionString	COSMOS_CONNECTION_STRING környezeti változó	Csatlakozás ion string to the API for NoSQL account

A fiók kapcsolati sztring lekérése

Azure CLI

1. az cosmosdb list A paranccsal lekérheti az erőforráscsoport első Azure Cosmos DB-fiókjának nevét, és tárolhatja az accountName rendszerhéj változójában.

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

2. Keresse meg az ELSŐDLEGES KAPCSOLAT SZTRINGet a parancsot tartalmazó az-cosmosdb-keys-list fiók kapcsolati sztring listájából.

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

PowerShell

1. Get-AzCosmosDBAccount A parancsmaggal lekérheti az első Azure Cosmos DB-fiók nevét az erőforráscsoportban, és tárolhatja a ACCOUNT_NAME rendszerhéj változójában.

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

2. Keresse meg az ELSŐDLEGES KAPCSOLAT SZTRINGet a parancsmaggal rendelkező Get-AzCosmosDBAccountKey fiók kapcsolati sztring listájából.

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

Portál

Tipp.

Ebben az útmutatóban az erőforráscsoport nevének msdocs-cosmos-dotnet-howto-rghasználatát javasoljuk.

1. Jelentkezzen be az Azure Portalra.

2. Lépjen a meglévő Azure Cosmos DB for NoSQL-fiók lapjára.

3. Az Azure Cosmos DB for NoSQL-fiók lapján válassza a Kulcsok navigációs menüt.

4. Jegyezze fel az ELSŐDLEGES KAPCSOLATI SZTRING mező értékét.

Az ELSŐDLEGES KAPCSOLATI SZTRING érték a .NET-kódban való használatához őrizze meg azt egy új környezeti változóban az alkalmazást futtató helyi gépen.

Windows

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

Linux/macOS

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

CosmosClient létrehozása kapcsolati sztring

Hozzon létre egy új CosmosClient-példányt, amelynek egyetlen paramétere a COSMOS_CONNECTION_STRING környezeti változó.

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

Csatlakozás a Microsoft Identitásplatform

Ha a Microsoft Identitásplatform és a Microsoft Entra ID használatával szeretne csatlakozni a NoSQL API-fiókjához, használjon egy biztonsági tagot. Az egyszerűség pontos típusa attól függ, hogy hol tárolja az alkalmazás kódját. Az alábbi táblázat rövid útmutatóként szolgál.

Az alkalmazás futtatásának helye	Rendszerbiztonsági tag
Helyi gép (fejlesztés és tesztelés)	Felhasználói identitás vagy szolgáltatásnév
Azure	Managed identity
Azure-on kívüli kiszolgálók vagy ügyfelek	Service principal

Az Azure.Identity importálása

Az Azure.Identity NuGet-csomag az összes Azure SDK-kódtár között megosztott alapvető hitelesítési funkciókat tartalmazza.

Importálja az Azure.Identity NuGet-csomagot a dotnet add package paranccsal.

dotnet add package Azure.Identity

Építse újra a projektet a dotnet build paranccsal.

dotnet build

A kódszerkesztőben adja hozzá a névterekre és Azure.Identity a névterekre vonatkozó Azure.Core irányelveket.

using Azure.Core;
using Azure.Identity;

CosmosClient létrehozása az alapértelmezett hitelesítő adatok implementálásával

Ha helyi gépen tesztel, vagy az alkalmazás a felügyelt identitások közvetlen támogatásával fog futni az Azure-szolgáltatásokban, szerezze be az OAuth-jogkivonatot egy DefaultAzureCredential példány létrehozásával.

Ebben a példában egy típusváltozóba TokenCredential mentettük a példányt, mivel ez egy általánosabb típus, amely az SDK-k között újra felhasználható.

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

Hozzon létre egy új CosmosClient-példányt a COSMOS_ENDPOINT környezeti változóval és a TokenCredential objektummal paraméterként.

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

CosmosClient létrehozása egyéni hitelesítő adatok implementálásával

Ha azt tervezi, hogy az alkalmazást az Azure-on kívül helyezi üzembe, oAuth-jogkivonatot szerezhet be az Azure.Identity ügyféloldali kódtára .NET-hez készült más osztályainak használatával. Ezek a többi osztály is az TokenCredential osztályból származik.

Ebben a példában egy példányt ClientSecretCredential hozunk létre ügyfél- és bérlőazonosítók, valamint egy titkos ügyfélkód használatával.

// 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()
);

Az alkalmazás Microsoft Entra-azonosítóban való regisztrálásakor beszerezheti az ügyfél-azonosítót, a bérlőazonosítót és az ügyfél titkos kódját. További információ a Microsoft Entra-alkalmazások regisztrálásáról: Alkalmazás regisztrálása a Microsoft Identitásplatform.

Hozzon létre egy új CosmosClient-példányt a COSMOS_ENDPOINT környezeti változóval és a TokenCredential objektummal paraméterként.

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

Az alkalmazás összeállítása

Az alkalmazás létrehozásakor a kód elsősorban négy erőforrástípussal fog működni:

• Az API for NoSQL-fiók, amely az Azure Cosmos DB-adatok egyedi legfelső szintű névtere.

• Adatbázisok, amelyek rendszerezik a tárolókat a fiókjában.

• Tárolók, amelyek az adatbázis egyes elemeit tartalmazzák.

• Elemek, amelyek egy JSON-dokumentumot jelölnek a tárolóban.

Az alábbi ábra az ezen erőforrások közötti kapcsolatot mutatja be.

Hierarchikus diagram egy Azure Cosmos DB-fiókot ábrázol felül. A fióknak két gyermekadatbázis-csomópontja van. Az adatbázis-csomópontok egyike két gyermektároló-csomópontot tartalmaz. A másik adatbáziscsomópont egyetlen gyermektároló-csomópontot tartalmaz. Az egyetlen tárolócsomópont három gyermekelem-csomópontból áll.

Minden erőforrástípust egy vagy több társított .NET-osztály jelöl. Íme a leggyakoribb osztályok listája:

Osztály	Leírás
CosmosClient	Ez az osztály ügyféloldali logikai reprezentációt biztosít az Azure Cosmos DB szolgáltatáshoz. Az ügyfélobjektum a szolgáltatással kapcsolatos kérések konfigurálására és végrehajtására szolgál.
Database	Ez az osztály egy olyan adatbázisra mutató hivatkozás, amely lehet, hogy még létezik a szolgáltatásban. Az adatbázis kiszolgálóoldali érvényesítve van, amikor megpróbálja elérni, vagy műveletet hajt végre rajta.
Container	Ez az osztály egy olyan tárolóra mutató hivatkozás, amely még nem létezik a szolgáltatásban. A tároló kiszolgálóoldali érvényesítve lesz, amikor megpróbál dolgozni vele.

Az alábbi útmutatók bemutatják, hogyan használhatja ezeket az osztályokat az alkalmazás létrehozásához.

Útmutató	Leírás
Adatbázis létrehozása	Adatbázisok létrehozására
Tároló létrehozása	Tárolók létrehozása
Elem olvasása	Adott elem pontolvasása
Lekérdezési elemek	Több elem lekérdezése

Kapcsolódó információk

• Csomag (NuGet)
• Példák
• API-referencia
• Kódtár forráskódja
• Visszajelzés küldése

Következő lépések

Most, hogy csatlakozott egy API for NoSQL-fiókhoz, használja a következő útmutatót az adatbázisok létrehozásához és kezeléséhez.

Adatbázis létrehozása az Azure Cosmos DB for NoSQL-ben a .NET használatával