如何使用受控識別來從 Azure 虛擬機器連線到 Azure Cosmos DB
在此文章中，我們會設定虛擬機器，以使用受控識別來連線到 Azure Cosmos DB。 Azure Cosmos DB 是適用於新式應用程式開發的完全受控 NoSQL 資料庫。 Azure 資源的受控識別在您使用受 Azure 管理的身分識別存取支援 Microsoft Entra 驗證的服務時，允許您的應用程式進行驗證。
必要條件
- 受控識別的基本了解。 如果您想要在繼續之前深入了解 Azure 資源的受控識別，請參閱受控識別概觀。
- 您必須具備含有效訂閱的 Azure 帳戶。 免費建立帳戶。
- 您可能需要 PowerShell 或 CLI。
- Visual Studio Community 版或一些您選擇的其他開發環境。
建立資源群組
建立名為 mi-test 的資源群組。 我們會將此資源群組用於本教學課程中所使用的所有資源。
建立具有受控識別的 Azure VM
在本教學課程中，您只需要 Azure 虛擬機器 (VM)。 建立一個名為 mi-vm-01 的虛擬機器，其系統指派的受控識別已啟用。 您也可以在我們稍早建立的資源群組 (mi-test) 中，建立使用者指派的受控識別，並命名為 mi-ua-01。 如果您使用使用者指派的受控識別，便可以在建立期間將其指派給 VM。
建立具有系統指派受控識別的 VM
若要建立已啟用系統指派受控識別的 Azure VM，您的帳戶需要虛擬機器參與者角色指派。 不需要其他 Microsoft Entra 角色指派。
- 從 Azure 入口網站搜尋虛擬機器。
- 選擇 [建立]
- 在 [基本] 索引標籤上輸入必要資訊。
- 選擇 [下一步：磁碟] >
- 視需要繼續填寫資訊，然後在 [管理] 索引標籤中尋找 [身分識別] 區段，並勾選 [系統指派的受控識別] 旁的方塊
如需詳細資訊，請檢閱 Azure 虛擬機器文件：
建立具有使用者指派受控識別的 VM
下列步驟說明如何建立已設定使用者指派受控識別的虛擬機器。
Azure 入口網站目前不支援在建立虛擬機器時指派使用者指派的受控識別。 您應建立虛擬機器，然後將使用者指派的受控識別指派給該虛擬機器。
建立 Azure Cosmos DB 帳戶
既然已經有一部具有使用者指派受控識別或系統指派受控識別的 VM，我們需要您擁有管理員權限的可用 Azure Cosmos DB 帳戶。 如果您需要建立此教學課程適用的 Azure Cosmos DB 帳戶，Azure Cosmos DB 快速入門提供如何建立該帳戶的詳細步驟。
注意
受控識別可用來存取任何支援 Microsoft Entra 驗證的 Azure 資源。 此教學課程假設您的 Azure Cosmos DB 帳戶設定如下所示。
| 設定 | 值 | Description |
|---|---|---|
| 訂用帳戶 | 訂用帳戶名稱 | 選取您要用於此 Azure Cosmos DB 帳戶的 Azure 訂用帳戶。 |
| 資源群組 | 資源群組名稱 | 選取 [mi-test]，或選取 [新建]，然後輸入新資源群組的唯一名稱。 |
| 客戶名稱 | 唯一名稱 | 輸入名稱來識別您的 Azure Cosmos DB 帳戶。 因為 documents.azure.com 會附加到您所提供的名稱以建立 URI，請使用唯一名稱。 名稱只能包含小寫字母、數字及連字號 (-) 字元。 其長度必須介於 3 到 44 個字元之間。 |
| API | 要建立的帳戶類型 | 選取 [Azure Cosmos DB for NoSQL]，以使用 SQL 語法來建立文件資料庫和查詢。 進一步了解 SQL API。 |
| Location | 最接近使用者的區域 | 選取用來裝載 Azure Cosmos DB 帳戶的地理位置。 使用最接近使用者的位置，讓他們能以最快速度存取資料。 |
注意
如果要進行測試，建議您申請 Azure Cosmos DB 免費階層折扣。 使用 Azure Cosmos DB 免費層，您將可在帳戶中免費取得前 1000 RU/秒和 25 GB 的儲存體。 深入了解免費層。 請記住，基於本教學課程的目的，此選擇不會產生任何差異。
授予存取權
此時，應該會有使用受控識別設定的虛擬機器及 Azure Cosmos DB 帳戶。 在繼續之前，我們必須將幾個不同的角色授與受控識別。
首先，使用 Azure RBAC 來授與對 Azure Cosmos DB 管理平面的存取權。 受控識別必須已指派 DocumentDB 帳戶參與者角色，才能建立資料庫和容器。
您也需要使用 Azure Cosmos DB RBAC，為受控識別授與參與者角色。 您可以在下方查看具體步驟。
注意
我們將使用 Cosmos DB 內建資料參與者角色。 若要授與存取權，您必須將角色定義與身分識別產生關聯。 在我們的案例中，是與我們的虛擬機器相關聯的受控識別。
目前，Azure 入口網站沒有任何角色指派選項可用
存取資料
您可以使用 Azure.identity 程式庫，在應用程式中啟用驗證，以使用受控識別來取得對 Azure Cosmos DB 的存取權。 您可以直接呼叫 ManagedIdentityCredential，或使用 DefaultAzureCredential。
ManagedIdentityCredential 類別會嘗試使用指派給部署環境的受控識別進行驗證。 DefaultAzureCredential 類別會依序逐一檢查不同的驗證選項。 DefaultAzureCredential 嘗試的第二個驗證選項是受控識別。
在如下所示的範例中，您會建立資料庫、容器、容器中的項目，並使用虛擬機器的系統指派受控識別來讀回新建立的項目。 如果您想使用使用者指派的受控識別，則必須指定受控識別的用戶端識別碼，以指定使用者指派的受控識別。
string userAssignedClientId = "<your managed identity client Id>";
var tokenCredential = new DefaultAzureCredential(new DefaultAzureCredentialOptions { ManagedIdentityClientId = userAssignedClientId });
若要使用下列範例，您需要有下列 NuGet 封裝：
- Azure.Identity
- Microsoft.Azure.Cosmos
- Microsoft.Azure.Management.CosmosDB
除了上述 NuGet 封裝外，您必須啟用 [包含發行前版本]，然後新增 Azure.ResourceManager.CosmosDB。
using Azure.Identity;
using Azure.ResourceManager.CosmosDB;
using Azure.ResourceManager.CosmosDB.Models;
using Microsoft.Azure.Cosmos;
using System;
using System.Threading.Tasks;
namespace MITest
{
class Program
{
static async Task Main(string[] args)
{
// Replace the placeholders with your own values
var subscriptionId = "Your subscription ID";
var resourceGroupName = "You resource group";
var accountName = "Cosmos DB Account name";
var databaseName = "mi-test";
var containerName = "container01";
// Authenticate to Azure using Managed Identity (system-assigned or user-assigned)
var tokenCredential = new DefaultAzureCredential();
// Create the Cosmos DB management client using the subscription ID and token credential
var managementClient = new CosmosDBManagementClient(tokenCredential)
{
SubscriptionId = subscriptionId
};
// Create the Cosmos DB data client using the account URL and token credential
var dataClient = new CosmosClient($"https://{accountName}.documents.azure.com:443/", tokenCredential);
// Create a new database using the management client
var createDatabaseOperation = await managementClient.SqlResources.StartCreateUpdateSqlDatabaseAsync(
resourceGroupName,
accountName,
databaseName,
new SqlDatabaseCreateUpdateParameters(new SqlDatabaseResource(databaseName), new CreateUpdateOptions()));
await createDatabaseOperation.WaitForCompletionAsync();
// Create a new container using the management client
var createContainerOperation = await managementClient.SqlResources.StartCreateUpdateSqlContainerAsync(
resourceGroupName,
accountName,
databaseName,
containerName,
new SqlContainerCreateUpdateParameters(new SqlContainerResource(containerName), new CreateUpdateOptions()));
await createContainerOperation.WaitForCompletionAsync();
// Create a new item in the container using the data client
var partitionKey = "pkey";
var id = Guid.NewGuid().ToString();
await dataClient.GetContainer(databaseName, containerName)
.CreateItemAsync(new { id = id, _partitionKey = partitionKey }, new PartitionKey(partitionKey));
// Read back the item from the container using the data client
var pointReadResult = await dataClient.GetContainer(databaseName, containerName)
.ReadItemAsync<dynamic>(id, new PartitionKey(partitionKey));
// Run a query to get all items from the container using the data client
await dataClient.GetContainer(databaseName, containerName)
.GetItemQueryIterator<dynamic>("SELECT * FROM c")
.ReadNextAsync();
}
}
}
使用 ManagedIdentityCredential 的特定語言範例：
.NET
將您的 Azure Cosmos DB 用戶端初始化：
CosmosClient client = new CosmosClient("<account-endpoint>", new ManagedIdentityCredential());
然後讀取和寫入資料。
Java
將您的 Azure Cosmos DB 用戶端初始化：
CosmosAsyncClient Client = new CosmosClientBuilder().endpoint("<account-endpoint>") .credential(new ManagedIdentityCredential()) .build();
然後讀取和寫入資料，如下列範例所述
JavaScript
將您的 Azure Cosmos DB 用戶端初始化：
const client = new CosmosClient({ "<account-endpoint>", aadCredentials: new ManagedIdentityCredential() });
然後讀取和寫入資料，如下列範例所述
清除步驟
提示
根據您開始使用的入口網站，本文中的步驟可能略有不同。
登入 Azure 入口網站。
選取您要刪除的資源。
選取 [刪除]。
出現提示時，確認刪除。
下一步
深入了解 Azure 資源的受控識別：
深入了解 Azure Cosmos DB：