設定對應項到對應項事件處理

發行項
05/13/2024

本文說明如何將事件從對應項傳送至對應項，以便在圖表中的某一個數位對應項更新時，受該資訊影響的相關對應項也可以更新。此事件處理可幫助您建立完全相連的 Azure Digital Twins 圖表，讓從外部來源 (如 IoT 中樞) 輸入 Azure Digital Twins 的資料能透過整個圖表傳播。

若要設定這種對應項對對應項的事件處理，您需要建立一個 Azure 函式來監看對應項的生命週期事件。函式可以辨識會影響圖表中其他對應項的事件，並依據事件資料來更新受影響的對應項。

必要條件

若要設定對應項到對應項的處理，您需要能夠使用的一個 Azure Digital Twins 執行個體。如需關於如何建立執行個體的指示，請參閱設定 Azure Digital Twins 執行個體和驗證。執行個體至少應包含兩個您想在其間傳送資料的對應項。

或者，您也可以為對應項設定從 IoT 中樞自動內嵌遙測。此流程不需要將資料從對應項傳送到對應項，但對於即時裝置遙測所驅動的對應項圖表來說，它是完整解決方案中的一個重要部分。

將對應項事件傳送至端點

若要設定對應項到對應項的事件處理，請先在 Azure Digital Twins 中建立一個「端點」和連接該端點的「路由」。進行更新的對應項會使用路由，將更新事件的相關資訊傳送至端點 (接下來，事件方格會接收這些事件，然後將其傳給 Azure 函式來處理)。

建立事件方格主題

事件方格是一項 Azure 服務，可協助您將來自 Azure 服務的事件路由及傳遞至 Azure 內的其他位置。您可以建立事件方格主題，從來源收集特定事件，然後訂閱者可以接聽該主題，以在事件送達時接收事件。

在 Azure CLI 中執行下列命令以建立事件方格主題：

az eventgrid topic create --resource-group <your-resource-group> --name <name-for-your-event-grid-topic> --location <region>

此命令的輸出是您所建立事件方格主題的相關資訊。請儲存您給予事件方格主題的名稱，因為您稍後將會用到它。

建立端點

接著，在 Azure Digital Twins 中建立事件方格端點，將您的執行個體連線至事件方格主題。使用下列命令，填入上一個步驟的事件方格主題名稱，並視需要填入其他的預留位置欄位。

az dt endpoint create eventgrid --dt-name <Azure-Digital-Twins-instance> --eventgrid-resource-group <your-resource-group> --eventgrid-topic <your-event-grid-topic> --endpoint-name <name-for-your-Azure-Digital-Twins-endpoint>

此命令的輸出是您所建立端點的相關資訊。

尋找輸出的 provisioningState 欄位，檢查其值是否為 "Succeeded"。

其也可能指出「佈建中」，這表示端點仍在建立中。如果是，請稍候幾秒鐘，然後執行下列命令來檢查端點狀態。重複前述作業，直到 provisioningState 顯示為 "Succeeded" 為止。

az dt endpoint show --dt-name <your-Azure-Digital-Twins-instance> --endpoint-name <your-Azure-Digital-Twins-endpoint>

請儲存端點的名稱，因為您稍後將會用到它。

建立路由

接下來，建立 Azure Digital Twins 路由，將事件傳送至您建立的事件方格端點。

使用下列 CLI 命令，填入上一個步驟的端點名稱，並視需要填入其他的預留位置欄位。此命令會轉送對應項圖表中發生的所有事件。

提示

您可以使用篩選條件來將事件限定為特定事件。

az dt route create --dt-name <your-Azure-Digital-Twins-instance> --endpoint-name <your-Azure-Digital-Twins-endpoint> --route-name <name-for-your-Azure-Digital-Twins-route>

此命令的輸出是您所建立路由的部分資訊。

注意

端點 (來自上一個步驟) 必須先完成佈建，您才能設定使用這些端點的事件路由。如果因為端點尚未就緒而導致路由建立失敗，請等候幾分鐘，然後再試一次。

建立 Azure 函式以更新對應項

接下來，建立一個 Azure 函式來接聽端點並接收透過路由傳送到該處的對應項事件。函式的邏輯應使用事件中的資訊來判斷還有哪些對應項需要更新，然後進行更新。

首先，建立一個新的 Azure Functions 專案。

