快速入門:適用於 .NET 的 Azure Cosmos DB for NoSQL 用戶端程式庫
適用於: NoSQL
使用適用於 .NET 的 Azure Cosmos DB 用戶端程式庫開始,以在您的帳戶內建立資料庫、容器和專案。 請遵循下列步驟來安裝套件,並試用基本工作的程式碼範例。
注意
範例程式碼片段可在 GitHub 作為 .NET 專案使用。
API 參考文件 | 程式庫來源程式碼 | 套件 (NuGet) | 範例
必要條件
- 具有有效訂用帳戶的 Azure 帳戶。
- 沒有 Azure 訂閱嗎? 您可以免費試用 Azure Cosmos DB,不需要信用卡。
- .NET 6.0 或更新版本
- Azure 命令列介面 (CLI) 或 Azure PowerShell
先決條件檢查
- 在終端機或命令視窗中,執行
dotnet --version
,以確認 .NET SDK 為 6.0 版或更新版本。 - 執行
az --version
(Azure CLI) 或Get-Module -ListAvailable AzureRM
(Azure PowerShell),以確認您已安裝適當的 Azure 命令列工具。
設定
本節將逐步引導您建立 Azure Cosmos DB 帳戶,並設定專案以使用適用於 .NET 的 Azure Cosmos DB for NoSQL 用戶端程式庫來管理資源。
建立 Azure Cosmos DB 帳戶
提示
沒有 Azure 訂閱嗎? 您可以免費試用 Azure Cosmos DB,不需要信用卡。 如果您使用免費試用來建立帳戶,則可以放心地跳到建立新的 .NET 應用程式一節。
本快速入門會使用 API for NoSQL 建立單一 Azure Cosmos DB 帳戶。
提示
針對本快速入門,我們建議使用資源組名稱 msdocs-cosmos-quickstart-rg
。
登入 Azure 入口網站。
從 Azure 入口網站功能表或[首頁] 頁面,選取 [建立資源]。
在 [新增] 頁面上,搜尋並選取 [Azure Cosmos DB]。
在 [選取 API 選項] 頁面上,選取 [NoSQL] 區段中的 [建立] 選項。 Azure Cosmos DB 有六個 API:NoSQL、MongoDB、PostgreSQL、Apache Cassandra、Apache Gremlin 和 Table。 深入了解 API for NoSQL。
在 [建立 Azure Cosmos DB 帳戶] 頁面上,輸入下列資訊:
設定 值 描述 訂用帳戶 訂閱名稱 選取要用於此 Azure Cosmos 帳戶的 Azure 訂用帳戶。 資源群組 資源群組名稱 選取資源群組,或選取 [新建],然後輸入新資源群組的唯一名稱。 帳戶名稱 唯一的名稱 輸入名稱來識別您的 Azure Cosmos 帳戶。 名稱將作為完整網域名稱 (FQDN) 的一部分,其尾碼為 documents.azure.com,因此名稱必須是全域唯一。 名稱只能包含小寫字母、數字及連字號 (-) 字元。 且名稱長度必須介於 3 到 44 個字元之間。 Location 最接近使用者的區域 選取用來裝載 Azure Cosmos DB 帳戶的地理位置。 使用最接近使用者的位置,讓他們能以最快速度存取資料。 容量模式 佈建輸送量或無伺服器 選取 [佈建的輸送量],以佈建的輸送量模式建立帳戶。 選取 [無伺服器],以無伺服器模式建立帳戶。 申請 Azure Cosmos DB 免費階層折扣 適用或不適用 啟用 Azure Cosmos DB 免費層。 使用 Azure Cosmos DB 免費層,您將可在帳戶中免費取得前 1000 RU/秒和 25 GB 的儲存體。 深入了解免費層。 注意
每個 Azure 訂用帳戶最多可以有一個免費層的 Azure Cosmos DB 帳戶,而且必須在建立帳戶時選擇加入。 如果您看不到套用免費層折扣的選項,這表示訂用帳戶中的另一個帳戶已透過免費層啟用。
選取 [檢閱 + 建立]。
檢閱您提供的設定,然後選取 [建立]。 建立帳戶需要幾分鐘的時間。 繼續進行之前,請等候入口網站頁面顯示 [您的部署已完成] 訊息。
選取 [移至資源] 以移至 Azure Cosmos DB 帳戶頁面。
從 API for NoSQL 帳戶頁面,選取 [金鑰] 導覽功能表選項。
記錄 URI 和 PRIMARY KEY 欄位中的值。 您將在稍後的步驟中使用這些值。
建立新的 .NET 應用程式
使用您慣用的終端機,在空白資料夾中建立新的 .NET 應用程式。 使用指定主控台範本的 dotnet new
命令。
dotnet new console
安裝套件
將 Microsoft.Azure.Cosmos NuGet 套件新增至 .NET 專案。 使用指定 NuGet 套件名稱的 dotnet add package
命令。
dotnet add package Microsoft.Azure.Cosmos
使用 dotnet build
命令建立專案。
dotnet build
確定建置成功,且沒有任何錯誤。 組建的預期輸出看起來應像這樣:
Determining projects to restore...
All projects are up-to-date for restore.
dslkajfjlksd -> C:\Users\sidandrews\Demos\dslkajfjlksd\bin\Debug\net6.0\dslkajfjlksd.dll
Build succeeded.
0 Warning(s)
0 Error(s)
設定環境變數
若要在程式碼中使用 URI 和 PRIMARY KEY 值,請將其保存在執行應用程式本機電腦上新的環境變數中。 若要設定環境變數,請使用您慣用的終端機來執行下列命令:
$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"
物件模型
在開始建置應用程式之前,讓我們看一下 Azure Cosmos DB 中的資源階層。 Azure Cosmos DB 具有用來建立和存取資源的特定物件模型。 Azure Cosmos DB 會在包含帳戶、資料庫、容器和專案的階層中建立資源。
在頂端顯示 Azure Cosmos DB 帳戶的階層式圖表。 帳戶有兩個子資料庫節點。 其中一個資料庫節點包含兩個子容器節點。 另一個資料庫節點包含單一子容器節點。 該單一容器節點有三個子項目節點。
如需深入了解不同資源的階層,請參閱使用 Azure Cosmos DB 中的資料庫、容器和項目。
您將使用下列 .NET 類別與這些資源互動:
CosmosClient
- 此類別提供適用於 Azure Cosmos DB 服務的用戶端邏輯表示法。 用戶端物件會用於設定及執行針對服務的要求。Database
- 此類別是服務中可能存在或不存在的資料庫參考。 當您嘗試存取資料庫或對其執行作業時,資料庫為已驗證的伺服器端。Container
- 此類別為容器參考,可能尚未於伺服器中存在。 當您嘗試使用此項目時,容器為已驗證的伺服器端。QueryDefinition
- 這個類別代表SQL查詢和任何查詢參數。FeedIterator<>
- 這個類別代表可追蹤目前結果頁面並取得新結果頁面的反覆運算器。FeedResponse<>
- 這個類別代表反覆運算器回應的單一頁面。 此類型可以使用foreach
迴圈逐一查看。
程式碼範例
本文所述的範例程式碼會建立名為 cosmicworks
的資料庫,其中包含名為 products
的容器。 products
資料表旨在包含產品詳細資料,例如名稱、類別、數量和銷售指標。 每個產品也都包含唯一識別碼。
在此範例程式碼中,容器會使用類別作為邏輯分割區索引鍵。
驗證用戶端
對大部分 Azure 服務的應用程式要求都必須獲得授權。 DefaultAzureCredential
使用 Azure 身分識別用戶端程式庫提供的 類別,是在您的程式碼中實作 Azure 服務無密碼連線的建議方法。
您也可以直接使用密碼、連接字串或其他認證來授權對 Azure 服務的要求。 不過,應該謹慎使用此方法。 開發人員必須努力不要在不安全的位置公開這些秘密。 取得密碼或秘密金鑰存取權的任何人都可以進行驗證。 DefaultAzureCredential
提供優於帳戶金鑰的管理和安全性優點,允許無密碼驗證。 下列範例示範這兩個選項。
DefaultAzureCredential
是適用于 .NET 的 Azure 身分識別用戶端程式庫所提供的類別。 若要深入瞭解 DefaultAzureCredential
,請參閱 DefaultAzureCredential 概觀。 DefaultAzureCredential
支援多個驗證方法,並在執行階段判斷應該使用哪個方法。 此方法可讓您的應用程式在不同的環境中 (本機或實際執行環境) 使用不同的驗證方法,而不需要實作環境特有的程式碼。
例如,您的應用程式可以在本機開發時使用 Visual Studio 登入認證進行驗證,然後在部署至 Azure 之後使用 受控識別 。 此轉移不需要變更程式碼。
使用無密碼驗證在本機開發時,請確定連線到 Cosmos DB 的使用者帳戶已獲指派具有正確許可權來執行資料作業的角色。 目前,適用于 NoSQL 的 Azure Cosmos DB 不包含資料作業的內建角色,但您可以使用 Azure CLI 或 PowerShell 建立自己的角色。
角色是由允許使用者執行的許可權或動作集合所組成,例如讀取、寫入和刪除。 您可以在 Cosmos DB 安全性設定檔中深入瞭解如何設定 角色型存取控制 (RBAC) 。
建立自訂角色
使用 命令建立
az role definition create
角色。 傳入 Cosmos DB 帳戶名稱和資源群組,後面接著定義自訂角色的 JSON 主體。 下列範例會建立名為PasswordlessReadWrite
的角色,其具有讀取和寫入 Cosmos DB 容器中專案的許可權。 角色也會使用/
範圍設定為帳戶層級。az cosmosdb sql role definition create \ --account-name <cosmosdb-account-name> \ --resource-group <resource-group-name> \ --body '{ "RoleName": "PasswordlessReadWrite", "Type": "CustomRole", "AssignableScopes": ["/"], "Permissions": [{ "DataActions": [ "Microsoft.DocumentDB/databaseAccounts/readMetadata", "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*", "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*" ] }] }'
當命令完成時,請從 欄位複製識別碼值,
name
並將它貼到某處以供稍後使用。將您建立的角色指派給將連線到 Cosmos DB 的使用者帳戶或服務主體。 在本機開發期間,這通常是您自己登入 Visual Studio 或 Azure CLI 等開發工具的帳戶。 使用
az ad user
命令擷取帳戶的詳細資料。az ad user show --id "<your-email-address>"
將 屬性的值
id
從結果複製出來,並貼到某處以供稍後使用。使用
az cosmosdb sql role assignment create
命令和您先前複製的識別碼,將您建立的自訂角色指派給使用者帳戶。az cosmosdb sql role assignment create \ --account-name <cosmosdb-account-name> \ --resource-group <resource-group-name> \ --scope "/" \ --principal-id <your-user-id> \ --role-definition-id <your-custom-role-id>
使用 DefaultAzureCredential 進行驗證
針對本機開發,請確定您已使用您指派角色的相同 Azure AD 帳戶進行驗證。 您可以透過熱門的開發工具進行驗證,例如 Azure CLI 或Azure PowerShell。 您可以驗證的開發工具會隨著語言而有所不同。
使用下列命令透過 Azure CLI 登入 Azure:
az login
您可以將 NuGet 套件新增至您的應用程式,以向 DefaultAzureCredential
適用于 NoSQL 的 Azure.Identity
Cosmos DB 進行驗證。 DefaultAzureCredential
會自動探索並使用您在上一個步驟中登入的帳戶。
dotnet add package Azure.Identity
從專案目錄開啟檔案 Program.cs
。 在編輯器中,為 和 Azure.Identity
命名空間新增 using 指示詞 Microsoft.Azure.Cosmos
。
using Microsoft.Azure.Cosmos;
using Azure.Identity;
使用 建構函式定義 類別的新實例,並 Environment.GetEnvironmentVariable
讀取 COSMOS_ENDPOINT
您稍早建立的 CosmosClient
環境變數。
// New instance of CosmosClient class
using CosmosClient client = new(
accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT"),
tokenCredential: new DefaultAzureCredential()
);
如需建立 CosmosClient
執行個體的不同方式詳細資訊,請參閱開始使用 Azure Cosmos DB for NoSQL 和 .NET。
建立和查詢資料庫
接下來,您將建立資料庫和容器來儲存產品,並執行查詢來插入和讀取這些專案。
用戶端 Microsoft.Azure.Cosmos
程式庫可讓您使用Azure RBAC執行資料作業。 不過,若要驗證 管理 作業,例如建立和刪除資料庫,您必須透過下列其中一個選項使用 RBAC:
此範例會使用 Azure CLI 方法。 az cosmosdb sql database create
使用 和 az cosmosdb sql container create
命令來建立 Cosmos DB NoSQL 資料庫和容器。
# Create a SQL API database
az cosmosdb sql database create
--account-name msdocs-cosmos-nosql
--resource-group msdocs
--name cosmicworks
# Create a SQL API container
az cosmosdb sql container create
--account-name msdocs-cosmos-nosql
--resource-group msdocs
--database-name cosmicworks
--name products
建立資源之後,請使用用戶端程式庫的 Microsoft.Azure.Cosmos
類別來連線並查詢資料庫。
取得資料庫
CosmosClient.GetDatabase
使用 方法會傳回指定資料庫的參考。
// Database reference with creation if it does not already exist
Database database = await client.CreateDatabaseIfNotExistsAsync(id: "cosmicworks");
Console.WriteLine($"New database:\t{database.Id}");
取得容器
Database.GetContainer
會傳回指定容器的參考。
// Container reference with creation if it does not alredy exist
Container container = database.GetContainer(id: "products");
Console.WriteLine($"New container:\t{container.Id}");
建立項目
在容器中建立新專案最簡單的方式,就是先建置 C# 類別或記錄類型,其中包含您想要序列化為 JSON 的所有成員。 在此範例中,C# 記錄具有唯一識別碼、分割區索引鍵的 categoryId 欄位,以及額外的 categoryName、name、quantity 和 sale 欄位。
// C# record representing an item in the container
public record Product(
string id,
string categoryId,
string categoryName,
string name,
int quantity,
bool sale
);
藉由呼叫 Container.CreateItemAsync
,在容器中建立項目。
// Create new object and upsert (create or replace) to container
Product newItem = new(
id: "70b63682-b93a-4c77-aad2-65501347265f",
categoryId: "61dba35b-4f02-45c5-b648-c6badc0cbd79",
categoryName: "gear-surf-surfboards",
name: "Yamba Surfboard",
quantity: 12,
sale: false
);
Product createdItem = await container.CreateItemAsync<Product>(
item: newItem,
partitionKey: new PartitionKey("61dba35b-4f02-45c5-b648-c6badc0cbd79")
);
Console.WriteLine($"Created item:\t{createdItem.id}\t[{createdItem.categoryName}]");
如需建立、更新插入或取代項目的詳細資訊,請參閱使用 .NET 在 Azure Cosmos DB for NoSQL 中建立項目。
取得項目
在 Azure Cosmos DB 中,您可以使用唯一識別碼 (id
) 和資料分割索引鍵欄位來執行點讀取作業。 在 SDK 中,呼叫 Container.ReadItemAsync<>
傳入這兩個值,以傳回 C# 類型的還原序列化執行個體。
// Point read item from container using the id and partitionKey
Product readItem = await container.ReadItemAsync<Product>(
id: "70b63682-b93a-4c77-aad2-65501347265f",
partitionKey: new PartitionKey("61dba35b-4f02-45c5-b648-c6badc0cbd79")
);
如需讀取項目和剖析回應的詳細資訊,請參閱使用 .NET 讀取 Azure Cosmos DB for NoSQL 中的項目。
查詢項目
插入項目之後,您可以執行查詢來取得符合特定篩選的所有項目。 此範例會執行SQL查詢:SELECT * FROM products p WHERE p.categoryId = "61dba35b-4f02-45c5-b648-c6badc0cbd79"
。 這個範例會針對分割區索引鍵篩選使用 QueryDefinition 類型和參數化查詢運算式。 定義查詢之後,呼叫 Container.GetItemQueryIterator<>
以取得將管理結果頁面的結果反覆運算器。 然後,使用 while
和 foreach
迴圈的組合來擷取結果的頁面,然後逐一查看個別專案。
// Create query using a SQL string and parameters
var query = new QueryDefinition(
query: "SELECT * FROM products p WHERE p.categoryId = @categoryId"
)
.WithParameter("@categoryId", "61dba35b-4f02-45c5-b648-c6badc0cbd79");
using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
queryDefinition: query
);
while (feed.HasMoreResults)
{
FeedResponse<Product> response = await feed.ReadNextAsync();
foreach (Product item in response)
{
Console.WriteLine($"Found item:\t{item.name}");
}
}
執行程式碼
此應用程式會建立 API for NoSQL 資料庫和容器。 然後,此範例會建立項目,然後重新讀取完全相同的項目。 最後,此範例會發出只應該傳回該單一項目的查詢。 在每個步驟中,範例會將中繼資料輸出至主控台,包含其執行的步驟。
若要執行應用程式,請使用終端機瀏覽至應用程式目錄並執行應用程式。
dotnet run
此命令的輸出應類似此範例:
New database: adventureworks
New container: products
Created item: 68719518391 [gear-surf-surfboards]
清除資源
當您不再需要 API for NoSQL 帳戶時,可以刪除對應的資源群組。
下一步
在本快速入門中,您已了解如何使用 .NET SDK 建立 Azure Cosmos DB for NoSQL 帳戶、建立資料庫,以及建立容器。 您現在可以深入探討使用 .NET 主控台應用程式管理 Azure Cosmos DB for NoSQL 資源和資料的教學課程。