快速入門:適用于 .NET 的 Azure Cosmos DB 資料表

適用於: Table

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

注意

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

資料表參考檔的 | APIAzure.Data.Tables 套件 (NuGet)

必要條件

先決條件檢查

  • 在終端機或命令視窗中執行 dotnet --list-sdks,確認 .NET 6.x 是其中一個可用版本。
  • 執行 az --version (Azure CLI) 或 Get-Module -ListAvailable AzureRM (Azure PowerShell),以確認您已安裝適當的 Azure 命令列工具。

設定

本節將逐步引導您建立 Azure Cosmos DB 帳戶,並設定使用資料表 NuGet 套件 API 的專案。

建立 Azure Cosmos DB 帳戶

本快速入門將使用適用于資料表的 API 建立單一 Azure Cosmos DB 帳戶。

  1. 建立 accountNameresourceGroupNamelocation 的殼層變數。

    # Variable for resource group name
    resourceGroupName="msdocs-cosmos-quickstart-rg"
    location="westus"
    
    # Variable for account name with a randomnly generated suffix
    let suffix=$RANDOM*$RANDOM
    accountName="msdocs-$suffix"
    
  2. 如果您尚未登入,請使用 az login 命令登入 Azure CLI。

  3. 使用 az group create 命令在您的訂用帳戶中建立新的資源群組。

    az group create \
        --name $resourceGroupName \
        --location $location
    
  4. az cosmosdb create使用 命令,為具有預設設定的資料表帳戶建立新的 Azure Cosmos DB。

    az cosmosdb create \
        --resource-group $resourceGroupName \
        --name $accountName \
        --locations regionName=$location
        --capabilities EnableTable
    

取得資料表連接字串的 API

  1. 使用 命令,從帳戶 az cosmosdb list-connection-strings 的連接字串清單中尋找資料表連接字串的 API。

    az cosmosdb list-connection-strings \
        --resource-group $resourceGroupName \
        --name $accountName 
    
  2. 記錄「主要資料表連接字串」值。 稍後您將使用這些認證。

建立新的 .NET 應用程式

使用您慣用的終端機,在空白資料夾中建立新的 .NET 應用程式。 使用 dotnet new console 建立新的主控台應用程式。

dotnet new console --output <app-name>

安裝 NuGet 封裝

Azure.Data.Tables NuGet 套件新增至新的 .NET 專案。 使用指定 NuGet 套件名稱的 dotnet add package 命令。

dotnet add package Azure.Data.Tables

設定環境變數

若要在程式碼中使用 CONNECTION STRING 值,請在執行應用程式的本機電腦上設定此值。 若要設定環境變數,請使用您慣用的終端機來執行下列命令:

$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"

程式碼範例

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

您將針對資料表類別使用下列 API 來與這些資源互動:

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

// 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 時,可以刪除對應的資源群組。

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

az group delete --name $resourceGroupName

下一步

在本快速入門中,您已瞭解如何使用 .NET SDK 建立適用于資料表帳戶的 Azure Cosmos DB、建立資料表和管理專案。 您現在可以深入瞭解 SDK,瞭解如何在適用于資料表資源的 Azure Cosmos DB 中執行更進階的資料查詢和管理工作。