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
Hozzon létre egy rendszerhéjváltozót a resourceGroupName számára.
# Variable for resource group name resourceGroupName="msdocs-cosmos-dotnet-howto-rg"
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 )
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"
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"
Jegyezze fel az URI és AZ ELSŐDLEGES KULCS értékeit. Ezeket a hitelesítő adatokat később 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.
$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env: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
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 )
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"
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.
$env: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
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.