你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

在 Azure 数字孪生中创建终结点

项目
04/06/2023

本文介绍如何使用 Azure 门户或 Azure CLI 为 Azure 数字孪生事件创建终结点。还可以使用 DigitalTwinsEndpoint 控制平面 API 管理终结点。

将事件通知从 Azure 数字孪生路由到下游服务或连接的计算资源分为两个步骤：创建终结点，然后创建事件路由以将数据发送到这些终结点。本文介绍第一个步骤：设置可以接收事件的终结点。然后，可创建事件路由来指定由 Azure 数字孪生生成的哪些事件传递到哪些终结点。

先决条件

你需要一个 Azure 帐户（可免费设置一个）
在 Azure 订阅中需要一个“Azure 数字孪生实例”。如果还没有实例，可以使用设置实例和身份验证中的步骤创建一个。准备好以下设置值，以便稍后在本文中使用：
- 实例名称
- 资源组
设置实例后，可以在 Azure 门户中找到这些详细信息。

接下来，若要遵循本指南的要求来使用 Azure CLI，请按以下说明操作。

为 Azure CLI 准备环境

在 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。

创建所需资源

以下服务是可为实例创建的受支持的终结点类型：

事件网格主题
- 对于事件网格终结点，只支持事件网格主题。不支持将事件网格域作为终结点。
事件中心中心
服务总线主题

若要将终结点链接到 Azure 数字孪生，需具备将用于终结点的事件网格主题、事件中心或服务总线主题。

使用下图查看在创建终结点之前应该设置的资源。

终结点类型	所需的资源（已链接到创建说明）
事件网格终结点	事件网格主题 \* 事件架构必须是事件网格架构或云事件架构 v1.0
事件中心终结点	事件中心命名空间事件中心（可选）基于密钥的身份验证的授权规则
Service Bus 终结点	服务总线命名空间服务总线主题（可选）基于密钥的身份验证的授权规则

创建终结点

创建终结点资源后，就可以将其用于 Azure 数字孪生终结点。

门户
CLI

要创建新的终结点，请在 Azure 门户中转到实例页面（可以通过在门户搜索栏中输入名称来查找实例）。

从实例菜单中选择“终结点”。然后，在显示的“终结点”页选择“+ 创建终结点”。这样做将打开“创建终结点”页，可在该页面中按以下步骤填写字段。
输入终结点的“名称”，并选择“终结点类型”。
完成终结点类型所需的其他详细信息，包括订阅和前文所述的终结点资源。
1. 只有“事件中心”和“服务总线”终结点必须选择“身份验证类型”。可以将基于密钥的身份验证与预先创建的授权规则，或者系统分配或用户分配的托管标识一起使用。有关使用标识身份验证选项的详细信息，请参阅终结点选项：基于标识的身份验证。
选择“保存”，完成终结点创建。

创建终结点后，可以通过查看 Azure 门户顶部栏中的通知图标来验证是否已成功创建终结点：

指示验证 Azure 门户中终结点的创建的通知的屏幕截图。

如果终结点创建失败，可查看错误消息并在几分钟后重试。

还可以返回 Azure 数字孪生实例的“终结点”页上查看已创建的终结点。

目前，根据为终结点所选的名称，可使用事件网格主题、事件中心或服务总线主题作为 Azure 数字孪生中的终结点。通常使用该名称作为事件路由（可在创建路由和筛选器中创建）的目标。

以下示例演示如何使用 Azure 数字孪生 CLI 的 az dt endpoint create 命令创建终结点。将命令中的占位符替换为你自己的资源的详细信息。

创建事件网格终结点：

az dt endpoint create eventgrid --endpoint-name <Event-Grid-endpoint-name> --eventgrid-resource-group <Event-Grid-resource-group-name> --eventgrid-topic <your-Event-Grid-topic-name> --dt-name <your-Azure-Digital-Twins-instance-name>

创建事件中心终结点（基于密钥的身份验证）：

az dt endpoint create eventhub --endpoint-name <Event-Hub-endpoint-name> --eventhub-resource-group <Event-Hub-resource-group> --eventhub-namespace <Event-Hub-namespace> --eventhub <Event-Hub-name> --eventhub-policy <Event-Hub-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

创建服务总线主题终结点（基于密钥的身份验证）：

az dt endpoint create servicebus --endpoint-name <Service-Bus-endpoint-name> --servicebus-resource-group <Service-Bus-resource-group-name> --servicebus-namespace <Service-Bus-namespace> --servicebus-topic <Service-Bus-topic-name> --servicebus-policy <Service-Bus-topic-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

成功运行这些命令后，事件网格主题、事件中心或服务总线主题将作为 Azure 数字孪生中的终结点提供，以你通过 --endpoint-name 参数提供的名称命名。通常使用该名称作为事件路由（可在创建路由和筛选器中创建）的目标。

终结点选项：基于标识的身份验证

本部分介绍如何在将事件转发到受支持的路由目标时，使用 Azure 数字孪生实例的托管标识。虽然路由不强制要求设置托管标识，但它可以帮助实例轻松访问其他受 Microsoft Entra 保护的资源，例如事件中心、服务总线目标和 Azure 存储容器。托管标识可以是系统分配或用户分配的标识。

