マネージド ID を使用して Azure 仮想マシンから Azure Cosmos DB に接続する方法

  • [アーティクル]

注意事項

この記事では、間もなくサポート終了 (EOL) 状態になる Linux ディストリビューションである CentOS について説明します。 適宜、使用と計画を検討してください。 詳細については、「CentOS のサポート終了に関するガイダンス」を参照してください。

この記事では、マネージド ID を使用して Azure Cosmos DB に接続するよう仮想マシンを設定します。 Azure Cosmos DB は、最新のアプリ開発に対応するフル マネージドの NoSQL データベースです。 Azure リソースのマネージド ID を使用すると、Azure によって管理されている ID を使用して Microsoft Entra 認証をサポートするサービスにアクセスするときに、アプリケーションを認証できます。

前提条件

リソース グループを作成する

mi-test という名前のリソース グループを作成します。 このチュートリアルで使用されるすべてのリソースについて、このリソース グループを使用します。

マネージド ID を使用して Azure VM を作成する

このチュートリアルでは、Azure 仮想マシン (VM) が必要です。 システム割り当てマネージド ID を有効にして mi-vm-01 という名前の仮想マシンを作成します。 また、以前作成したリソース グループ (mi-test) に、mi-ua-01 という名前のユーザー割り当てマネージド ID を作成することもできます。 ユーザー割り当てマネージド ID を使用する場合は、作成時に VM に割り当てることができます。

システム割り当てマネージド ID を使用して VM を作成する

システム割り当てマネージド ID を有効にして Azure VM を作成するには、お使いのアカウントに仮想マシン共同作成者ロールの割り当てが必要です。 その他の Microsoft Entra ロールを割り当てる必要はありません。

  • Azure portal から、 [仮想マシン] を検索します。
  • [作成] を選択します。
  • [基本] タブで、必要な情報を指定します。
  • [Next: Disks>](次へ: ディスク>) を選択します
  • 必要に応じて情報の入力を続行し、 [管理] タブで [ID] セクションを見つけ、 [システム割り当てマネージド ID] の横のボックスをオンにします。

VM の作成時にシステム割り当てマネージド ID を有効にする方法を示す画像。

詳細については、Azure 仮想マシンのドキュメントを参照してください。

ユーザー割り当てマネージド ID を使用して VM を作成する

以下の手順では、ユーザー割り当てマネージド ID が構成された仮想マシンを作成する方法を示します。

現在 Azure portal では、VM 作成中のユーザー割り当てマネージド ID の割り当てはサポートされていません。 仮想マシンを作成した後で、ユーザー割り当てマネージド ID をそれに割り当てる必要があります。

Azure portal を使用して Azure VM で Azure リソースのマネージド ID を構成する

Azure Cosmos DB アカウントを作成する

これで、ユーザー割り当てマネージド ID またはシステム割り当てマネージド ID を使用して VM が作成されたので、管理者権限を持つ Azure Cosmos DB アカウントを使用できるようにする必要があります。 このチュートリアル用に Azure Cosmos DB アカウントを作成する必要がある場合、その方法の詳細なステップについては Azure Cosmos DB クイック スタートを参照してください。

Note

マネージド ID は、Microsoft Entra 認証をサポートするあらゆる Azure リソースにアクセスするために使用できます。 このチュートリアルでは、Azure Cosmos DB アカウントが次に示すように構成されていることを前提とします。

設定 値 説明
サブスクリプション サブスクリプション名 この Azure Cosmos DB アカウントに使用する Azure サブスクリプションを選択します。
リソース グループ リソース グループ名 mi-test を選択するか、 [新規作成] を選択し、新しいリソース グループの一意の名前を入力します。
アカウント名 一意の名前 自分の Azure Cosmos DB アカウントを識別するための名前を入力します。 指定した名前に documents.azure.com が付加されて URI が作成されるので、一意の名前を使用してください。

名前に含めることができるのは、英小文字、数字、ハイフン (-) のみです。 長さは 3 文字から 44 文字でなければなりません。
API 作成するアカウントの種類。 ドキュメント データベースを作成し、SQL 構文を使用してクエリを実行するには、Azure Cosmos DB for NoSQL を選択します。

SQL API について詳しくは、こちらをご覧ください。
場所 ユーザーに最も近いリージョン Azure Cosmos DB アカウントをホストする地理的な場所を選択します。 データに最も高速にアクセスできるよう、お客様のユーザーに最も近い場所を使用します。

注意

テストを行う場合は、Azure Cosmos DB の Free レベル割引を適用することもできます。 Azure Cosmos DB Free レベルのアカウントでは、最初の 1000 RU/s と 25 GB のストレージを無料でご利用いただけます。 Free レベルの詳細を確認してください。 ただし、このチュートリアルでは、この選択によって違いが生じることはありません。

アクセス権の付与

この時点で、マネージド ID を使用して構成された仮想マシンと、Azure Cosmos DB アカウントが両方存在するはずです。 続行する前に、マネージド ID にいくつかの異なるロールを付与する必要があります。

  • 最初に、Azure RBAC を使用して、Azure Cosmos DB 管理プレーンへのアクセス権を付与します。 マネージド ID には、データベースとコンテナーを作成するために DocumentDB アカウント共同作成者ロールが割り当てられている必要があります。

  • また、Azure Cosmos DB RBAC を使用して、マネージド ID に共同作成者ロールを付与する必要もあります。 具体的な手順は下で確認できます。

注意

Cosmos DB 組み込みデータ共同作成者ロールを使用します。 アクセス権を付与するには、ロール定義を ID に関連付ける必要があります。 この例では、マネージド ID は仮想マシンに関連付けられます。

現時点では、Azure portal ではロールの割り当てオプションを利用できません

データにアクセスする

マネージド ID を使用して Azure Cosmos DB にアクセスすることは、Azure.identity ライブラリを使用してアプリケーションで認証を有効にすることによって実現できます。 ManagedIdentityCredential を直接呼び出すか、DefaultAzureCredential を使用することができます。

ManagedIdentityCredential クラスでは、デプロイ環境に割り当てられたマネージド ID を使用して認証が試行されます。 DefaultAzureCredential では、様々な認証オプションが順番に実行されます。 DefaultAzureCredential が試行する 2 番目の認証オプションが、マネージド ID です。

下の例では、データベース、コンテナー、コンテナー内の項目を作成し、仮想マシンのシステム割り当てマネージド ID を使用して、新しく作成された項目を読み戻します。 ユーザー割り当てマネージド ID を使用する場合は、マネージド ID のクライアント ID を指定して、ユーザー割り当てマネージド ID を指定する必要があります。

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() });

次に、これらのサンプルで説明されているように、データの読み取りと書き込みを行います。

クリーンアップの手順

ヒント

この記事の手順は、開始するポータルによって若干異なる場合があります。

  1. Azure portal にサインインします。

  2. 削除するリソースを選びます。

  3. [削除] を選択します。

  4. メッセージが表示されたら、削除を確定します。

次のステップ

詳細については、Azure リソースのマネージド ID について学びます。

Azure Cosmos DB の詳細を確認してください：