在 Azure Digital Twins 中建立事件路由和篩選條件

本文會逐步引導您使用 Azure 入口網站、Azure CLI az dt route 命令、事件路由資料平面 API 和 .NET (C#) SDK 建立事件路由的程序。

將事件通知從 Azure Digital Twins 路由傳送至下游服務或連線的計算資源是兩個步驟的程序：建立端點，然後建立事件路由以將資料傳送至這些端點。 本文涵蓋第二個步驟：設定路由來控制哪些事件會傳遞至 Azure Digital Twin 端點。 若要繼續本文，您應該已建立端點。

必要條件

• 您會需要可免費設定的 Azure 帳戶

• 您需要 Azure 訂用帳戶中的 Azure Digital Twins 執行個體。 如果您還沒有執行個體，您可以使用設定執行個體和驗證中的步驟來建立。 請從安裝程式取得下列值，以便稍後使用於本文中：

  • 執行個體名稱
  • 資源群組

  您可以在設定執行個體之後，於 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 Digital Twins 外部路由傳送任何訊息。 如果有路由名稱，且篩選準則為 true，則所有訊息都會經路由傳送至端點。 如果有路由名稱，且新增了不同的篩選準則，則會根據篩選準則篩選訊息。

您可以使用 Azure 入口網站、EventRoutes 資料平面 API 或 az dt 路由 CLI 命令來建立事件路由。 本節的其餘部分會引導您完成建立流程。

入口網站

若要建立事件路由，請移至 Azure 入口網站中 Azure Digital Twins 執行個體的詳細資料頁面 (您可以在入口網站搜尋列中輸入該名稱，以尋找執行個體)。

從執行個體功能表中，選取 [事件路由]。 然後，從後續的 [事件路由] 頁面中，選取 [+ 建立事件路由]。

在開啟的 [建立事件路由] 頁面上，至少選擇：

• 名稱欄位中路由的名稱
• 您想要用來建立路由的端點

若要啟用路由，您也必須至少有 true 的新增事件路由篩選。 (保留預設值 false 將會建立路由，但不會對其傳送任何事件。)若要這麼做，請切換 [進階編輯器] 的開關加以啟用，然後在 [篩選] 方塊中寫入 true。

完成後，選取 [儲存] 按鈕以建立事件路由。

CLI

您可以使用 Azure Digital Twins CLI 的 az dt 路由 命令來管理路由。

如需使用 CLI 和可用命令的詳細資訊，請參閱 Azure Digital Twins CLI 命令集。

.NET SDK

本節說明如何使用 .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 Digital Twins 的不同事件：

• 由使用 Azure Digital Twins 服務 API 的數位對應項所引發的遙測
• 數位對應項屬性變更通知，由 Azure Digital Twins 執行個體中的對應項屬性變更所引發
• 生命週期事件，在建立或刪除對應項或關聯性時即會引發

您可定義更具體的篩選條件，以限制要傳送的事件種類。

注意

篩選條件會區分大小寫，且必須符合承載案例。 對於遙測篩選條件，這表示大小寫必須符合裝置所傳送遙測中的大小寫。

入口網站

若要在建立事件路由時新增事件篩選器，請使用 [建立事件路由] 頁面的 [新增事件路由篩選] 區段。

您可從幾個常用的基本篩選選項中選取，或使用進階篩選選項來撰寫自己的自訂篩選。

使用基本篩選

若要使用基本篩選條件，請展開 [事件類型] 選項，針對要傳送至端點的事件選取對應的核取方塊。

這麼做會將您所選取的篩選文字自動填入篩選文字方塊：

使用進階篩選

您可使用進階篩選選項，來寫入自己的自訂篩選條件。

若要使用進階篩選選項來建立事件路由，請切換為 [進階編輯器] 以便啟用。 接著，您可在 [篩選] 方塊中撰寫自己的事件篩選條件：

API

您可使用事件路由資料平面 API 來撰寫自訂篩選條件。 若要新增篩選條件，您可以使用 PUT 要求 https://<Your-Azure-Digital-Twins-host-name>/eventRoutes/<event-route-name>?api-version=2020-10-31 搭配下列本文：

{
    "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 Digital Twins 執行個體名稱	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 格式，這些主體是由多個組件或識別碼唯一識別： <twin-ID>/relationships/<relationship-ID> 對於遙測：主體是元件路徑 (如果遙測是從對應項元件發出)，例如 comp1.comp2。 若遙測不是由元件發出，則主體欄位則為空白。
資料結構描述	DTDL 模型識別碼	dataschema = '<model-dtmi-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 Digital Twins 目前不支援以陣列中欄位為基礎的篩選事件， 這包含在數位對應項變更通知的 patch 區段中篩選屬性。

下列資料類型支援作為上述資料參考所傳回的值：

資料類型	範例
String	STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor') CONTAINS(subject, '<twin-ID>')
整數	$body.errorCode > 200
雙重	$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 監視器檢視和管理計量的資訊，請參閱開始使用計量瀏覽器。 如需 Azure Digital Twins 可用的路由計量完整清單，請參閱 Azure Digital Twins 路由計量。

下一步

閱讀您可以接收的不同事件訊息類型：

• 事件通知