共用方式為


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

本文說明如何將事件從對應項傳送至對應項,以便在圖表中的某一個數位對應項更新時,受該資訊影響的相關對應項也可以更新。 此事件處理可幫助您建立完全相連的 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"。

Azure 入口網站 Cloud Shell 中端點查詢結果的螢幕快照,其中顯示具有 provisioningState of 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 函式來接聽端點並接收透過路由傳送到該處的對應項事件。 函式的邏輯應使用事件中的資訊來判斷還有哪些對應項需要更新,然後進行更新。

  1. 首先,建立一個新的 Azure Functions 專案。

    您可以使用 Visual Studio (如需相關指示,請參閱使用 Visual Studio 來開發 Azure Functions)、Visual Studio Code (如需相關指示,請參閱使用 Visual Studio Code 以在 Azure 中建立 C# 函式) 或 Azure CLI (如需相關指示,請參閱從命令列在 Azure 中建立 C# 函式) 來執行此動作。

  2. 將下列套件新增至您的專案 (您可以使用 Visual Studio NuGet 套件管理員,或命令列工具中的 dotnet add package 命令)。

  3. 填入您函式的邏輯。 您可以在 azure-digital-twins-getting-started 存放庫中檢視多個案例的範例函式程式碼以協助您著手使用。

  4. 使用您慣用的方法將函式發佈至 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 資料擁有者角色,這會授與函數應用程式在執行個體上執行資料平面活動的權限。

  1. 使用下列命令來為函式建立 系統受控識別 (如果函式已經有,此命令將會列印其詳細資料)。 記下輸出中的 principalId 欄位。 您將使用此識別碼來參考函數,以便可以在下一個步驟中授與其權限。

    az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
    
  2. 使用下列命令中的 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 CLIAzure Digital Twins SDKAzure Digital Twins REST API 來進行更新。

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

下一步

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