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 インスタンスの名前
あなたの場所	インスタンスがホストされているリージョン

クライアント ライブラリ リファレンス

ユーザー定義関数ランタイムでヘルパー メソッドとして使用できる関数は、 クライアント ライブラリのリファレンス ドキュメントに記載されています。

マッチャーを作成する

マッチャーは、特定のテレメトリ メッセージに対して実行されるユーザー定義関数を決定するグラフ オブジェクトです。

• 有効なマッチャー条件の比較:

  • 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 によって宣言された BLOB メタデータ (関連付けられている MIME タイプなど)
• アップロードするファイルの非構造化コンテンツを含む BLOB コンテンツ

PATCH 要求には、2 つの部分のどちらも必要ありません。 両方とも 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--

価値	に置き換える
ユーザー定義境界	マルチパート コンテンツ境界名
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_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);
}

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

より複雑なユーザー定義関数のコード サンプルについては、 占有率のクイック スタートを参照してください。

ロールの割り当てを作成する

実行するユーザー定義関数のロールの割り当てを作成します。 ユーザー定義関数にロールの割り当てが存在しない場合、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
   

   価値	に置き換える
   あなたのスペース名	使用するスペースの名前

5. 返された spacePaths 値を パス に貼り付けて、認証された 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"
   }
   

   価値	に置き換える
   希望する役割識別子	目的のロールの識別子
   ユーザー定義関数ID	使用するユーザー定義関数の ID
   ユーザー定義関数のタイプID	ユーザー定義関数型を指定する ID (UserDefinedFunctionId)
   YOUR_ACCESS_CONTROL_PATH	アクセス制御パス

ヒント

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

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

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

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

次のステップ

• イベントを送信する Azure Digital Twins エンドポイントを作成 する方法について説明します。

• Azure Digital Twins でのルーティングの詳細については、「 ルーティング イベントとメッセージ」を参照してください。

• クライアント ライブラリのリファレンス ドキュメントを確認します。