本部分的其余部分逐步讲解设置具有托管标识的终结点的三个步骤。

1.为实例启用托管标识

使用下面的选项卡获取与首选体验匹配的说明。

Portal
CLI

首先，请确保为 Azure 数字孪生实例启用了托管标识。

另请确保实例上已有“Azure 数字孪生数据所有者”角色。可以在设置用户访问权限中找到说明。

2.将 Azure 角色分配给标识

为 Azure 数字孪生实例创建托管标识后，需要为其分配适当的角色来通过不同类型的终结点进行身份验证，以将事件路由到受支持的目标。本部分将介绍角色选项，以及如何将它们分配给托管标识。

重要

请确保完成此步骤。如果不执行此步骤，标识将无法访问终结点，并且不会传送事件。

下面是 Azure 数字孪生标识访问终结点所需的最低角色，具体取决于目标类型。分配权限更高的角色（例如“数据所有者”角色）也同样起作用。

目标	Azure 角色
Azure 事件中心	Azure 事件中心数据发送方
Azure 服务总线	Azure 服务总线数据发送方
Azure 存储容器	存储 Blob 数据参与者

通过下面的选项卡使用首选体验分配角色。

Portal
CLI

要为标识分配角色，请先在浏览器中打开 Azure 门户。

在门户搜索栏中搜索你的终结点资源（事件中心、服务总线主题或存储容器）名称并导航到该资源。
选择“访问控制 (IAM)”。
选择“添加”>“添加角色分配”，打开“添加角色分配”页面。

使用以下信息将所需角色分配给 Azure 数字孪生实例的托管标识。有关详细步骤，请参阅使用 Azure 门户分配 Azure 角色。

设置	值
角色	从选项中选择所需的角色。
将访问权限分配到	托管的标识
成员	在此处选择要为其分配角色的 Azure 数字孪生实例的用户分配或系统分配的托管标识。用户分配的标识将具有创建标识时选择的名称，系统分配的标识的名称将与 Azure 数字孪生实例的名称匹配。

可将 --scopes 参数添加到 az dt create 命令，将该标识分配到一个或多个具有指定角色的范围。你可在首次创建实例时使用这个带有此参数的命令，也可稍后通过传入已存在的实例的名称来使用。

以下示例创建一个具有系统分配的托管标识的实例，并在事件中心为该标识分配一个名为 MyCustomRole 的自定义角色。

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned --scopes "/subscriptions/<subscription ID>/resourceGroups/<resource-group>/providers/Microsoft.EventHub/namespaces/<Event-Hubs-namespace>/eventhubs/<event-hub-name>" --role MyCustomRole

有关使用此命令进行角色分配的更多示例，请参阅 az dt create 参考文档。

也可使用 az role assignment 命令组来创建和管理角色。此命令可用于支持你不想使用 create 命令进行组角色分配的其他场景。

3.创建使用基于标识的身份验证的终结点

为 Azure 数字孪生实例设置托管标识并为其分配适当的角色后，可以创建使用该标识进行身份验证的终结点。此选项仅适用于事件中心和服务总线类型终结点（事件网格不支持此选项）。

注意

对于已使用基于密钥的标识创建的终结点，不能通过对其进行编辑来将其更改为使用基于标识的身份验证。必须选择最初创建终结点时指定的身份验证类型。

通过下面的选项卡使用首选体验创建终结点。

Portal
CLI

请按照有关创建 Azure 数字孪生终结点的一般说明开始操作。

完成终结点类型所需的详细信息的步骤时，请为“身份验证类型”选择“系统分配”或“用户分配（预览版）”。

完成终结点设置，然后选择“保存”。

通过将参数添加到用于创建终结点的 az dt endpoint create 命令，即可将托管标识添加到终结点。（有关此命令的详细信息，请参阅其参考文档或有关创建 Azure 数字孪生终结点的一般说明）。

将下面的 CLI 命令用于所选的托管标识类型。

系统分配的标识命令

若要创建使用系统分配的身份验证的终结点，请使用 --auth-type 参数指定 IdentityBased 身份验证类型。以下示例演示了如何对事件中心终结点使用此功能。

az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --auth-type IdentityBased

用户分配的标识命令

若要创建使用用户分配的身份验证的终结点，请使用 --user 参数指定用户分配的标识资源 ID。以下示例演示了如何对事件中心终结点使用此功能。

az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --user <user-assigned-identity-resource-ID>

有关禁用托管标识的注意事项

由于标识与使用该标识的终结点是分开管理的，因此必须考虑到对标识或其角色做出的任何更改可能给 Azure 数字孪生实例中的终结点造成的影响。如果禁用标识或者从中删除某个终结点的必要角色，终结点可能变得不可访问，并且事件流将会中断。

若要继续使用某个终结点，而该终结点是使用现已禁用的托管标识设置的，则需要删除该终结点，然后使用不同的身份验证类型重新创建它。做出此项更改后，最长可能需要经过一小时，事件才会继续传送到终结点。

终结点选项：死信

