Azure Digital Twins インスタンスと認証を設定する (CLI)

この記事では、新しい Azure Digital Twins インスタンスを設定する手順 (インスタンスの作成と認証の設定を含む) について説明します。 この記事を完了すると、Azure Digital Twins インスタンスのプログラミングを開始する準備が整います。

新しい Azure Digital Twins インスタンスのための設定全体は、2 つの部分で構成されます。

1. インスタンスの作成。
2. ユーザーのアクセス許可の設定: Azure ユーザーが Azure Digital Twins インスタンスとそのデータを管理するには、Azure Digital Twins データ所有者ロールが必要です。 この手順では、Azure サブスクリプションの所有者または管理者として、Azure Digital Twins インスタンスを管理するユーザーにこのロールを割り当てます。 このユーザーは、自分または組織内の他のユーザーである可能性があります。

前提条件

• Azure Cloud Shell で Bash 環境を使用します。 詳細については、「Azure Cloud Shell の概要」を参照してください。

  

• CLI リファレンス コマンドをローカルで実行する場合、Azure CLI をインストールします。 Windows または macOS で実行している場合は、Docker コンテナーで Azure CLI を実行することを検討してください。 詳細については、「Docker コンテナーで Azure CLI を実行する方法」を参照してください。

  • ローカル インストールを使用する場合は、az login コマンドを使用して Azure CLI にサインインします。 認証プロセスを完了するには、ターミナルに表示される手順に従います。 その他のサインイン オプションについては、「 Azure CLI を使用した Azure への認証」を参照してください。

  • 初回使用時にインストールを求められたら、Azure CLI 拡張機能をインストールします。 拡張機能の詳細については、「Azure CLI で拡張機能を使用および管理する」を参照してください。

  • az version を実行し、インストールされているバージョンおよび依存ライブラリを検索します。 最新バージョンにアップグレードするには、az upgrade を実行します。

CLI セッションを設定する

CLI で Azure Digital Twins の使用を開始するには、まずサインインし、このセッションのサブスクリプションに CLI コンテキストを設定します。 CLI ウィンドウでこれらのコマンドを実行します。

az login
az account set --subscription "<your-Azure-subscription-ID>"

Azure Digital Twins でこのサブスクリプションを初めて使用する場合は、次のコマンドを実行して Azure Digital Twins 名前空間に登録します。 (不明な場合は、過去に実行した場合でも、もう一度実行してもかまいません)。

az provider register --namespace 'Microsoft.DigitalTwins'

次に、 Azure CLI 用の Microsoft Azure IoT 拡張機能を追加して、Azure Digital Twins やその他の IoT サービスと対話するためのコマンドを有効にします。 このコマンドを実行して、最新バージョンの拡張機能がインストールされていることを確認します。

az extension add --upgrade --name azure-iot

これで、Azure CLI で Azure Digital Twins を使用する準備ができました。

この状態を確認するには、 az dt --help をいつでも実行して、使用可能な最上位レベルの Azure Digital Twins コマンドの一覧を表示します。

Azure Digital Twins インスタンスを作成する

このセクションでは、CLI コマンドを使用して、Azure Digital Twins の新しいインスタンスを作成します。 以下を指定する必要があります。

• インスタンスがデプロイされるリソース グループ。 既存のリソース グループをまだ念頭に置いていない場合は、次のコマンドを使用して作成できます。

  az group create --___location <region> --name <name-for-your-resource-group>
  

• デプロイのためのリージョン。 Azure Digital Twins がどのリージョンでサポートされているかを確認するには、リージョン別の利用可能な Azure 製品に関するページを参照してください。
• インスタンスの名前。 指定した名前を既に使用しているリージョンにサブスクリプションに別の Azure Digital Twins インスタンスがある場合は、別の名前を選択するように求められます。

これらの値を使用して、az dt command コマンドでインスタンスを作成します。

az dt create --dt-name <name-for-your-Azure-Digital-Twins-instance> --resource-group <your-resource-group> --___location <region>

インスタンスのマネージド ID の作成やパブリック ネットワーク アクセスの有効化/無効化など、作成時にリソースに関するその他のものを指定するために、コマンドに追加できる省略可能なパラメーターがいくつかあります。 サポートされているすべてのパラメーターの一覧については、az dt create のリファレンス ドキュメントを参照してください。

