Mulai cepat: Azure Cosmos DB untuk Tabel untuk .NET
BERLAKU UNTUK: Meja
Mulai cepat ini menunjukkan cara memulai Azure Cosmos DB for Table dari aplikasi .NET. Azure Cosmos DB for Table adalah penyimpanan data tanpa skema yang memungkinkan aplikasi menyimpan data tabel terstruktur di cloud. Anda akan mempelajari cara membuat tabel, baris, dan melakukan tugas dasar dalam sumber daya Azure Cosmos DB Anda menggunakan Paket Azure.Data.Tables (NuGet).
Catatan
Contoh cuplikan kode tersedia di GitHub sebagai proyek .NET.
API untuk dokumentasi | referensi Tabel Azure.Data.Tables Package (NuGet)
Prasyarat
- Akun Azure dengan langganan aktif. Buat akun secara gratis.
- Akun GitHub
- Akun Azure dengan langganan aktif. Buat akun secara gratis.
- Azure Developer CLI
- Desktop Docker
Menyiapkan
Sebarkan kontainer pengembangan proyek ini ke lingkungan Anda. Kemudian, gunakan Azure Developer CLI (azd) untuk membuat akun Azure Cosmos DB for Table dan menyebarkan aplikasi sampel dalam kontainer. Aplikasi sampel menggunakan pustaka klien untuk mengelola, membuat, membaca, dan mengkueri data sampel.
Penting
Akun GitHub mencakup pemberian izin penyimpanan dan jam inti tanpa biaya. Untuk informasi selengkapnya, lihat penyimpanan dan jam inti yang disertakan untuk akun GitHub.
Buka terminal di direktori akar proyek.
Autentikasi ke Azure Developer CLI menggunakan
azd auth login
. Ikuti langkah-langkah yang ditentukan oleh alat untuk mengautentikasi ke CLI menggunakan kredensial Azure pilihan Anda.azd auth login
Gunakan
azd init
untuk menginisialisasi proyek.azd init
Selama inisialisasi, konfigurasikan nama lingkungan yang unik.
Tip
Nama lingkungan juga akan digunakan sebagai nama grup sumber daya target. Untuk mulai cepat ini, pertimbangkan untuk menggunakan
msdocs-cosmos-db
.Sebarkan akun Azure Cosmos DB menggunakan
azd up
. Templat Bicep juga menyebarkan aplikasi web sampel.azd up
Selama proses provisi, pilih langganan dan lokasi yang Anda inginkan. Tunggu hingga proses provisi selesai. Prosesnya dapat memakan waktu sekitar lima menit.
Setelah provisi sumber daya Azure Anda selesai, URL ke aplikasi web yang sedang berjalan disertakan dalam output.
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.
Gunakan URL di konsol untuk menavigasi ke aplikasi web Anda di browser. Amati output aplikasi yang sedang berjalan.
Memasang pustaka klien
Pustaka klien tersedia melalui NuGet, sebagai Microsoft.Azure.Cosmos
paket.
Buka terminal dan navigasi ke
/src/web
folder .cd ./src/web
Jika belum diinstal, instal
Azure.Data.Tables
paket menggunakandotnet add package
.dotnet add package Azure.Data.Tables
Selain itu
Azure.Identity
, instal paket jika belum diinstal.dotnet add package Azure.Identity
Buka dan tinjau file src/web/Cosmos.Samples.Table.Quickstart.Web.csproj untuk memvalidasi bahwa
Microsoft.Azure.Cosmos
entri danAzure.Identity
keduanya ada.
Contoh kode
Kode sampel yang dijelaskan dalam artikel ini membuat tabel bernama adventureworks
. Setiap baris tabel berisi detail produk seperti nama, kategori, kuantitas, dan indikator penjualan. Setiap produk juga berisi pengidentifikasi unik.
Anda akan menggunakan API berikut untuk kelas Table untuk berinteraksi dengan sumber daya ini:
TableServiceClient
- Kelas ini menyediakan metode untuk melakukan operasi tingkat layanan dengan Azure Cosmos DB for Table.TableClient
- Kelas ini memungkinkan Anda berinteraksi dengan tabel yang dihosting di API tabel Azure Cosmos DB.TableEntity
- Kelas ini adalah referensi ke baris dalam tabel yang memungkinkan Anda mengelola properti dan data kolom.
Mengautentikasi klien
Dari direktori proyek, buka file Program.cs. Di editor Anda, tambahkan arahan penggunaan untuk Azure.Data.Tables
.
using Azure.Data.Tables;
Tentukan instans baru kelas TableServiceClient
menggunakan konstruktor dan Environment.GetEnvironmentVariable
untuk membaca string koneksi yang Anda tentukan sebelumnya.
// New instance of the TableClient class
TableServiceClient tableServiceClient = new TableServiceClient(Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING"));
Buat tabel
Ambil instans TableClient
menggunakan kelas TableServiceClient
. Gunakan metode TableClient.CreateIfNotExistsAsync
pada TableClient
untuk membuat tabel baru jika belum ada. Metode ini akan mengembalikan referensi ke database yang sudah ada atau yang baru dibuat.
// New instance of TableClient class referencing the server-side table
TableClient tableClient = tableServiceClient.GetTableClient(
tableName: "adventureworks"
);
await tableClient.CreateIfNotExistsAsync();
Membuat item
Cara termudah untuk membuat item baru dalam tabel adalah dengan membuat kelas yang mengimplementasikan antarmuka ITableEntity
. Anda kemudian dapat menambahkan properti Anda sendiri ke kelas untuk mengisi kolom data di baris tabel tersebut.
// C# record type for items in the table
public record Product : ITableEntity
{
public string RowKey { get; set; } = default!;
public string PartitionKey { get; set; } = default!;
public string Name { get; init; } = default!;
public int Quantity { get; init; }
public bool Sale { get; init; }
public ETag ETag { get; set; } = default!;
public DateTimeOffset? Timestamp { get; set; } = default!;
}
Buat item dalam koleksi menggunakan kelas Product
dengan memanggil TableClient.AddEntityAsync<T>
.
// Create new item using composite key constructor
var prod1 = new Product()
{
RowKey = "68719518388",
PartitionKey = "gear-surf-surfboards",
Name = "Ocean Surfboard",
Quantity = 8,
Sale = true
};
// Add new item to server-side table
await tableClient.AddEntityAsync<Product>(prod1);
Mendapatkan item
Anda dapat mengambil item tertentu dari tabel menggunakan metode TableClient.GetEntityAsync<T>
. Berikan partitionKey
dan rowKey
sebagai parameter untuk mengidentifikasi baris yang benar guna melakukan pembacaan titik cepat dari item tersebut.
// Read a single item from container
var product = await tableClient.GetEntityAsync<Product>(
rowKey: "68719518388",
partitionKey: "gear-surf-surfboards"
);
Console.WriteLine("Single product:");
Console.WriteLine(product.Value.Name);
Buat kueri item
Setelah menyisipkan item, Anda bisa menjalankan kueri untuk mendapatkan semua item yang cocok dengan filter tertentu dengan menggunakan metode TableClient.Query<T>
. Contoh ini memfilter produk menurut kategori menggunakan sintaks Linq, yaitu manfaat penggunaan model ITableEntity
yang spesifik seperti kelas Product
.
Catatan
Anda juga bisa mengkueri item menggunakan sintaks OData . Anda dapat melihat contoh pendekatan ini dalam tutorial Data Kueri .
// Read multiple items from container
var prod2 = new Product()
{
RowKey = "68719518390",
PartitionKey = "gear-surf-surfboards",
Name = "Sand Surfboard",
Quantity = 5,
Sale = false
};
await tableClient.AddEntityAsync<Product>(prod2);
var products = tableClient.Query<Product>(x => x.PartitionKey == "gear-surf-surfboards");
Console.WriteLine("Multiple products:");
foreach (var item in products)
{
Console.WriteLine(item.Name);
}
Menjalankan kode
Aplikasi ini membuat tabel Azure Cosmos DB Table API. Contohnya kemudian membuat item lalu membaca kembali item yang sama persis. Terakhir, contoh membuat item kedua lalu melakukan kueri yang harus mengembalikan beberapa item. Dengan setiap langkah, contoh menghasilkan metadata ke konsol tentang langkah-langkah yang telah dilakukannya.
Untuk menjalankan aplikasi, gunakan terminal untuk menavigasi ke direktori aplikasi dan menjalankannya.
dotnet run
Output aplikasi harus mirip dengan contoh ini:
Single product name:
Yamba Surfboard
Multiple products:
Yamba Surfboard
Sand Surfboard
Membersihkan sumber daya
Saat Anda tidak lagi memerlukan akun Azure Cosmos DB for Table, Anda dapat menghapus grup sumber daya yang sesuai.
Untuk menghapus grup sumber daya tersebut, gunakan perintah az group delete
.
az group delete --name $resourceGroupName
Langkah berikutnya
Dalam mulai cepat ini, Anda mempelajari cara membuat akun Azure Cosmos DB for Table, membuat tabel, dan mengelola entri menggunakan .NET SDK. Anda sekarang dapat mendalami lebih dalam SDK untuk mempelajari cara melakukan kueri data dan tugas manajemen yang lebih canggih di sumber daya Azure Cosmos DB for Table Anda.