当终结点无法在特定时间段内传递事件，或在尝试传递事件一定次数后仍无法传递，它可将未传递的事件发送到存储帐户。此过程称为“死信处理”。

可以使用 Azure 门户或 Azure 数字孪生 CLI 来设置必需的存储资源。但是，若要创建一个启用了死信的终结点，需使用 Azure 数字孪生 CLI 或控制平面 API。

若要详细了解死信，请参阅终结点和事件路由。有关如何设置使用死信的终结点的说明，请继续阅读本部分的其余内容。

设置存储资源

在设置死信位置之前，必须在 Azure 帐户中设置一个带有容器的存储帐户。

稍后创建终结点时，需要提供此容器的 URI。死信位置将作为带有 SAS 令牌的容器 URI 提供给终结点。该令牌需要存储帐户中目标容器的 write 权限。完全格式化的死信 SAS URI 的格式为：https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>。

按照以下步骤在 Azure 帐户中设置这些存储资源，为在下一部分中设置终结点连接做准备。

按照创建存储帐户中的步骤，在 Azure 订阅中创建一个存储帐户。记下存储帐户名以便以后使用。
按照创建容器中的步骤，在新的存储帐户中创建一个容器。记下容器名称以便以后使用。

创建 SAS 令牌

接下来，为存储帐户创建一个 SAS 令牌，终结点可以使用该令牌来访问它。

门户
CLI

首先导航到 Azure 门户中的存储帐户（可以通过门户搜索栏按名称找到它）。
在存储帐户页面中，选择左侧导航栏中的“共享访问签名”链接以开始设置 SAS 令牌。
在“共享访问签名”页的“允许的服务”和“允许的资源类型”下，选择所需的任何设置。需要在每个类别中至少选择一个框。在“允许的权限”下，选择“写入”（如果需要，还可以选择其他权限）。
对于其余的设置，设置所需的任何值。
完成后，选择“生成 SAS 和连接字符串”按钮来生成 SAS 令牌。
这样做将在同一个页面底部的各设置选项下生成几个 SAS 和连接字符串值。向下滚动以查看这些值，并使用“复制到剪贴板”图标复制“SAS 令牌”值。保存它以供以后使用。

使用以下命令检索存储帐户密钥，并复制其中一个密钥的值：
```
az storage account keys list --account-name <storage-account-name>
```
使用以下命令选择到期日期，为存储帐户生成 SAS 令牌：
```
az storage account generate-sas --account-name <storage-account-name> --account-key <storage-account-key> --expiry <expiration-date> --services bfqt --resource-types o --permissions w
```
此命令的输出为 SAS 令牌。复制 SAS 令牌值供稍后使用。

注意

此命令包含“blob”、“file”（文件）、“queue”（队列）和“table”（表）服务和一个“object”（对象）资源类型，并允许“write”（写入）权限。

有关 az storage account generate-sas 命令及其参数的详细信息，请参阅 Azure CLI 参考。

若要创建启用死信的终结点，必须使用 CLI 命令或控制平面 API 来创建终结点，而不是 Azure 门户。

有关如何使用 Azure CLI 创建此类终结点的说明，请切换到此部分的“CLI”选项卡。

若要创建一个启用了死信的终结点，请将 --deadletter-sas-uri 参数添加到用于创建终结点的 az dt endpoint create 命令中。

参数的值是“死信 SAS URI”，由你在上一部分中收集的存储帐户名、容器名和 SAS 令牌组成。此参数创建使用基于密钥的身份验证的终结点。该参数如下所示：

--deadletter-sas-uri https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>

提示

若要创建使用基于标识的身份验证的死信终结点，请将本节中的死信参数和相应的托管标识参数添加到同一命令。

也可以使用 Azure 数字孪生控制平面 API 而不是 CLI 创建死信终结点。为此，请查看 DigitalTwinsEndpoint 文档，了解如何构造请求并添加死信参数。

消息存储架构

设置了使用死信的终结点后，经过死信处理的消息将采用以下格式存储在存储帐户中：

<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json

经过死信处理的消息将与打算传递到原始终结点的原始事件的架构匹配。

下面是孪生体创建通知的死信消息示例：

{
  "specversion": "1.0",
  "id": "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "Microsoft.DigitalTwins.Twin.Create",
  "source": "<your-instance>.api.<your-region>.da.azuredigitaltwins-test.net",
  "data": {
    "$dtId": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "$etag": "W/\"xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx\"",
    "TwinData": "some sample",
    "$metadata": {
      "$model": "dtmi:test:deadlettermodel;1",
      "room": {
        "lastUpdateTime": "2020-10-14T01:11:49.3576659Z"
      }
    }
  },
  "subject": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "time": "2020-10-14T01:11:49.3667224Z",
  "datacontenttype": "application/json",
  "traceparent": "00-889a9094ba22b9419dd9d8b3bfe1a301-f6564945cb20e94a-01"
}

后续步骤

若要实际地将数据从 Azure 数字孪生发送到终结点，需要定义一个事件路由。通过这些路由，开发人员可在整个系统中串联事件流并连接到下游服务。单一路由可允许选择多个通知和事件类型。继续在创建路由和筛选器中创建到终结点的事件路由。

通过