マネージド ID を使用してインスタンスを作成する

Azure Digital Twins インスタンスでマネージド ID を有効にすると、Microsoft Entra ID で ID が作成されます。 その ID を使用して、他のサービスに対する認証を行うことができます。 Azure Digital Twins インスタンスのシステム マネージド ID は、インスタンスの作成時に有効にすることも、後で既存のインスタンスで有効にすることもできます。

選択した種類のマネージド ID に対して、次の CLI コマンドを使用します。

システム割り当て ID コマンド

システム割り当て ID が有効になっている Azure Digital Twins インスタンスを作成するには、インスタンスの作成に使用する --mi-system-assigned コマンドに az dt create パラメーターを追加します。 (作成コマンドの詳細については、リファレンス ドキュメントまたは「Azure Digital Twins インスタンスを設定するための一般的な手順」に関する記事を参照してください)。

システム 割り当て ID を持つインスタンスを作成するには、次のように --mi-system-assigned パラメーターを追加します。

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned

ユーザー割り当て ID コマンド

ユーザー割り当て ID を持つインスタンスを作成するには、--mi-user-assigned パラメーターを使用して、既存のユーザー割り当て ID の ID を次のように指定します。

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-user-assigned <user-assigned-identity-resource-ID>

正常に実行されたことを確認して重要な値を収集する

インスタンスが正常に作成された場合、CLI の結果は次のようになります。作成したリソースに関する情報が出力されます。

Azure Digital Twins インスタンスの hostName、name、resourceGroup を出力から確認します。 これらの値はすべて重要であり、Azure Digital Twins インスタンスを引き続き使用して認証と関連する Azure リソースを設定するときに、それらを使用する必要がある場合があります。 他のユーザーがインスタンスに対してプログラミングを行っている場合は、これらの値をそれらのユーザーと共有する必要があります。

これで、Azure Digital Twins インスタンスの準備が完了しました。 次に、それを管理するための適切な Azure ユーザーアクセス許可を付与します。

ユーザーのアクセス許可を設定する

Azure Digital Twins では、Microsoft Entra ID をロールベースのアクセス制御 (RBAC) に使用します。 つまり、ユーザーが Azure Digital Twins インスタンスへのデータ プレーン呼び出しを行うには、そのための適切なアクセス許可を持つロールをそのユーザーに割り当てておく必要があります。

Azure Digital Twins の場合、このロールは "Azure Digital Twins Data Owner" (Azure Digital Twins データ所有者) です。 ロールとセキュリティの詳細については、Azure Digital Twins ソリューションのセキュリティに関するページを参照してください。

このセクションでは、Azure サブスクリプションの Microsoft Entra テナントでそのユーザーの電子メールを使用して、Azure Digital Twins インスタンス内のユーザーのロールの割り当てを作成する方法について説明します。 組織内のロールに応じて、このアクセス許可を自分用に設定するか、Azure Digital Twins インスタンスを管理する他のユーザーに代わって設定することができます。

前提条件: 権限の要件

あなたのサブスクリプションでは、次のアクセス許可を持つロールが必要です。次のすべての手順を実行するにはそれが必要です。

• Azure リソースのデプロイおよび管理
• Azure リソースへのユーザー アクセスの管理 (アクセス許可の付与と委任を含む)

この要件を満たす一般的なロールは、所有者、アカウント管理者、ユーザー アクセス管理者と共同作成者の組み合わせです。 ロールや権限について、特に他のロールに含まれる権限の詳細説明については、Azure RBAC のドキュメントにある「Azure ロール、Microsoft Entra ロール、従来のサブスクリプション管理者ロール」をご参照ください。

ご自分のサブスクリプションのロールを確認するには、Azure portal 上のサブスクリプション ページにアクセスします (このリンクを使用するか、ポータルの検索バーを使って サブスクリプション を検索できます)。 使用しているサブスクリプションの名前を検索し、それに対応するロールを [自分の役割] 列で確認します:

