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 Management API にマルチパート HTTP 要求を行う必要があります。

注意

マルチパート要求には、一般的に次の 3 つの情報が必要です。

• Content-Type ヘッダー:
  • application/json; charset=utf-8
  • multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
• コンテンツ廃棄:
  • form-data; name="metadata"
• アップロードするファイルの内容

Content-Type と Content-Disposition は使用シナリオによって異なる場合があります。

マルチパート要求は、プログラム (C# を使用)、REST クライアント、または Postman などのツールを使用して行うことができます。 REST クライアント ツールには、複雑なマルチパート要求をサポートするさまざまなレベルがある場合があります。 構成設定はツールによって若干異なる場合もあります。 どのツールがニーズに最適であるかを確認してください。

重要

Azure Digital Twins Management API に対して行われるマルチパート要求には、一般的に 2 つの部分があります。

• Content-Type および Content-Disposition で宣言される (関連付けられている MIME の種類などの) BLOB メタデータ
• アップロードされるファイルの非構造化コンテンツを含む BLOB コンテンツ

2 つの部分のどちらも PATCH 要求には不要です。 どちらも POST または作成操作に必要です。

占有率のクイック スタートのソース コードには、Azure Digital Twins Management API に対するマルチパート要求を行う方法を示す完全な C# の例が示されています。

マッチャーが作成された後、次の認証済みマルチパート 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	使用するマッチャーの ID

1. ヘッダーに Content-Type: multipart/form-data; boundary="USER_DEFINED_BOUNDARY" が含まれていることを確認します。

2. 本文がマルチパートであることを確認します。

   • 最初の部分には、必須のユーザー定義関数メタデータが含まれています。
   • 2 番目の部分には、JavaScript の計算ロジックが含まれています。

3. USER_DEFINED_BOUNDARYセクションで、spaceId () とマッチャー (YOUR_MATCHER_IDENTIFIERYOUR_SPACE_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);
}

テレメトリ パラメーターは、センサーによって送信されたメッセージに対応する SensorId 属性とメッセージ属性を公開します。 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));
  }
}

より複雑なユーザー定義関数のコード サンプルについては、占有率のクイック スタートに関するページをお読みください。

役割の割り当ての作成

ユーザー定義関数の実行に使われるロールの割り当てを作成します。 ユーザー定義関数にロールが割り当てられていない場合、ユーザー定義関数には Management API と対話したり、グラフ オブジェクトで操作を実行したりするための適切なアクセス許可がありません。 ユーザー定義関数で実行できるアクションは、Azure Digital Twins Management API 内のロールベースのアクセス制御によって指定および定義されます。 たとえば、ユーザー定義関数の範囲は、特定のロールまたは特定のアクセス制御パスを指定することで限定できます。 詳しくは、ロールベースのアクセス制御のドキュメントをお読みください。

1. すべてのロールについてシステム API に対してクエリを実行して、ユーザー定義関数に割り当てるロール ID を取得します。 そのためには、以下に対して認証済みの HTTP GET 要求を実行します。

   YOUR_MANAGEMENT_API_URL/system/roles
   

   目的のロール ID を保持します。 これは、以下の JSON 本文属性 roleId (YOUR_DESIRED_ROLE_IDENTIFIER) として渡されます。

2. objectId (YOUR_USER_DEFINED_FUNCTION_ID) は、前に作成したユーザー定義関数 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	使用するユーザー定義関数の ID
   YOUR_USER_DEFINED_FUNCTION_TYPE_ID	ユーザー定義関数 (UserDefinedFunctionId) の種類を指定する ID
   YOUR_ACCESS_CONTROL_PATH	アクセス制御パス

ヒント

ユーザー定義関数の Management API の操作とエンドポインについて詳しくは、ロールの割り当てを作成および管理する方法に関する記事をご覧ください。

処理するテレメトリを送信する

空間インテリジェンス グラフで定義されているセンサーによってテレメトリが送信されます。 さらに、テレメトリでは、アップロードされたユーザー定義関数の実行がトリガーされます。 データ プロセッサがテレメトリを取得します。 次に、ユーザー定義関数の呼び出し用の実行プランが作成されます。

1. 測定値の生成元であるセンサーのマッチャーを取得します。
2. どのマッチャーが正常に評価されたかに応じて、関連付けられているユーザー定義関数を取得します。
3. 各ユーザー定義関数を実行します。

次の手順

• イベントの送信先となる Azure Digital Twins エンドポイントを作成する方法を学習する。

• Azure Digital Twins でのルーティングについて詳しくは、「ルーティング イベントおよびメッセージ」をご覧ください。

• クライアント ライブラリ リファレンス ドキュメントをご覧ください。