如何在 Azure Digital Twins 中建立使用者定義函式

重要

已發行新版本的 Azure Digital Twins 服務。 針對新服務的擴充功能，本檔集) 中所述的原始 Azure Digital Twins 服務 (已淘汰。

若要檢視新服務的檔，請流覽使用中的 Azure Digital Twins 檔。

使用者定義函式可讓使用者將自訂邏輯設定為從傳入遙測訊息和空間圖表中繼資料中執行。 使用者也可以將事件傳送至預先定義的端點。

本指南將在範例中逐步示範如何從所接收的溫度事件中偵測超過特定溫度的任何讀數並發出警示。

在以下範例中，YOUR_MANAGEMENT_API_URL 代表 Digital Twins API 的 URI：

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0

名稱	更換為
YOUR_INSTANCE_NAME	Azure Digital Twins 執行個體的名稱
YOUR_LOCATION	裝載您執行個體的區域

用戶端程式庫參考

使用者定義函式執行階段中可作為協助程式方法的函式，會列在用戶端參考文件中。

建立比對器

比對器是針對指定的遙測訊息，判斷要使用哪個使用者定義函式的圖表物件。

• 有效比對器條件的比較：

  • Equals
  • NotEquals
  • Contains

• 有效比對器條件的目標：

  • Sensor
  • SensorDevice
  • SensorSpace

下列比對器範例在資料類型值為 "Temperature" 的任何感應器遙測事件上會評估為 True。 您可以藉由提出已驗證的 HTTP POST 要求，在使用者定義函式上建立多個比對器：

YOUR_MANAGEMENT_API_URL/matchers

使用 JSON 主體：

{
  "id": "3626464-f39b-46c0-d9b0c-436aysj55",
  "name": "Temperature Matcher",
  "spaceId": "YOUR_SPACE_IDENTIFIER",
  "conditions": [
    {
      "id": "ag7gq35cfu3-e15a-4e9c-6437-sj6w68sy44s",
      "target": "Sensor",
      "path": "$.dataType",
      "value": "\"Temperature\"",
      "comparison": "Equals"
    }
  ]
}

值	更換為
YOUR_SPACE_IDENTIFIER	裝載您執行個體的伺服器區域

建立使用者定義函式

建立使用者定義的函式涉及向 Azure Digital Twins 管理 API 提出多部分 HTTP 要求。

注意

多部分要求通常需要三個資訊片段：

• Content-Type 標頭：
  • application/json; charset=utf-8
  • multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
• Content-Disposition：
  • form-data; name="metadata"
• 要上傳的檔案內容

Content-Type 和 Content-Disposition 可能會依使用案例而有所不同。

可以透過程式設計的方式 (透過 C#)、透過 REST 用戶端或 Postman 等工具進行多部分要求。 REST 用戶端工具可能對複雜的多部分要求具有不同程度的支援。 組態設定可能會隨著工具而略有不同。 確認哪一種工具最適合您的需求。

重要

針對 Azure Digital Twins 管理 API 發出的多部分要求通常有兩個部分：

• 由 Content-Type 和/或 Content-Disposition 宣告的 Blob 中繼資料 (例如相關聯的 MIME 類型)
• Blob 內容，其中包含要上傳之檔案的非結構化內容

兩個部分都不需要 PATCH 要求。 針對 POST 或建立作業，兩者皆為必要。

佔用量快速入門原始程式碼包含完整的 C# 範例，示範如何針對 Azure Digital Twins 管理 API 發出多部分要求。

建立比對器之後，使用下列已驗證的多部分 HTTP POST 要求來上傳函式程式碼片段：

YOUR_MANAGEMENT_API_URL/userdefinedfunctions

使用下列主體：

--USER_DEFINED_BOUNDARY
Content-Type: application/json; charset=utf-8
Content-Disposition: form-data; name="metadata"

{
  "spaceId": "YOUR_SPACE_IDENTIFIER",
  "name": "User Defined Function",
  "description": "The contents of this udf will be executed when matched against incoming telemetry.",
  "matchers": ["YOUR_MATCHER_IDENTIFIER"]
}
--USER_DEFINED_BOUNDARY
Content-Disposition: form-data; name="contents"; filename="userDefinedFunction.js"
Content-Type: text/javascript

function process(telemetry, executionContext) {
  // Code goes here.
}

--USER_DEFINED_BOUNDARY--

值	更換為
USER_DEFINED_BOUNDARY	多部分內容界限名稱
YOUR_SPACE_IDENTIFIER	空間識別碼
YOUR_MATCHER_IDENTIFIER	您想要使用之比對器的識別碼

1. 確認標頭包含：Content-Type: multipart/form-data; boundary="USER_DEFINED_BOUNDARY"。

2. 確認主體是由多個部分組成的：

   • 第一個部分包含必要的使用者定義函式中繼資料。
   • 第二個部分包含 JavaScript 計算邏輯。

3. 在 [USER_DEFINED_BOUNDARY] 區段中，取代 spaceId (YOUR_SPACE_IDENTIFIER) 和 比對器 (YOUR_MATCHER_IDENTIFIER) 值。

4. 確認將 JavaScript 使用者定義函式作為 Content-Type: text/javascript 提供。

函式範例

直接針對資料類型為 Temperature (也就是 sensor.DataType) 的感應器設定感應器遙測讀取：

function process(telemetry, executionContext) {

  // Get sensor metadata
  var sensor = getSensorMetadata(telemetry.SensorId);

  // Retrieve the sensor value
  var parseReading = JSON.parse(telemetry.Message);

  // Set the sensor reading as the current value for the sensor.
  setSensorValue(telemetry.SensorId, sensor.DataType, parseReading.SensorValue);
}

telemetry 參數會公開 SensorId 和 Message 屬性 (對應到感應器所傳送的訊息)。 ExecutionContext 參數會公開下列屬性：

var executionContext = new UdfExecutionContext
{
    EnqueuedTime = request.HubEnqueuedTime,
    ProcessorReceivedTime = request.ProcessorReceivedTime,
    UserDefinedFunctionId = request.UserDefinedFunctionId,
    CorrelationId = correlationId.ToString(),
};

在下一個範例中，如果感應器遙測讀取超出預先定義的閾值，我們就會記錄訊息。 如果 Azure Digital Twins 執行個體上已啟用診斷設定，則也會轉送來自使用者定義函式的記錄：

function process(telemetry, executionContext) {

  // Retrieve the sensor value
  var parseReading = JSON.parse(telemetry.Message);

  // Example sensor telemetry reading range is greater than 0.5
  if(parseFloat(parseReading.SensorValue) > 0.5) {
    log(`Alert: Sensor with ID: ${telemetry.SensorId} detected an anomaly!`);
  }
}

如果溫度高於在預先定義的常數，下列程式碼會觸發通知：

function process(telemetry, executionContext) {

  // Retrieve the sensor value
  var parseReading = JSON.parse(telemetry.Message);

  // Define threshold
  var threshold = 70;

  // Trigger notification 
  if(parseInt(parseReading) > threshold) {
    var alert = {
      message: 'Temperature reading has surpassed threshold',
      sensorId: telemetry.SensorId,
      reading: parseReading
    };

    sendNotification(telemetry.SensorId, "Sensor", JSON.stringify(alert));
  }
}

如需更複雜的使用者定義函數程式碼範例，請閱讀 佔用量快速入門。

建立角色指派

建立角色指派，讓使用者定義函式可在其下執行。 如果為使用者定義的函式沒有角色指派存在，則不會擁有適當的權限可與管理 API 互動，或者不會擁有可對圖表物件執行動作的存取權。 使用者定義函式可執行的動作是透過 Azure Digital Twins 管理 API 內的角色型存取控制所指定與定義的。 例如，您可以藉由指定特定角色或特定存取控制路徑來限制使用者定義函式的範圍。 如需詳細資訊，請參閱 角色型存取控制 檔。

1. 針對所有角色查詢系統 API，以取得您想要指派給使用者定義函式的角色識別碼。 提出已驗證的 HTTP GET 要求來達成此目的：

   YOUR_MANAGEMENT_API_URL/system/roles
   

   保留所需的角色識別碼。 其會以 JSON 主體屬性 roleId 的形式傳遞， (YOUR_DESIRED_ROLE_IDENTIFIER) 如下。

2. objectId (YOUR_USER_DEFINED_FUNCTION_ID) 會是稍早建立的使用者定義函數識別碼。

3. 使用 查詢空格 fullpath ，以尋找路徑 (YOUR_ACCESS_CONTROL_PATH) 的值。

4. 複製傳回的 spacePaths 值。 您將會在下方用到該值。 提出已驗證的 HTTP GET 要求：

   YOUR_MANAGEMENT_API_URL/spaces?name=YOUR_SPACE_NAME&includes=fullpath
   

   值	更換為
   YOUR_SPACE_NAME	想要使用的空間名稱

5. 將傳回的 spacePaths 值貼至 path，藉由提出已驗證的 HTTP POST 要求來建立使用者定義函式角色指派：

   YOUR_MANAGEMENT_API_URL/roleassignments
   

   使用 JSON 主體：

   {
     "roleId": "YOUR_DESIRED_ROLE_IDENTIFIER",
     "objectId": "YOUR_USER_DEFINED_FUNCTION_ID",
     "objectIdType": "YOUR_USER_DEFINED_FUNCTION_TYPE_ID",
     "path": "YOUR_ACCESS_CONTROL_PATH"
   }
   

   值	更換為
   YOUR_DESIRED_ROLE_IDENTIFIER	所需角色的識別碼
   YOUR_USER_DEFINED_FUNCTION_ID	您所要使用的使用者定義函式其識別碼
   YOUR_USER_DEFINED_FUNCTION_TYPE_ID	指定使用者定義函式類型的識別碼 (UserDefinedFunctionId)
   YOUR_ACCESS_CONTROL_PATH	存取控制路徑

提示

請參閱如何建立和管理角色指派一文，以取得使用者定義函式管理 API 作業和端點的相關詳細資訊。

傳送要處理的遙測

空間智慧圖形中所定義的感應器會傳送遙測。 接著，遙測會觸發已上傳的使用者定義函式執行。 資料處理器取用遙測資料。 然後，系統會為使用者定義函式的調用建立執行計畫。

1. 針對產生讀數的感應器擷取比對器。
2. 根據評估成功的比對器，擷取相關聯的使用者定義函式。
3. 擷取每個使用者定義函式。

後續步驟

• 了解如何建立 Azure Digital Twins 端點以傳送事件。

• 如需 Azure Digital Twins 中路由的詳細資訊，請參閱路由事件和訊息。

• 檢閱用戶端程式庫參考文件。