その値が共同作成者、または前述した必要なアクセス許可を持たない別のロールである場合は、こうしたアクセス許可を持つサブスクリプションのユーザー (サブスクリプションの所有者やアカウント管理者など) に問い合わせて、次のいずれかの方法で続行することができます:

• 自分の代わりにロール割り当て手順を完了してもらうように依頼する。
• 自身で続行するためのアクセス許可が付与されるよう、サブスクリプションのロールを昇格するように依頼します。 この要求が適切かどうかは、組織とその中のユーザーの役割によって異なります。

ロールを割り当てる

ユーザーに Azure Digital Twins インスタンスを管理するためのアクセス許可を付与するには、そのインスタンス内の Azure Digital Twins データ所有者ロールをそのユーザーに割り当てる必要があります。

ロールを割り当てるには、次のコマンドを使用します。 Azure サブスクリプションで 十分なアクセス許可 を持つユーザーがコマンドを実行する必要があります。 このコマンドを実行するには、ロールを割り当てる必要があるユーザーの Microsoft Entra アカウントで、"ユーザー プリンシパル名" を渡す必要があります。 ほとんどの場合、この値は Microsoft Entra アカウントのユーザーの電子メールと一致します。

az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<Azure-AD-user-principal-name-of-user-to-assign>" --role "Azure Digital Twins Data Owner"

このコマンドの結果は、ユーザーに対して作成されたロールの割り当てに関する情報を出力します。

成功を確認する

ロールの割り当てを正常に設定したことを確認するための 1 つの方法として、Azure portal で Azure Digital Twins インスタンスのロールの割り当てを表示します。

Azure portal で Azure Digital Twins インスタンスに移動します。 そこに移動するには、Azure Digital Twins インスタンスのページで検索するか、ポータルの検索バーでその名前を検索します。

次に、[アクセス制御 (IAM)] > [ロールの割り当て] で、それに割り当てられているすべてのロールを表示します。 ロールの割り当てが一覧に表示されます。

これで、Azure Digital Twins インスタンスの準備が完了し、これを管理するためのアクセス許可が割り当てられました。

インスタンスのマネージド ID を有効または無効にする

このセクションでは、既に存在する Azure Digital Twins インスタンスにマネージド ID を追加する方法について説明します。 インスタンスに既に存在するマネージド ID を無効にすることもできます。

選択した種類のマネージド ID に対して、次の CLI コマンドを使用します。

システム割り当て ID コマンド

既存のインスタンスのシステム割り当て ID を有効にするコマンドは、az dt createために使用されるのと同じ コマンドです。 作成するインスタンスの新しい名前を指定する代わりに、既に存在するインスタンスの名前を指定できます。 その場合、--mi-system-assigned パラメーターを必ず追加してください。

az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned

現在有効になっているインスタンスでシステム割り当て ID を無効にするには、次のコマンドを使用して --mi-system-assigned を false に設定します。

az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned false

ユーザー割り当て ID コマンド

既存のインスタンスでユーザー割り当て ID を有効にするには、次のコマンドで既存のユーザー割り当て ID の ID を指定します。

az dt identity assign --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>

現在有効になっているインスタンスでユーザー割り当て ID を無効にするには、次のコマンドで ID の ID を指定します。

az dt identity remove --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>

マネージド ID を無効にする場合の考慮事項

ID またはそのロールに対する変更が、それを使用するリソースに及ぼす影響を考慮することが重要です。 Azure Digital Twins エンドポイントでマネージド ID を使用している場合、またはデータ履歴に ID が無効になっている場合、または必要なロールが無効になっている場合、エンドポイントまたはデータ履歴の接続にアクセスできなくなり、イベントのフローが中断される可能性があります。

現在無効になっているマネージド ID で設定されたエンドポイントを引き続き使用するには、エンドポイントを削除し、別の認証の種類 で再作成 する必要があります。 この変更後、イベントがエンドポイントへの配信を再開するまでに最大 1 時間かかる場合があります。

次のステップ

Azure Digital Twins CLI コマンドを使用して、インスタンスでの個別の REST API 呼び出しをテストします。

• AZ DT リファレンス
• Azure Digital Twins CLI コマンド セット

または、認証コードを使ってクライアント アプリケーションをインスタンスに接続する方法を確認します。

• クライアント アプリ認証コードを記述する