Azure Digital Twins インスタンスと認証を設定する (CLI)
この記事では、新しい Azure Digital Twins インスタンスを設定する手順 (インスタンスの作成と認証の設定を含む) について説明します。 この記事を完了すると、Azure Digital Twins インスタンスのプログラミングを開始する準備が整います。
新しい Azure Digital Twins インスタンスのための設定全体は、2 つの部分で構成されます。
- インスタンスの作成
- ユーザーのアクセス許可の設定: Azure ユーザーが Azure Digital Twins インスタンスとそのデータを管理するには、Azure Digital Twins データ所有者ロールが必要です。 この手順では、Azure サブスクリプションの所有者/管理者が、Azure Digital Twins インスタンスを管理することになる人にこのロールを割り当てます。 これは、自分自身のこともあれば、組織内の他の人であることもあります。
重要
このすべての記事を完了し、使用可能なインスタンスを完全に設定するには、Azure サブスクリプションのリソースとユーザーの両方へのアクセスを管理するためのアクセス許可が必要です。 最初の手順は、サブスクリプションでリソースを作成できる人であればだれでも完了できますが、2 番目の手順では、ユーザー アクセス管理のアクセス許可 (またはこれらのアクセス許可を持つ人の協力) が必要です。 この詳細については、ユーザー アクセス権限手順の「前提条件:権限の要件」セクションを参照してください。
前提条件
Azure Cloud Shell で Bash 環境を使用します。 詳細については、「Azure Cloud Shell の Bash のクイックスタート」を参照してください。
CLI リファレンス コマンドをローカルで実行する場合、Azure CLI をインストールします。 Windows または macOS で実行している場合は、Docker コンテナーで Azure CLI を実行することを検討してください。 詳細については、「Docker コンテナーで Azure CLI を実行する方法」を参照してください。
ローカル インストールを使用する場合は、az login コマンドを使用して Azure CLI にサインインします。 認証プロセスを完了するには、ターミナルに表示される手順に従います。 その他のサインイン オプションについては、Azure CLI でのサインインに関するページを参照してください。
初回使用時にインストールを求められたら、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>"
ヒント
上記のコマンドでは、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 インスタンスを作成するには、インスタンスの作成に使用する az dt create コマンドに --mi-system-assigned パラメーターを追加します。 (作成コマンドの詳細については、リファレンス ドキュメントまたは「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 リソースを設定する引き続きの操作で、必要になる可能性があります。 他のユーザーがそのインスタンスに対してプログラミングする場合は、これらの値を彼らと共有する必要があります。
ヒント
これらのプロパティは、インスタンスのすべてのプロパティと共に、az dt show --dt-name <your-Azure-Digital-Twins-instance> を実行することでいつでも確認できます。
これで、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 ソリューションのセキュリティに関するページを参照してください。
Note
このロールは、Azure Digital Twins インスタンスのスコープでも割り当てることができる Microsoft Entra ID [所有者] ロールとは異なります。 これらは 2 つの個別の管理ロールであり、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"
このコマンドの結果として、そのユーザー向けに作成されたロールの割り当てに関する情報が出力されます。
Note
このコマンドによって、CLI がグラフ データベースでユーザーまたはサービス プリンシパルを見つけることができないというエラーが返される場合は、次のことを行います。
代わりに、ユーザーの "オブジェクト ID" を使用して、ロールを割り当てます。 これは、個人の Microsoft アカウント (MSA) を使用するユーザーの場合に当てはまります。
Microsoft Entra ユーザーの Azure portal ページを使用して、ユーザー アカウントを選択し、その詳細を開きます。 ユーザーのオブジェクト ID をコピーします:
次に、前述の assignee パラメーターにユーザーの "オブジェクト ID" を使用して、ロールの割り当てリスト コマンドを繰り返します。
成功を確認する
ロールの割り当てを正常に設定したことを確認するための 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 を有効にするコマンドは、システム割り当て 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 またはそのロールに対する変更が、それを使用するリソースに及ぼす影響を考慮することが重要です。 マネージド ID を Azure Digital Twins エンドポイントまたはデータ履歴で使用している場合、ID を無効にするか、必要なロールをそれから削除すると、エンドポイントまたはデータ履歴の接続にアクセスできなくなる可能性があり、イベントのフローが中断されます。
設定されていたマネージド ID を無効にした後もエンドポイントを引き続き使用するには、エンドポイントを削除し、異なる認証の種類で再作成する必要があります。 この変更を行った後、エンドポイントへのイベントの配信が再開されるまで、最大で 1 時間かかることがあります。
次のステップ
Azure Digital Twins CLI コマンドを使用して、インスタンスでの個別の REST API 呼び出しをテストします。
または、認証コードを使ってクライアント アプリケーションをインスタンスに接続する方法を確認します。