您可以使用 Visual Studio (如需相關指示，請參閱使用 Visual Studio 來開發 Azure Functions)、Visual Studio Code (如需相關指示，請參閱使用 Visual Studio Code 以在 Azure 中建立 C# 函式) 或 Azure CLI (如需相關指示，請參閱從命令列在 Azure 中建立 C# 函式) 來執行此動作。
將下列套件新增至您的專案 (您可以使用 Visual Studio NuGet 套件管理員，或命令列工具中的 dotnet add package 命令)。
填入您函式的邏輯。您可以在 azure-digital-twins-getting-started 存放庫中檢視多個案例的範例函式程式碼以協助您著手使用。
使用您慣用的方法將函式發佈至 Azure。

如需如何使用 Visual Studio 來發佈函式的相關指示，請參閱使用 Visual Studio 來開發 Azure Functions。如需如何使用 Visual Studio Code 來發佈函式的相關指示，請參閱使用 Visual Studio Code 以在 Azure 中建立 C# 函式。對於如何使用 Azure CLI 來發佈函數，如需相關指示，請參閱從命令列在 Azure 中建立 C# 函數。

函式發佈完畢後，您可以使用此 Azure CLI 命令來確認發佈是否成功。資源群組中有預留位置、函式應用程式的名稱，以及特定函式的名稱。此命令會列印您函式的相關資訊。

az functionapp function show --resource-group <your-resource-group> --name <your-function-app> --function-name <your-function>

設定函式應用程式

您的函式需要一些執行個體的相關資訊和存取 Azure Digital Twins 的權限，才能夠存取 Azure Digital Twins。在本節中，您會為函式指派存取角色，並設定應用程式以尋找和存取執行個體。

在 Azure Cloud Shell 或本機 Azure CLI 中執行下列命令。

注意

此區段必須由有權限管理使用者對 Azure 資源存取權的 Azure 使用者來完成，包括授與和委派權限。符合此需求的常見角色包括：擁有者、帳戶管理員，或使用者存取管理員與參與者的組合。如需 Azure Digital Twins 角色權限需求的詳細資訊，請參閱設定執行個體和驗證。

指派存取角色

Azure 函數需要傳遞給角色的持有人權杖。若要確定已傳遞持有人權杖，請為函數應用程式授與 Azure Digital Twins 執行個體的 Azure Digital Twins 資料擁有者角色，這會授與函數應用程式在執行個體上執行資料平面活動的權限。

使用下列命令來為函式建立系統受控識別 (如果函式已經有，此命令將會列印其詳細資料)。記下輸出中的 principalId 欄位。您將使用此識別碼來參考函數，以便可以在下一個步驟中授與其權限。
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```

使用下列命令中的 principalId 值，將函數提供給您 Azure Digital Twins 執行個體的 Azure Digital Twins 資料擁有者角色。

az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"

設定應用程式設定

接下來，為函數設定環境變數，讓您的 Azure Digital Twins 執行個體的 URL 存取函數。

提示

Azure Digital Twins 執行個體的 URL 是藉由將 https:// 新增至執行個體主機名稱的開頭加以建立。若要查看主機名稱，以及執行個體的所有屬性，請執行 az dt show --dt-name <your-Azure-Digital-Twins-instance>。

下列命令會設定執行個體 URL 的環境變數，每當函式需要存取執行個體時，就會使用該環境變數。

az functionapp config appsettings set --resource-group <your-resource-group> --name <your-function-app-name> --settings "ADT_SERVICE_URL=https://<your-Azure-Digital-Twins-instance-host-name>"

將函式連接至端點

接下來，請將您的 Azure 函式訂閱到您稍早建立的事件方格端點。這麼做可確保資料從更新的對應項透過事件方格主題流向函式，以便根據需要利用事件資訊來更新其他對應項。

若要訂閱您的 Azure 函式，您需要建立一個「事件方格訂閱」來將資料從稍早建立的事件方格主題傳送至 Azure 函式。

使用下列 CLI 命令，並填入訂閱識別碼、資源群組、函式應用程式和函式名稱的預留位置。

az eventgrid event-subscription create --name <name-for-your-event-subscription> --source-resource-id /subscriptions/<subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.EventGrid/topics/<your-event-grid-topic> --endpoint-type azurefunction --endpoint /subscriptions/<subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.Web/sites/<your-function-app-name>/functions/<function-name>

現在，您的函式可以透過事件方格主題來接收事件。資料流程設定已完成。

測試和驗證結果

最後一個步驟是確認流程是否正常運作，方法是更新一個對應項，並確認其相關對應項是否有根據 Azure 函式中的邏輯來更新。

若要開始此流程，請更新事件流程來源的對應項。您可以使用 Azure CLI、Azure Digital Twins SDK 或 Azure Digital Twins REST API 來進行更新。

接下來，在您的 Azure Digital Twins 執行個體中查詢相關的對應項。您可以使用 Azure CLI 或 Azure Digital Twins REST API 和 SDK。確認對應項已收到資料並如預期般更新。

下一步

在本文中，您將會在 Azure Digital Twins 中設定對應項到對應項的事件處理。接下來，設定一個 Azure 函式，以根據從 IoT 中樞裝置傳入的遙測資料來自動觸發此流程：從 IoT 中樞內嵌遙測。

共用方式為