開始使用 Azure Cosmos DB for Table 搭配 .NET

適用於： Table

本文說明如何透過 .NET SDK 與 Azure Cosmos DB for Table 連線。 連線之後，您即可在表格和項目上執行作業。

封裝 (NuGet) | 範例 | API 參考 | 程式庫原始程式碼 | 提供意見反應 |

必要條件

• 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
• Azure Cosmos DB for Table 帳戶。 建立 API for Table 帳戶。
• .NET 6.0 或更新版本
• Azure 命令列介面 (CLI) 或 Azure PowerShell

設定您的專案

建立 .NET 主控台應用程式

使用 dotnet new 命令搭配主控台範本來建立新的 .NET 應用程式。

dotnet new console

使用 命令匯入 Azure.Data.Tablesdotnet add package NuGet 套件。

dotnet add package Azure.Data.Tables

使用 dotnet build 命令建立專案。

dotnet build

連線至 Azure Cosmos DB for Table

若要連線到 Azure Cosmos DB 的 API for Table，請建立 TableServiceClient 類別的執行個體。 此類別是針對表格執行所有作業的起點。 有兩種主要的方式可使用 TableServiceClient 類別，連線至 API for Table 帳戶：

• 使用 API for Table 連接字串進行連線

使用連接字串來連線

TableServiceClient 最常見的建構函式具有單一參數：

參數	範例值	描述
connectionString	COSMOS_CONNECTION_STRING 環境變數	API for Table 帳戶的連接字串

擷取您的帳戶連接字串

Azure CLI

1. 使用 az cosmosdb list 命令來擷取資源群組中第一個 Azure Cosmos DB 帳戶的名稱，並將其儲存在 accountName 殼層變數中。

   # Retrieve most recently created account name
   accountName=$(
       az cosmosdb list \
           --resource-group $resourceGroupName \
           --query "[0].name" \
           --output tsv
   )
   

2. 使用 az-cosmosdb-keys-list 命令，從帳戶的連接字串清單中尋找 PRIMARY CONNECTION STRING。

   az cosmosdb keys list \
       --resource-group $resourceGroupName \
       --name $accountName \
       --type "connection-strings" \
       --query "connectionStrings[?description == \`Primary Table Connection String\`] | [0].connectionString"
   

PowerShell

1. 使用 Get-AzCosmosDBAccount Cmdlet 來擷取資源群組中第一個 Azure Cosmos DB 帳戶的名稱，並將其儲存在 ACCOUNT_NAME 殼層變數中。

   # Retrieve most recently created account name
   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
   }
   $ACCOUNT_NAME = (
       Get-AzCosmosDBAccount @parameters |
           Select-Object -Property Name -First 1
   ).Name
   

2. 使用 Cmdlet，從帳戶的連接字串清單中尋找 PRIMARY CONNECTION STRINGGet-AzCosmosDBAccountKey。

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "ConnectionStrings"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "Primary Table Connection String" -First 1    
   

若要在 .NET 程式碼中使用 [PRIMARY CONNECTION STRING] 值，請將其保存在執行應用程式的本機電腦上新的環境變數。

Windows

$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"

Linux / macOS

export COSMOS_CONNECTION_STRING="<cosmos-account-PRIMARY-CONNECTION-STRING>"

使用連接字串建立 TableServiceClient

使用 COSMOS_CONNECTION_STRING 環境變數作為唯一參數，建立 TableServiceClient 類別的新執行個體。

// New instance of TableServiceClient class using a connection string
TableServiceClient client = new(
    connectionString: Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING")!
);

建置您的 應用程式

組建應用程式時，程式碼主要與四種資源互動：

• API for Table 帳戶是 Azure Cosmos DB 資料的唯一最上層命名空間。

• 表格，其中包含帳戶中的一組個別項目。

• 項目，代表表格中的個別項目。

下圖顯示資源之間的關係。

在頂端顯示 Azure Cosmos DB 帳戶的階層式圖表。 帳戶有兩個子表格節點。 其中一個表格節點包含兩個子項目。

每種資源以一或多個相關聯的 .NET 類別或介面來表示。 以下是最常見類型的清單：

類別	描述
TableServiceClient	此用戶端類別提供適用於 Azure Cosmos DB 服務的用戶端邏輯表示法。 用戶端物件會用於設定及執行針對服務的要求。
TableClient	此用戶端類別是服務中可能存在或不存在的表格參考。 當您嘗試存取資料庫或對其執行作業時，表格為已驗證的伺服器端。
ITableEntity	此介面是表格中已建立或從表格中查詢的項目基底介面。 此介面包含 API for Table 中項目的所有必要屬性。
TableEntity	這個類別是 ITableEntity 介面的通用實作，做為機碼值組的字典。

下列指南說明如何以上每個類別來組建應用程式。

指南	描述
建立資料表	建立表格
建立項目	建立項目
讀取項目	讀取項目

另請參閱

• 套件 (NuGet)
• 範例
• API 參考
• 程式庫原始程式碼
• 提供意見反應

下一步

既然您已連線到 API for Table 帳戶，請使用下一份指南來建立和管理資料表。

使用 .NET 在 Azure Cosmos DB for Table 中建立資料表