路由傳送 Azure Digital Twins 事件

  • 發行項

本文說明 Azure Digital Twins 用來傳送事件資料的程式，這兩者皆用於在 Azure Digital Twins 內部路由事件，以及將事件資料外部傳送至下游服務或服務外部連線的計算資源。

從 Azure Digital Twins 路由 傳送事件通知 是兩個步驟的程式：建立 端點，然後建立 事件路由 以將資料傳送至這些端點。 本文會進一步詳細說明這些概念。 也說明端點無法及時傳遞事件時如何處理 (稱為「無效信件」的程序)。

事件路由概觀

傳送 Azure Digital Twins 資料有兩種主要案例，兩者都由事件路由完成：

  • 在 Azure Digital Twins 圖表中的兩個對應項之間傳送事件資料。 例如，當某個數位對應項的屬性變更時，您可以根據更新的資料來通知並更新另一個數位對應項。
  • 在 Azure Digital Twins 外部將資料傳送至下游資料服務，以進一步儲存或處理。 例如，如果您已使用 Azure 地圖服務，您可以提供 Azure Digital Twins 資料，以使用整合式模型或查詢來增強解決方案。

對於任何事件目的地，事件路由會將事件資料從 Azure Digital Twins 傳送至訂用帳戶中已自行定義的「端點」。 端點目前支援三個 Azure 服務：事件中樞、事件方格和服務匯流排。 這些 Azure 服務都可以連線到其他服務，並做為中間人，將資料傳送至最終目的地，例如Azure 地圖服務，或傳回到 Azure Digital Twins 以進行相依圖表更新。

下圖說明事件資料流經較大的 IoT 解決方案，其中包括 Azure Digital Twins 資料經過端點傳送至其他 Azure 服務，然後回到 Azure Digital Twins：

Azure Digital Twins 將資料經過端點路由傳送至數個下游服務的圖表。

針對 Azure Digital Twins 外部的資料輸出，事件路由的典型下游目標包括時間序列深入解析、Azure 地圖服務、儲存體和分析解決方案。 針對發出至輸出服務的資料，Azure Digital Twins 會實作「至少一次」傳遞。

若要在相同的 Azure Digital Twins 解決方案內路由傳送內部數位對應項事件，請繼續下一節。

路由傳送內部數位對應項事件

事件路由在對應項圖表內處理事件的一種機制，可在數位對應項之間傳送資料。 這種事件處理會將事件路由經過事件方格來連線到計算資源，例如 Azure Functions。 這些函式接著定義對應項應該如何接收和回應事件。

當計算資源想要根據透過事件路由收到的事件來修改對應項圖表時，最好事先知道應該修改的對應項。 事件訊息也包含傳送訊息的來源對應項的識別碼，因此計算資源可以使用查詢或周遊關聯性，以尋找所需作業的目標對應項。

計算資源也需要獨立建立安全性和存取權限。

有關設定 Azure 函式來處理數位對應項事件的逐步解說過程，請參閱設定對應項到對應項事件處理。

建立端點

若要定義事件路由，開發人員必須先定義「端點」。 「端點」是 Azure Digital Twins 外部支援路由連線的目的地。 支援的目的地包括：

  • 事件方格自訂主題
  • 事件中樞
  • 服務匯流排

若要建立端點，您可以使用 Azure Digital Twins REST API、CLI 命令或Azure 入口網站。

定義端點時，您必須提供：

  • 端點的名稱
  • 端點類型 (事件方格、事件中樞或服務匯流排)
  • 要驗證的主要連接字串和次要連接字串
  • 端點的主題路徑，例如 your-topic.westus2.eventgrid.azure.net

您可以選擇使用身分識別型驗證來建立端點，以搭配 系統指派或使用者指派的受控識別使用端點。 此選項僅適用於事件中樞和服務匯流排類型端點 (並不支援事件方格)。

控制平面中可用的端點 API 如下：

  • 建立端點
  • 取得端點清單
  • 依名稱取得端點
  • 依名稱刪除端點

如需建立端點的詳細指示，請參閱 建立端點。

建立事件路由

若要建立事件路由，您可以使用 Azure Digital Twins REST API、CLI 命令或Azure 入口網站。

以下是使用 CreateOrReplaceEventRouteAsync.NET (C#) SDK 呼叫在用戶端應用程式內建立事件路由的範例：

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

  1. 首先會建立 DigitalTwinsEventRoute 物件，且建構函式接受端點的名稱。 此 endpointName 欄位會識別端點，例如事件中樞、事件方格或服務匯流排。 進行此註冊呼叫之前，必須在訂用帳戶中建立這些端點，並使用控制平面 API 將端點連結至 Azure Digital Twins。

  2. 事件路由物件也有篩選條件欄位，可用來限制沿著此路由傳送的事件類型。 篩選條件為 true 會啟用路由，且不額外篩選 (篩選條件為 false 會停用路由)。

  3. 然後，此事件路由會連同路由的名稱傳遞至 CreateOrReplaceEventRouteAsync。

提示

所有 SDK 函式都有同步和非同步版本。

如需建立事件路由的詳細指示，請參閱 建立路由和篩選。

無效事件

當端點在一定期限內或嘗試傳遞事件幾次之後無法傳遞事件時，就會將未傳遞的事件傳送至儲存體帳戶。 此程序稱為無效化。 符合下列其中一個條件時，Azure Digital Twins 會將事件當成無效信件處理：

  • 未在存留時間期間內傳遞事件
  • 嘗試傳遞事件的次數已超過限制

如果符合任一條件，就會卸除事件或已變更為無效信件。 每個端點預設不啟用無效信件處理。 若要啟用，您必須在建立端點時指定儲存體帳戶來保留未傳遞的事件。 然後，您可以從這個儲存體帳戶提取事件以解析傳遞。

在設定無效信件位置之前，您必須先有具備容器的儲存體帳戶。 您在建立端點時提供此容器的 URL。 提供的無效信件為容器 URL 加上 SAS 權杖。 對於儲存體帳戶內的目的地容器，該權杖只需要 write 權限。 完整 URL 的格式為：https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>

如需深入了解 SAS 權杖，請參閱使用共用存取簽章 (SAS) 授與 Azure 儲存體資源的有限存取權

若要瞭解如何使用寄不出的信件設定端點，請參閱 端點選項：寄不出的信件。

事件訊息的類型

IoT 中樞和 Azure Digital Twins 中不同類型的事件會產生不同類型的通知訊息，如下所述。

通知類型 路由來源名稱 產生自...
數位對應項變更通知 數位對應項變更通知 任何數位對應項屬性變更
數位對應項生命週期通知 數位對應項生命週期通知 任何數位對應項建立或刪除作業
數位對應項關聯性變更通知 數位對應項關聯性變更通知 任何數位對應項關聯性變更
數位對應項遙測訊息 遙測訊息 任何遙測訊息

下一步

繼續閱讀設定端點和事件路由的逐步指示：

或者，請遵循本逐步解說，在 Azure Digital Twins 內設定 Azure Function 以支援對應項到對應項事件處理：