共用方式為


快速入門:適用於 .NET 的 Azure Cosmos DB 數據表連結庫

適用於: 資料表

此快速入門說明如何從 .NET 應用程式開始使用 Azure Cosmos DB for Table。 Azure Cosmos DB for Table 是無結構描述資料存放區,可讓應用程式將結構化的資料表資料儲存在雲端中。 您將瞭解如何使用適用於 .NET 的 Azure SDK,在 Azure Cosmos DB 資源內建立數據表、數據列及執行基本工作

API 參考文件 | 程式庫原始程式碼 | 套件 (NuGet) | Azure Developer CLI

必要條件

初始化專案

使用 Azure 開發人員 CLI (azd) 建立適用於資料表帳戶的 Azure Cosmos DB,並部署容器化範例應用程式。 應用程式範例使用用戶端程式庫管理、建立、讀取和查詢樣本資料。

  1. 在空的目錄中開啟終端機。

  2. 如果您尚未通過驗證,請使用 azd auth login向 Azure 開發人員 CLI 進行驗證。 依照工具指定的步驟,使用您慣用的 Azure 認證向 CLI 進行驗證。

    azd auth login
    
  3. 使用 azd init 來初始化專案。

    azd init --template cosmos-db-table-dotnet-quickstart
    
  4. 在初始化期間,請設定唯一的環境名稱。

  5. 使用 azd up 部署 Azure Cosmos DB 帳戶。 Bicep 範本也會部署範例 Web 應用程式。

    azd up
    
  6. 在布建程式期間,選取您的訂用帳戶、所需的位置和目標資源群組。 等候佈建程序完成。 此流程「大約需要五分鐘」的時間。

  7. 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.
    
  8. 請使用主控台中的 URL,以在瀏覽器中導覽至您的 Web 應用程式。 觀察執行中應用程式的輸出。

    螢幕擷取畫面,其中顯示執行中的 Web 應用程式。

安裝用戶端程式庫

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

  1. 開啟終端機,然後導覽至 /src/web 資料夾。

    cd ./src/web
    
  2. 如果尚未安裝,則請使用 dotnet add package 來安裝 Azure.Data.Tables 套件。

    dotnet add package Azure.Data.Tables
    
  3. 開啟並檢閱 src/web/Microsoft.Samples.Cosmos.Table.Quickstart.Web.csproj 檔案,以驗證 Azure.Data.Tables 專案是否存在。

物件模型

名稱 描述
TableServiceClient 此類別是主要用戶端類別,並且用來管理全帳戶中繼資料或資料庫。
TableClient 這個類別代表帳戶內數據表的用戶端。

程式碼範例

範本中的範例程式代碼會使用名為 的 cosmicworks-products數據表。 數據表 cosmicworks-products 包含詳細數據,例如名稱、類別、數量、價格、唯一標識碼,以及每個產品的銷售旗標。 容器會使用唯一 標識符* 作為數據列索引鍵,而 類別目錄 則作為分割區索引鍵。

驗證用戶端

此範例會建立 類別的新實例 TableServiceClient

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 string RowKey { get; set; } = $"{Guid.NewGuid()}";

    public string PartitionKey { get; set; } = String.Empty;

    public string Name { get; set; } = String.Empty;

    public int Quantity { get; set; } = 0;

    public decimal Price { get; set; } = 0.0m;

    public bool Clearance { get; set; } = false;

    public ETag ETag { get; set; } = ETag.All;

    public DateTimeOffset? Timestamp { get; set; }
};

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

Product entity = new()
{
    RowKey = "68719518391",
    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> 方法,從資料表擷取特定項目。 提供用來識別正確資料列的 partitionKeyrowKey 作為參數,以執行該項目的快速點讀取

Response<Product> response = await client.GetEntityAsync<Product>(
    rowKey: "68719518391",
    partitionKey: "gear-surf-surfboards"
);

查詢項目

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

注意

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

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