在 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 route CLI 命令 來建立 事件路由。 本節的其餘部分會逐步解說建立程式。

入口網站

若要建立事件路由，請移至 Azure 入口網站 中 Azure Digital Twins 實例的詳細資料頁面（您可以在入口網站搜尋列中輸入其名稱來尋找實例）。

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

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

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

若要啟用路由，您也必須 至少 true 新增 的事件路由篩選 。 （將 的預設值 false 保留為 會建立路由，但不會傳送任何事件給路由。若要這樣做，請切換 [進階編輯器] 的 切換來啟用它，然後在 [ 篩選 ] 方塊中寫入 true 。

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

CLI

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

如需使用 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 路由計量 。

下一步

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

• 事件通知