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).

API untuk dokumentasi | referensi Tabel Azure.Data.Tables Package (NuGet)

Prasyarat

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.

1. Buka terminal di direktori akar proyek.

2. 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
   

3. Gunakan azd init untuk menginisialisasi proyek.

   azd init
   

4. 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.

5. Sebarkan akun Azure Cosmos DB menggunakan azd up. Templat Bicep juga menyebarkan aplikasi web sampel.

   azd up
   

6. Selama proses provisi, pilih langganan dan lokasi yang Anda inginkan. Tunggu hingga proses provisi selesai. Prosesnya dapat memakan waktu sekitar lima menit.

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

8. 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.

1. Buka terminal dan navigasi ke /src/web folder .

   cd ./src/web
   

2. Jika belum diinstal, instal Azure.Data.Tables paket menggunakan dotnet add package.

   dotnet add package Azure.Data.Tables
   

3. Selain itu Azure.Identity , instal paket jika belum diinstal.

   dotnet add package Azure.Identity
   

4. Buka dan tinjau file src/web/Cosmos.Samples.Table.Quickstart.Web.csproj untuk memvalidasi bahwa Microsoft.Azure.Cosmos entri dan Azure.Identity keduanya ada.

Contoh kode

• Autentikasi klien
• Buat tabel
• Membuat item
• Mendapatkan item
• Item kueri

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 TableEntity.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.

// 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.

az group delete --name $resourceGroupName

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters

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.