你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
设置 Azure 数字孪生实例和身份验证 (CLI)
本文将介绍新 Azure 数字孪生实例的设置步骤，包括创建实例和设置身份验证。 完成本文操作后，即可对 Azure 数字孪生实例编程。
新的 Azure 数字孪生实例的完整设置包括两部分：
- 创建实例
- 设置用户访问权限：Azure 用户需要对 Azure 数字孪生实例具有“Azure 数字孪生数据所有者”角色，才能管理该实例及其数据。 在此步骤中，你作为 Azure 订阅的所有者/管理员需将此角色分配给将要管理 Azure 数字孪生实例的人员。 这可能是你自己或你组织中的其他人。
重要
要完成整篇文章的步骤并完全设置一个可用的实例，你需要有权限来管理 Azure 订阅上的资源和用户访问权限。 第一个步骤可以由能够在订阅上创建资源的任何人完成，但第二个步骤需要有用户访问管理权限（或具有这些权限的人的协助）。 有关详细信息，请参阅用户访问权限步骤的先决条件：所需权限部分。
先决条件
在 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 数字孪生，首先要做的是登录并将 CLI 上下文设置为此会话的订阅。 在 CLI 窗口中运行以下命令：
az login
az account set --subscription "<your-Azure-subscription-ID>"
提示
在上面的命令中，还可以使用订阅名称而不使用 ID。
如果这是你首次将此订阅与 Azure 数字孪生一起使用，请运行该命令以向 Azure 数字孪生命名空间进行注册。 （如果不确定，可以再次运行该命令，即使过去某个时候操作过也是如此。）
az provider register --namespace 'Microsoft.DigitalTwins'
接下来，添加适用于 Azure CLI 的 Microsoft Azure IoT 扩展以支持用于与 Azure 数字孪生和其他 IoT 服务进行交互的命令。 运行此命令以确保你已安装最新版本的扩展：
az extension add --upgrade --name azure-iot
现在 Azure 数字孪生已可在 Azure CLI 中使用。
若要验证 Azure 数字孪生在 Cloud Shell 中的就绪性，可以随时运行 az dt --help 查看可用的顶层 Azure 数字孪生命令列表。
创建 Azure 数字孪生实例
在本部分，你将使用 CLI 命令创建新的 Azure 数字孪生实例。 你需要提供以下信息：
- 将在其中部署实例的资源组。 如果还没有现有的资源组，可以使用以下命令立即创建一个资源组：
az group create --location <region> --name <name-for-your-resource-group> - 用于部署的区域。 若要查看哪些区域支持 Azure 数字孪生，请访问各区域的 Azure 产品可用性。
- 你的实例的名称。 如果订阅在该区域已存在使用指定名称的其他 Azure 数字孪生实例，系统会要求你选择其他的名称。
在以下 az dt 命令中使用这些值创建实例：
az dt create --dt-name <name-for-your-Azure-Digital-Twins-instance> --resource-group <your-resource-group> --location <region>
有几个可选参数可以添加到命令中，以在创建过程中指定有关资源的其他信息，包括为实例创建托管标识或启用/禁用公用网络访问。 有关支持的参数的完整列表，请参阅 az dt create 参考文档。
使用托管标识创建实例
在 Azure 数字孪生实例上启用托管标识时，在 Microsoft Entra ID 中为其创建标识。 然后，可以使用该标识向其他服务进行身份验证。 可以在创建实例时为 Azure 数字孪生实例启用托管标识，或稍后在现有实例上启用。
将下面的 CLI 命令用于所选的托管标识类型。
系统分配的标识命令
若要创建启用了系统分配的标识的 Azure 数字孪生实例，可以向用于创建实例的 az dt create 命令添加 --mi-system-assigned 参数。 （有关此创建命令的详细信息，请参阅其参考文档或有关设置 Azure 数字孪生实例的一般说明）。
若要创建具有系统分配的标识的实例，请按如下所示添加 --mi-system-assigned 参数：
az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned
用户分配的标识命令
若要创建具有用户分配的标识的实例，请使用 --mi-user-assigned 参数提供现有用户分配的标识的 ID，如下所示：
az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-user-assigned <user-assigned-identity-resource-ID>
验证是否成功并收集重要值
如果实例已成功创建，则 CLI 中的结果将如下所示，输出有关已创建资源的信息：
记下输出中 Azure 数字孪生实例的“hostName”、“name”和“resourceGroup”。 在继续使用 Azure 数字孪生实例时，可能需要使用所有这些重要的值，以便设置身份验证和相关的 Azure 资源。 如果其他用户将针对该实例进行编程，则应与他们共享这些值。
提示
你可以随时通过运行 az dt show --dt-name <your-Azure-Digital-Twins-instance> 来查看这些属性和你的实例的所有属性。
你现在已准备好 Azure 数字孪生实例。 接下来，你将向 Azure 用户授予适当的权限来管理该实例。
设置用户访问权限
Azure 数字孪生使用 Microsoft Entra ID 进行基于角色的访问控制（RBAC）。 这意味着，在用户可以对 Azure 数字孪生实例进行数据平面调用之前，需要为该用户分配具有相应权限的角色。
对于 Azure 数字孪生，此角色是“Azure 数字孪生数据所有者”。 要详细了解角色和安全性，可参阅 Azure 数字孪生解决方案的安全性。
注意
此角色不同于 Microsoft Entra ID 所有者 角色，该角色也可以在 Azure 数字孪生实例的范围内分配。 这是两个不同的管理角色，所有者不授予对数据平面功能的访问权限，而 Azure 数字孪生数据所有者则可以授予。
本部分介绍如何在 Azure 数字孪生实例中为用户创建角色分配，并在 Azure 订阅的 Microsoft Entra 租户中使用该用户的电子邮件。 根据你在组织中的角色，你可以为自己设置此权限，或者以将要管理 Azure 数字孪生实例的其他人的名义设置此权限。
先决条件：权限要求
为了能够完成所有后续步骤，你需要在订阅中有一个具有以下权限的角色：
- 创建和管理 Azure 资源
- 管理用户对 Azure 资源的访问权限（包括授予和委托权限）
满足此要求的常见角色包括“所有者”、“帐户管理员”或“用户访问管理员”和“参与者”的组合。 有关角色和权限的完整说明，包括其他角色中包含的权限、访问 Azure 角色、Microsoft Entra 角色和 Azure RBAC 文档中的经典订阅管理员角色 。
若要查看你在订阅中的角色，请访问 Azure 门户中的订阅页（你可以使用此链接，也可以通过门户搜索栏查找“订阅”）。 查找你正在使用的订阅的名称，然后在“我的角色”列中查看你在该订阅中的角色：
如果你发现值是“参与者”，或者是其他没有上述所需权限的角色，可以联系对订阅具有这些权限的用户（例如订阅所有者或帐户管理员），并按以下方式之一继续操作：
- 请求他们以你的名义完成角色分配步骤。
- 请求他们提升你在订阅中的角色，以便你有权自行继续执行。 这是否合适取决于你的组织和你在其中的角色。
分配角色
若要授予用户管理 Azure 数字孪生实例的权限，必须在实例中为他们分配“Azure 数字孪生数据所有者”角色。
使用以下命令来分配角色（必须由在 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"
此命令的结果是有关已为用户创建的角色分配的输出信息。
注意
如果此命令返回一个错误，指出 CLI 在 graph 数据库中找不到用户或服务主体：
请改为使用用户的对象 ID 来分配角色。 对于使用个人 Microsoft 帐户 (MSA) 的用户，可能会发生这种情况。
使用 Microsoft Entra 用户的Azure 门户页选择用户帐户并打开其详细信息。 复制用户的“对象 ID”：
然后，重复执行角色分配列表命令，将用户的对象 ID 用于上面的 assignee 参数。
验证是否成功
检查是否已成功设置角色分配的一种方法是在 Azure 门户中查看 Azure 数字孪生实例的角色分配。 在 Azure 门户中查看 Azure 数字孪生实例。 为此，可以在 Azure 数字孪生实例页上查找，也可以在门户搜索栏中搜索其名称。
然后，在“访问控制(IAM)”>“角色分配”下查看已分配的所有角色。 角色分配应显示在列表中。
现在，你已准备好 Azure 数字孪生实例，并分配了管理权限。
为实例启用/禁用托管标识
本部分介绍如何将托管标识添加到已存在的 Azure 数字孪生实例。 此外，还可以对已经拥有托管标识的实例禁用托管标识。
将下面的 CLI 命令用于所选的托管标识类型。
系统分配的标识命令
用于为现有实例启用系统分配的标识的命令与用于创建具有系统分配的标识的新实例的 az dt create 命令相同。 无需提供要创建的实例的新名称，而可以提供现存实例的名称。 然后，请确保添加 --mi-system-assigned 参数。
az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned
若要在当前已启用系统分配的标识的实例上禁用它，请使用下面的命令将 --mi-system-assigned 设置为 false。
az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned false
用户分配的标识命令
若要在现有实例上启用用户分配的标识，请在以下命令中提供现有用户分配的标识的 ID：
az dt identity assign --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>
若要在当前已启用用户分配的标识的实例上禁用它，请在以下命令中提供标识的 ID：
az dt identity remove --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>
有关禁用托管标识的注意事项
请务必考虑对标识或其角色所做的任何更改会对使用该标识的资源产生的影响。 如果将托管标识用于 Azure 数字孪生终结点或用于数据历史记录，并且标识已禁用，或者从中删除了必要的角色，则终结点或数据历史记录连接可能会变得不可访问，并且事件流将中断。
若要继续使用某个终结点，而该终结点是使用现已禁用的托管标识设置的，则需要删除该终结点，然后使用不同的身份验证类型重新创建它。 做出此项更改后，最长可能需要经过一小时，事件才会继续传送到终结点。
后续步骤
使用 Azure 数字孪生 CLI 命令在实例上测试各个 REST API 调用：
或者，了解如何使用验证码将客户端应用程序连接到实例：