Mulai menggunakan Azure Cosmos DB untuk NoSQL menggunakan .NET
BERLAKU UNTUK: 
NoSQL
Artikel ini memperlihatkan kepada Anda cara menyambungkan ke Azure Cosmos DB for NoSQL menggunakan .NET SDK. Setelah tersambung, Anda dapat melakukan operasi pada database, kontainer, dan item.
Paket (NuGet) | Contoh | Referensi API | Kode sumber pustaka | Berikan Umpan Balik
Prasyarat
- Akun Azure dengan langganan aktif. Buat akun secara gratis.
- Akun Azure Cosmos DB for NoSQL. Buat API untuk akun NoSQL.
- .NET 6.0 atau yang lebih baru
- Azure Command-Line Interface (CLI) atau Azure PowerShell
Menyiapkan proyek Anda
Buat aplikasi .NET baru dengan menggunakan perintah dotnet new dengan templat konsol.
dotnet new console
Impor paket NuGet Microsoft.Azure.Cosmos menggunakan perintah dotnet add package.
dotnet add package Microsoft.Azure.Cosmos
Buat proyek dengan perintah dotnet build.
dotnet build
Menyambungkan ke Azure Cosmos DB for NoSQL
Untuk menyambungkan ke API untuk NoSQL Azure Cosmos DB, buat instans CosmosClient kelas . Kelas ini adalah titik awal untuk melakukan semua operasi terhadap database.
Untuk menyambungkan ke API Anda untuk akun NoSQL menggunakan Microsoft Entra, gunakan prinsip keamanan. Jenis prinsipal yang tepat akan bergantung pada tempat Anda menghosting kode aplikasi. Tabel di bawah ini berfungsi sebagai panduan referensi singkat.
| Tempat aplikasi berjalan | Prinsip keamanan |
|---|---|
| Komputer lokal (pengembangan dan pengujian) | Identitas pengguna atau perwakilan layanan |
| Azure | Identitas terkelola |
| Server atau klien di luar Azure | Perwakilan layanan |
Mengimpor Azure.Identity
Paket NuGet Azure.Identity berisi fungsionalitas autentikasi inti yang dibagikan di antara semua pustaka Azure SDK.
Impor paket NuGet Azure.Identity menggunakan perintah dotnet add package.
dotnet add package Azure.Identity
Bangun kembali proyek dengan perintah dotnet build.
dotnet build
Di editor kode Anda, tambahkan namespace Azure.Core dan Azure.Identity menggunakan arahan.
using Azure.Core;
using Azure.Identity;
Membuat CosmosClient dengan implementasi kredensial default
Jika Anda melakukan pengujian pada mesin lokal, atau aplikasi Anda akan berjalan di layanan Azure dengan dukungan langsung untuk identitas terkelola, dapatkan token OAuth dengan membuat instans DefaultAzureCredential.
Untuk contoh ini, kami menyimpan instans dalam variabel jenis TokenCredential karena itu adalah jenis yang lebih umum yang dapat digunakan kembali di seluruh SDK.
// Credential class for testing on a local machine or Azure services
TokenCredential credential = new DefaultAzureCredential();
Buat instans baru kelas CosmosClient dengan variabel lingkungan COSMOS_ENDPOINT dan objek TokenCredential sebagai parameter.
// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
tokenCredential: credential
);
Bangun aplikasi Anda
Saat Anda membangun aplikasi, kode Anda utamanya akan berinteraksi dengan empat jenis sumber daya:
API untuk akun NoSQL, yang merupakan namespace layanan tingkat atas unik untuk data Azure Cosmos DB Anda.
Database, yang mengatur kontainer di akun Anda.
Kontainer, yang berisi sekumpulan item individual dalam database Anda.
Item, yang mewakili dokumen JSON dalam kontainer Anda.
Diagram berikut menunjukkan hubungan antara ketiga sumber daya ini.
Diagram hierarki memperlihatkan akun Azure Cosmos DB di bagian atas. Akun ini memiliki dua node database turunan. Salah satu node database tersebut memiliki dua node kontainer turunan. Sedangkan, node database lainnya hanya memiliki satu node kontainer turunan. Satu node kontainer tersebut memiliki tiga node item turunan.
Setiap jenis sumber daya diwakili oleh satu atau lebih kelas .NET terkait. Berikut adalah daftar kelas yang paling umum:
| Kelas | Deskripsi |
|---|---|
CosmosClient |
Kelas ini menyediakan representasi logis sisi klien untuk layanan Azure Cosmos DB. Klien ini digunakan untuk mengonfigurasi dan menjalankan permintaan terhadap layanan. |
Database |
Kelas ini adalah referensi ke database yang mungkin sudah ada, atau mungkin belum ada dalam layanan. Database divalidasi di sisi server saat Anda mencoba mengaksesnya atau melakukan operasi terhadapnya. |
Container |
Kelas ini adalah referensi ke kontainer yang juga mungkin belum ada dalam layanan. Kontainer divalidasi di sisi server ketika Anda mencoba untuk menggunakannya. |
Panduan berikut menunjukkan cara menggunakan masing-masing kelas ini untuk membangun aplikasi Anda.
| Panduan | Deskripsi |
|---|---|
| Membuat database | Membuat database |
| Membuat kontainer | Membuat kontainer |
| Membaca item | Membaca poin item tertentu |
| Item kueri | Mengkueri beberapa item |