快速入門：適用於 .NET 的 Azure Cosmos DB for Table

發行項
04/04/2024

適用於： Table

此快速入門說明如何從 .NET 應用程式開始使用 Azure Cosmos DB for Table。適用於資料表的 Azure Cosmos DB 是無架構的數據存放區，可讓應用程式將結構化數據表資料儲存在雲端中。您將了解如何使用 Azure.Data.Tables 套件 (NuGet) (英文)，在 Azure Cosmos DB 資源內建立資料表和資料列及執行基本工作。

注意

範例程式碼片段可在 GitHub 作為 .NET 專案使用。

API for Table 參考文件 (英文) | Azure.Data.Tables 套件 (NuGet) (英文)

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
GitHub 帳戶

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
Azure Developer CLI
Docker Desktop

設定

將這個專案的開發容器部署到您的環境。然後，使用 Azure 開發人員 CLI （azd）建立適用於資料表帳戶的 Azure Cosmos DB，並部署容器化範例應用程式。應用程式範例使用用戶端程式庫管理、建立、讀取和查詢樣本資料。

重要

GitHub 帳戶的免費權利包括儲存體和核心時數。如需詳細資訊，請參閱 GitHub 帳戶包含的儲存體和核心時數。

在專案的根目錄中開啟終端。
使用 azd auth login 以向 Azure Developer CLI 進行驗證。依照工具指定的步驟，使用您慣用的 Azure 認證向 CLI 進行驗證。
```
azd auth login
```
使用 azd init 來初始化專案。
```
azd init
```
在初始化期間，請設定唯一的環境名稱。

提示

環境名稱也將是目標資源群組名稱。在這個快速入門中，請考慮使用 msdocs-cosmos-db。
使用 azd up部署 Azure Cosmos DB 帳戶。 Bicep 範本也會部署範例 Web 應用程式。
```
azd up
```
在佈建流程期間，請選取您的訂用帳戶和所需位置。等候佈建程序完成。此流程「大約需要五分鐘」的時間。

Azure 資源佈建完成後，輸出將包含正在執行的 Web 應用程式的 URL。

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.

請使用主控台中的 URL，以在瀏覽器中導覽至您的 Web 應用程式。觀察執行中應用程式的輸出。

安裝用戶端程式庫

用戶端程式庫可透過 NuGet 以 Microsoft.Azure.Cosmos 套件形式提供。

開啟終端機，然後導覽至 /src/web 資料夾。
```
cd ./src/web
```
如果尚未安裝，則請使用 dotnet add package 來安裝 Azure.Data.Tables 套件。
```
dotnet add package Azure.Data.Tables
```
也請安裝 Azure.Identity 套件 (如果尚未安裝)。
```
dotnet add package Azure.Identity
```
開啟並檢閱 src/web/Cosmos.Samples.Table.Quickstart.Web.csproj 檔案，以驗證 Microsoft.Azure.Cosmos 和 Azure.Identity 專案都存在。

本文所述的範例程式碼會建立名為 adventureworks 的資料表。每個資料表資料列都包含產品的詳細資料，例如名稱、類別、數量和銷售指標。每個產品也都包含唯一識別碼。

您將使用下列 API for Table 類別與這些資源互動：

TableServiceClient：此類別提供使用 Azure Cosmos DB for Table 執行服務層級作業的方法。
TableClient - 此類別可讓您與 Azure Cosmos DB 資料表 API 中裝載的資料表進行互動。
TableEntity - 此類別是資料表中資料列的參考，可讓您管理屬性和資料行資料。

驗證用戶端

從專案目錄開啟 Program.cs 檔案。在編輯器中，為 Azure.Data.Tables 新增 using 指示詞。

using Azure.Data.Tables;

使用建構函式定義 TableServiceClient 類別的新執行個體，並且定義 Environment.GetEnvironmentVariable 以讀取您先前設定的連接字串。

// New instance of the TableClient class
TableServiceClient tableServiceClient = new TableServiceClient(Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING"));

建立表格

使用 TableServiceClient 類別擷取 TableClient 的執行個體。如果資料表尚不存在，請使用 TableClient 上的 TableClient.CreateIfNotExistsAsync 方法建立新的資料表。這個方法將會傳回現有或新建立資料表的參考。

// New instance of TableClient class referencing the server-side table
TableClient tableClient = tableServiceClient.GetTableClient(
    tableName: "adventureworks"
);

await tableClient.CreateIfNotExistsAsync();

建立項目

在資料表中建立新項目最簡單的方式，就是建立實作 ITableEntity 介面的類別。接著，您可以將自己的屬性新增至類別，以填入該資料表資料列中的資料行。

// 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!;
}

藉由呼叫 TableClient.AddEntityAsync<T> 並使用 Product 類別在集合中建立項目。

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

取得項目

您可以使用 TableEntity.GetEntityAsync<T> 方法，從資料表擷取特定項目。提供用來識別正確資料列的 partitionKey 和 rowKey 作為參數，以執行該項目的快速點讀取。

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

查詢項目

插入項目之後，您也可以使用 TableClient.Query<T> 方法，執行查詢來取得符合特定篩選的所有項目。此範例會使用 Linq 語法依類別篩選產品，這是使用類似 Product 類別的 ITableEntity 型別模型的優點。

注意

您也可以使用 OData 語法查詢項目。您可以在查詢資料教學課程中看到此方法的範例。

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

執行程式碼

此應用程式會建立 Azure Cosmos DB 資料表 API 資料表。然後，此範例會建立項目，然後重新讀取完全相同的項目。最後，此範例會建立第二個項目，然後執行應傳回多個項目的查詢。在每個步驟中，範例會將中繼資料輸出至主控台，包含其執行的步驟。

若要執行應用程式，請使用終端機瀏覽至應用程式目錄並執行應用程式。

dotnet run

此命令的輸出應類似此範例：

Single product name: 
Yamba Surfboard
Multiple products:
Yamba Surfboard
Sand Surfboard

清除資源

當您不再需要 Azure Cosmos DB for Table 帳戶時，可以刪除對應的資源群組。

使用 az group delete 命令以刪除資源群組。

az group delete --name $resourceGroupName

使用 Remove-AzResourceGroup Cmdlet 以刪除資源群組。

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

下一步

在此快速入門中，您已了解如何使用 .NET SDK 建立 Azure Cosmos DB for Table 帳戶、建立資料表以及管理項目。您現在可以深入探索 SDK，以了解如何在 Azure Cosmos DB for Table 資源中執行更進階的資料查詢和管理工作。

開始使用 Azure Cosmos DB for Table 和 .NET