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

在 Azure 数字孪生中创建事件路由和筛选器

项目
01/03/2024

本文指导你完成使用 Azure 门户、Azure CLI az dt route 命令、事件路由数据平面 API 和 .NET (C#) SDK 创建事件路由的过程。

将事件通知从 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。

创建事件路由

创建终结点后，需要定义事件路由，以将数据发送到终结点。通过这些路由，开发人员可在整个系统中串联事件流并连接到下游服务。单一路由可允许选择多个通知和事件类型。有关事件路由的详细信息，请参阅终结点和事件路由。

注意

在继续创建路由之前，请确保你已创建至少一个终结点，如先决条件中所述。

如果你最近才部署了终结点，在尝试将它们用于新的事件路由之前，请验证它们是否已完成部署。如果由于终结点未就绪而导致路由部署失败，请等待几分钟，然后重试。

如果要编写此流的脚本，你可能希望为终结点服务完成部署留出 2-3 分钟的等待时间，然后再继续进行路由设置，从而解决此问题。

路由定义可包含以下元素：

要使用的路由名称
要使用的终结点名称
一个筛选器，用于定义发送到终结点的事件
- 若要禁用路由而不发送事件，请使用筛选器值 false
- 若要启用未指定筛选条件的路由，请使用筛选器值 true
- 有关任何其他类型的筛选器的详细信息，请参阅下面的筛选器事件部分

如果没有路由名称，则不会在 Azure 数字孪生之外路由任何消息。如果存在路由名称且筛选器为 true，则所有消息都将路由到终结点。如果存在路由名称并添加了不同的筛选器，则将根据筛选器筛选消息。

可使用 Azure 门户、EventRoutes 数据平面 API 或 az dt route CLI 命令来创建事件路由。本部分的其余内容将介绍创建过程。

若要创建事件路由，请在 Azure 门户中转到 Azure 数字孪生实例的详细信息页（可以通过在门户搜索栏中输入名称来查找实例）。

从实例菜单中选择“事件路由”。然后，在显示的“事件路由”页选择“+ 创建事件路由”。

在打开的“创建事件路由”页上，至少选择以下项目：

“名称”字段的路由名称
要用于创建路由的终结点

要启用该路由，还必须“添加事件路由筛选器”，其值至少为 true。（保留默认值 false 会创建路由，但不会向其发送事件。）为此，请切换“高级编辑器”的开关将其启用，并在“筛选器”框中写入 true。

完成后，选择“保存”按钮创建事件路由。

此部分介绍如何使用 .NET (C#) SDK 创建事件路由。

CreateOrReplaceEventRouteAsync 是用于添加事件路由的 SDK 调用。下面是它的用法示例：

string eventFilter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'";
var er = new DigitalTwinsEventRoute("endpointName", eventFilter);
await client.CreateOrReplaceEventRouteAsync("routeId", er);

提示

所有 SDK 函数都提供同步和异步版本。

事件路由示例 SDK 代码

下面的示例方法演示如何使用 C# SDK 创建、列出和删除事件路由：

public static async Task CreateEventRouteAsync(DigitalTwinsClient client, string routeId, DigitalTwinsEventRoute er)
{
    try
    {
        Console.WriteLine("Create a route: testRoute1");

        // Make a filter that passes everything
        er.Filter = "true";
        await client.CreateOrReplaceEventRouteAsync(routeId, er);
        Console.WriteLine("Create route succeeded.");

        // List routes
        AsyncPageable<DigitalTwinsEventRoute> results = client.GetEventRoutesAsync();
        await foreach (DigitalTwinsEventRoute route in results)
        {
            Console.WriteLine($"Route {route.Id} to endpoint {route.EndpointName} with filter {route.Filter} ");
        }

        // Delete route created earlier
        Console.WriteLine($"Deleting route {routeId}:");
        await client.DeleteEventRouteAsync(routeId);
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"*** Error in event route processing ({e.ErrorCode}):\n${e.Message}");
    }
}

筛选事件

如上所述，路由包含“筛选器”字段。如果路由上的筛选器值为 false，则不会向终结点发送任何事件。

启用最小筛选器 true 后，终结点将从 Azure 数字孪生接收不同类型的事件：

遥测，由数字孪生使用 Azure 数字孪生服务 API 触发
孪生属性更改通知，在 Azure 数字孪生实例中的任何孪生属性更改时触发
生命周期事件，在创建或删除孪生体或关系时触发

可以通过定义更具体的筛选器来限制将发送的事件类型。

注意

筛选器区分大小写，并需要与有效负载大小写匹配。对于遥测筛选器，这意味着大小写需要与设备发送的遥测中的大小写匹配。

Portal
API

若要在创建事件路由时添加事件筛选器，请使用“创建事件路由”页的“添加事件路由筛选器”部分。

可以从一些基本的常用筛选器选项中选择，也可以使用高级筛选器选项编写自己的自定义筛选器。

使用基本筛选器

若要使用基本筛选器，请展开“事件类型”选项，并选择与要发送到终结点的事件对应的复选框。

这样做会在筛选器文本框中自动填充所选筛选器的文本：

使用高级筛选器

也可以使用高级筛选器选项来编写自己的自定义筛选器。

要使用高级筛选器选项创建事件路由，请切换“高级筛选器”的开关将其启用。然后，则可以在“筛选器”框中编写自己的事件筛选器：

可以使用事件路由数据平面 API 编写自定义筛选器。若要添加筛选器，可对 https://<Your-Azure-Digital-Twins-host-name>/eventRoutes/<event-route-name>?api-version=2020-10-31 使用 PUT 请求，正文如下：

{
    "endpointName": "<endpoint-name>",
    "filter": "<filter-text>"
}

支持的路由筛选器

下面是受支持的路由筛选器。

筛选器名称	说明	筛选文本架构	支持的值
True/False	允许创建无筛选的路由，或禁用路由，这样就不会发送事件	`<true/false>`	`true` = 启用无筛选的路由 `false` = 禁用路由
类型	流经数字孪生体实例的事件类型	`type = '<event-type>'`	以下是可能的事件类型值： `Microsoft.DigitalTwins.Twin.Create` `Microsoft.DigitalTwins.Twin.Delete` `Microsoft.DigitalTwins.Twin.Update` `Microsoft.DigitalTwins.Relationship.Create` `Microsoft.DigitalTwins.Relationship.Update` `Microsoft.DigitalTwins.Relationship.Delete` `microsoft.iot.telemetry`
源	Azure 数字孪生实例的名称	`source = '<host-name>'`	以下是可能的主机名值：用于通知：`<your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net` 用于遥测：`<your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>`
使用者	上述事件源上下文中事件的说明	`subject = '<subject>'`	以下是可能的使用者值：对于通知：使用者为 `<twin-ID>` 或使用者的 URI 格式（由多个部件或 ID 唯一标识）： `<twin-ID>/relationships/<relationship-ID>` 对于遥测：使用者是组件路径（如果遥测是从一个孪生体组件发出的），例如 `comp1.comp2`。如果遥测不是从组件发出的，则其使用者字段为空。
数据架构	DTDL 模型 ID	`dataschema = '<model-dtmi-ID>'`	对于遥测：数据架构是孪生体或发出遥测的组件的模型 ID。例如 `dtmi:example:com:floor4;2` 对于通知（创建/删除）：可以通过 `$body.$metadata.$model` 访问通知正文中的数据架构。对于通知（更新）：可以通过 `$body.modelId` 访问通知正文中的数据架构
内容类型	数据值的内容类型	`datacontenttype = '<content-type>'`	内容类型为 `application/json`
规范版本	所使用的事件架构的版本	`specversion = '<version>'`	版本必须为 `1.0`。此值指示 CloudEvents 架构版本 1.0
通知正文	引用通知的 `data` 字段中的任何属性	`$body.<property>`	有关通知示例，请参阅事件通知。 `data` 字段中的任何属性都可以使用 `$body` 进行引用

注意

Azure 数字孪生目前不支持基于数组中的字段筛选事件。这包括对数字孪生更改通知的 patch 部分中的属性进行筛选。

以下数据类型可以用作对上述数据进行引用后返回的值：

数据类型	示例
String	`STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')` `CONTAINS(subject, '<twin-ID>')`
Integer	`$body.errorCode > 200`
Double	`$body.temperature <= 5.5`
Bool	`$body.poweredOn = true`
Null	`$body.prop != null`

定义路由筛选器时支持以下运算符：

系列	运算符	示例
逻辑	AND、OR、( )	`(type != 'microsoft.iot.telemetry' OR datacontenttype = 'application/json') OR (specversion != '1.0')`
比较	<、<=、>、>=、=、!=	`$body.temperature <= 5.5`

定义路由筛选器时支持以下函数：

函数	说明	示例
STARTS_WITH(x,y)	如果值 `x` 以字符串 `y` 开头，则返回 true。	`STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')`
ENDS_WITH(x,y)	如果值 `x` 以字符串 `y` 结尾，则返回 true。	`ENDS_WITH($body.$metadata.$model, 'floor;1')`
CONTAINS(x,y)	如果值 `x` 包含字符串 `y`，则返回 true。	`CONTAINS(subject, '<twin-ID>')`

实现或更新筛选器时，更改可能需要几分钟时间才能在数据管道中反映出来。

监视事件路由

可在 Azure 门户中查看计数、延迟和失败率等路由指标。

有关使用 Azure Monitor 查看和管理指标的信息，请参阅指标资源管理器入门。有关可用于 Azure 数字孪生的路由指标的完整列表，请参阅 Azure 数字孪生路由指标。

后续步骤

阅读可接收的不同类型的事件消息：

事件通知

通过