快速入門:搭配適用於 .NET 的 Azure SDK 使用適用於數據表的 Azure Cosmos DB
在本快速入門中,您會使用適用於 .NET 的 Azure SDK 來部署適用於數據表的基本 Azure Cosmos DB 應用程式。 Azure Cosmos DB for Table 是無架構的數據存放區,可讓應用程式將結構化數據表數據儲存在雲端中。 您將瞭解如何使用適用於 .NET 的 Azure SDK,在 Azure Cosmos DB 資源內建立數據表、數據列及執行基本工作。
API 參考文件 | 程式庫原始程式碼 | 套件 (NuGet) | Azure Developer CLI
必要條件
- Azure Developer CLI
- Docker Desktop
- .NET 9.0
如果您沒有 Azure 帳戶,請在您開始之前先建立 免費帳戶。
初始化專案
使用 Azure 開發人員 CLI (azd
) 建立適用於資料表帳戶的 Azure Cosmos DB,並部署容器化範例應用程式。 應用程式範例使用用戶端程式庫管理、建立、讀取和查詢樣本資料。
在空的目錄中開啟終端機。
如果您尚未通過驗證,請使用
azd auth login
向 Azure 開發人員 CLI 進行驗證。 依照工具指定的步驟,使用您慣用的 Azure 認證向 CLI 進行驗證。azd auth login
使用
azd init
來初始化專案。azd init --template cosmos-db-table-dotnet-quickstart
在初始化期間,請設定唯一的環境名稱。
使用
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 以 Azure.Data.Tables
套件形式提供。
開啟終端機,然後導覽至
/src/web
資料夾。cd ./src/web
如果尚未安裝,則請使用
dotnet add package
來安裝Azure.Data.Tables
套件。dotnet add package Azure.Data.Tables
開啟並檢閱 src/web/Microsoft.Samples.Cosmos.Table.Quickstart.Web.csproj 檔案,以驗證
Azure.Data.Tables
專案是否存在。
物件模型
名稱 | 描述 |
---|---|
TableServiceClient | 此類別是主要用戶端類別,並且用來管理全帳戶中繼資料或資料庫。 |
TableClient | 這個類別代表帳戶內數據表的用戶端。 |
程式碼範例
範本中的範例程式代碼會使用名為 的 cosmicworks-products
數據表。 數據表 cosmicworks-products
包含詳細數據,例如名稱、類別、數量、價格、唯一標識碼,以及每個產品的銷售旗標。 容器會使用唯一 標識碼 作為數據列索引鍵,而 類別 目錄作為分割區索引鍵。
驗證用戶端
此範例會建立 類別的新實例 TableServiceClient
。
DefaultAzureCredential credential = new();
TableServiceClient serviceClient = new(
endpoint: new Uri("<azure-cosmos-db-table-account-endpoint>"),
credential
);
取得數據表
此範例會使用 GetTableClient
類別的 TableClient
方法,建立 類別的TableServiceClient
實例。
TableClient client = serviceClient.GetTableClient(
tableName: "<azure-cosmos-db-table-name>"
);
建立實體
在數據表中建立新實體最簡單的方式,就是建立實作 介面的 ITableEntity
類別。 接著,您可以將自己的屬性新增至 類別,以填入該資料表資料列中的資料行。
public record Product : ITableEntity
{
public required string RowKey { get; set; }
public required string PartitionKey { get; set; }
public required string Name { get; set; }
public required int Quantity { get; set; }
public required decimal Price { get; set; }
public required bool Clearance { get; set; }
public ETag ETag { get; set; } = ETag.All;
public DateTimeOffset? Timestamp { get; set; }
};
藉由呼叫 TableClient.AddEntityAsync<T>
,Product
在數據表中建立實體。
Product entity = new()
{
RowKey = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
PartitionKey = "gear-surf-surfboards",
Name = "Surfboard",
Quantity = 10,
Price = 300.00m,
Clearance = true
};
Response response = await client.UpsertEntityAsync<Product>(
entity: entity,
mode: TableUpdateMode.Replace
);
取得實體
您可以使用 方法,從數據表 TableClient.GetEntityAsync<T>
擷取特定實體。 partitionKey
提供 和 rowKey
作為參數,以識別正確的數據列,以執行該實體的快速讀取點。
Response<Product> response = await client.GetEntityAsync<Product>(
rowKey: "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
partitionKey: "gear-surf-surfboards"
);
查詢實體
插入實體之後,您也可以執行查詢,以使用 TableClient.Query<T>
方法來取得符合特定篩選的所有實體。 此範例會使用 Language Integrated Query (LINQ) 語法依類別篩選產品,這是使用類似 Product
類別的具型ITableEntity
別模型的優點。
string category = "gear-surf-surfboards";
AsyncPageable<Product> results = client.QueryAsync<Product>(
product => product.PartitionKey == category
);
使用異步迴圈迴圈逐一查看結果的每個頁面,以剖析查詢的分頁結果。
List<Product> entities = new();
await foreach (Product product in results)
{
entities.Add(product);
}
清除資源
當您不再需要範例應用程式或資源時,請移除對應的部署和所有資源。
azd down