Azure Digital Twins 内でユーザー定義関数を作成する方法How to create user-defined functions in Azure Digital Twins

ユーザー定義関数を使用すると、ユーザーは受信テレメトリ メッセージおよび空間グラフのメタデータから実行されるようにカスタム ロジックを構成できます。User-defined functions enable users to configure custom logic to be executed from incoming telemetry messages and spatial graph metadata. ユーザーは定義済みのエンドポイントにイベントを送信することもできます。Users can also send events to predefined endpoints.

このガイドでは、受信した温度イベントから一定の温度を超えるすべての測定値を検出して警告する方法を示す例を見ていきます。This guide walks through an example demonstrating how to detect and alert on any reading that exceeds a certain temperature from received temperature events.

次の例では、YOUR_MANAGEMENT_API_URL は Digital Twins API の URI を参照しています。In the examples below, YOUR_MANAGEMENT_API_URL refers to the URI of the Digital Twins APIs:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0
NameName 置換後の文字列Replace with
YOUR_INSTANCE_NAMEYOUR_INSTANCE_NAME Azure Digital Twins インスタンスの名前The name of your Azure Digital Twins instance
YOUR_LOCATIONYOUR_LOCATION インスタンスをホストするリージョンThe region your instance is hosted on

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

ユーザー定義関数の実行時のヘルパー メソッドとして使用できる関数の一覧が、クライアント ライブラリ リファレンス ドキュメントに示されています。Functions available as helper methods in the user-defined functions runtime are listed in the client library reference document.

マッチャーを作成するCreate a matcher

マッチャーは、特定のテレメトリ メッセージに対して実行されるユーザー定義関数を決定するグラフ オブジェクトです。Matchers are graph objects that determine what user-defined functions run for a given telemetry message.

  • 有効なマッチャー条件の比較は次のとおりです。Valid matcher condition comparisons:

    • Equals
    • NotEquals
    • Contains
  • 有効なマッチャー条件のターゲットは次のとおりです。Valid matcher condition targets:

    • Sensor
    • SensorDevice
    • SensorSpace

次の例のマッチャーは、データ型の値が "Temperature" であるすべてのセンサー テレメトリ イベントに対して true と評価されます。The following example matcher evaluates to true on any sensor telemetry event with "Temperature" as its data type value. ユーザー定義関数に複数のマッチャーを作成するには、以下に対して認証済みの HTTP POST 要求を実行します。You can create multiple matchers on a user-defined function by making an authenticated HTTP POST request to:

YOUR_MANAGEMENT_API_URL/matchers

JSON 本文は次のようになります。With JSON body:

{
  "Name": "Temperature Matcher",
  "Conditions": [
    {
      "target": "Sensor",
      "path": "$.dataType",
      "value": "\"Temperature\"",
      "comparison": "Equals"
    }
  ],
  "SpaceId": "YOUR_SPACE_IDENTIFIER"
}
Value 置換後の文字列Replace with
YOUR_SPACE_IDENTIFIERYOUR_SPACE_IDENTIFIER インスタンスをホストするサーバーのリージョンWhich server region your instance is hosted on

ユーザー定義関数を作成するCreate a user-defined function

ユーザー定義関数を作成するには、Azure Digital Twins Management API にマルチパート HTTP 要求を行う必要があります。Creating a user-defined function involves making a multipart HTTP request to the Azure Digital Twins Management APIs.

注意

マルチパート要求には、一般的に次の 3 つの情報が必要です。Multipart requests typically require three pieces:

  • Content-Type ヘッダー:A Content-Type header:
    • application/json; charset=utf-8
    • multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
  • Content-Disposition:A Content-Disposition:
    • form-data; name="metadata"
  • アップロードするファイルの内容The file content to upload

Content-TypeContent-Disposition は使用シナリオによって異なる場合があります。Content-Type and Content-Disposition will vary depending on use scenario.

マルチパート要求は、プログラム (C# を使用)、REST クライアント、または Postman などのツールを使用して行うことができます。Multipart requests can be made programmatically (through C#), through a REST client, or tool such as Postman. REST クライアント ツールには、複雑なマルチパート要求をサポートするさまざまなレベルがある場合があります。REST client tools may have varying levels of support for complex multipart requests. 構成設定はツールによって若干異なる場合もあります。Configuration settings may also vary slightly from tool to tool. どのツールがニーズに最適であるかを確認してください。Verify which tool is best suited for your needs.

重要

Azure Digital Twins Management API に対して行われるマルチパート要求には、一般的に 2 つの部分があります。Multipart requests made to the Azure Digital Twins Management APIs typically have two parts:

  • Content-Type および Content-Disposition で宣言される (関連付けられている MIME の種類などの) BLOB メタデータBlob metadata (such as an associated MIME type) that's declared by Content-Type and/or Content-Disposition
  • アップロードされるファイルの非構造化コンテンツを含む BLOB コンテンツBlob contents which include the unstructured contents of a file to be uploaded

2 つの部分のどちらも PATCH 要求には不要です。Neither of the two parts is required for PATCH requests. どちらも POST または作成操作に必要です。Both are required for POST or create operations.

占有率のクイック スタートのソース コードには、Azure Digital Twins Management API に対するマルチパート要求を行う方法を示す完全な C# の例が示されています。The Occupancy Quickstart source code contains complete C# examples demonstrating how to make multipart requests against the Azure Digital Twins Management APIs.

マッチャーが作成された後、次の認証済みマルチパート HTTP POST 要求で関数スニペットをアップロードします。After the matchers are created, upload the function snippet with the following authenticated multipart HTTP POST request to:

YOUR_MANAGEMENT_API_URL/userdefinedfunctions

以下の本文を使用します。Use the following body:

--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--
Value 置換後の文字列Replace with
USER_DEFINED_BOUNDARYUSER_DEFINED_BOUNDARY マルチパート コンテンツ境界名A multipart content boundary name
YOUR_SPACE_IDENTIFIERYOUR_SPACE_IDENTIFIER 空間識別子The space identifier
YOUR_MATCHER_IDENTIFIERYOUR_MATCHER_IDENTIFIER 使用するマッチャーの IDThe ID of the matcher you want to use
  1. ヘッダーに Content-Type: multipart/form-data; boundary="USER_DEFINED_BOUNDARY" が含まれていることを確認します。Verify that the headers include: Content-Type: multipart/form-data; boundary="USER_DEFINED_BOUNDARY".

  2. 本文がマルチパートであることを確認します。Verify that the body is multipart:

    • 最初の部分には、必須のユーザー定義関数メタデータが含まれています。The first part contains the required user-defined function metadata.
    • 2 番目の部分には、JavaScript の計算ロジックが含まれています。The second part contains the JavaScript compute logic.
  3. USER_DEFINED_BOUNDARY セクションで、spaceId (YOUR_SPACE_IDENTIFIER) および matchers (YOUR_MATCHER_IDENTIFIER) の値を置き換えます。In the USER_DEFINED_BOUNDARY section, replace the spaceId (YOUR_SPACE_IDENTIFIER) and matchers (YOUR_MATCHER_IDENTIFIER) values.

  4. JavaScript ユーザー定義関数が Content-Type: text/javascript として提供されていることを確認します。Verify that the JavaScript user-defined function is supplied as Content-Type: text/javascript.

関数の例Example functions

データ型 Temperature のセンサー (sensor.DataType) に対して、センサー テレメトリの測定値を直接設定します。Set the sensor telemetry reading directly for the sensor with data type Temperature, which is 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 属性 (センサーから送信されたメッセージに対応) を公開します。The telemetry parameter exposes the SensorId and Message attributes, corresponding to a message sent by a sensor. executionContext パラメーターは、次の属性を公開します。The executionContext parameter exposes the following attributes:

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

次の例では、センサー テレメトリの測定値が定義済みしきい値を超えた場合に、メッセージを記録します。In the next example, we log a message if the sensor telemetry reading surpasses a predefined threshold. Azure Digital Twins インスタンスで診断設定が有効になっている場合は、ユーザー定義関数からのログも転送されます。If your diagnostic settings are enabled on the Azure Digital Twins instance, logs from user-defined functions are also forwarded:

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!`);
  }
}

次のコードでは、温度レベルが定義済み定数を超えた場合に通知がトリガーされます。The following code triggers a notification if the temperature level rises above the predefined constant:

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));
  }
}

より複雑なユーザー定義関数のコード サンプルについては、占有率のクイック スタートに関するページをご覧ください。For a more complex user-defined function code sample, see the Occupancy quickstart.

役割の割り当ての作成Create a role assignment

ユーザー定義関数の実行に使われるロールの割り当てを作成します。Create a role assignment for the user-defined function to run under. ユーザー定義関数にロールが割り当てられていない場合、ユーザー定義関数には Management API と対話したり、グラフ オブジェクトで操作を実行したりするための適切なアクセス許可がありません。If no role assignment exists for the user-defined function, it won't have the proper permissions to interact with the Management API or have access to perform actions on graph objects. ユーザー定義関数で実行できるアクションは、Azure Digital Twins Management API 内のロールベースのアクセス制御によって指定および定義されます。Actions that a user-defined function may perform are specified and defined via role-based access control within the Azure Digital Twins Management APIs. たとえば、ユーザー定義関数の範囲は、特定のロールまたは特定のアクセス制御パスを指定することで限定できます。For example, user-defined functions can be limited in scope by specifying certain roles or certain access control paths. 詳しくは、ロールベースのアクセス制御のドキュメントをご覧ください。For more information, see the Role-based access control documentation.

  1. すべてのロールについてシステム API に対してクエリを実行して、ユーザー定義関数に割り当てるロール ID を取得します。Query the System API for all roles to get the role ID you want to assign to your user-defined function. そのためには、以下に対して認証済みの HTTP GET 要求を実行します。Do so by making an authenticated HTTP GET request to:

    YOUR_MANAGEMENT_API_URL/system/roles
    

    目的のロール ID を保持します。Keep the desired role ID. これは、下で JSON 本文属性 roleId (YOUR_DESIRED_ROLE_IDENTIFIER) として渡されます。It will be passed as the JSON body attribute roleId (YOUR_DESIRED_ROLE_IDENTIFIER) below.

  2. objectId (YOUR_USER_DEFINED_FUNCTION_ID) は先ほど作成したユーザー定義関数 ID になります。objectId (YOUR_USER_DEFINED_FUNCTION_ID) will be the user-defined function ID that was created earlier.

  3. fullpath を使用して空間に対してクエリを実行して、path (YOUR_ACCESS_CONTROL_PATH) の値を見つけます。Find the value of path (YOUR_ACCESS_CONTROL_PATH) by querying your spaces with fullpath.

  4. 返された spacePaths 値をコピーします。Copy the returned spacePaths value. 次のように使用します。You'll use that below. 以下に対して認証済みの HTTP GET 要求を実行します。Make an authenticated HTTP GET request to:

    YOUR_MANAGEMENT_API_URL/spaces?name=YOUR_SPACE_NAME&includes=fullpath
    
    Value 置換後の文字列Replace with
    YOUR_SPACE_NAMEYOUR_SPACE_NAME 使用する空間の名前The name of the space you wish to use
  5. 返された spacePaths 値を path に貼り付けて、認証済み HTTP POST 要求を以下に対して実行することでユーザー定義関数のロールの割り当てを作成します。Paste the returned spacePaths value into path to create a user-defined function role assignment by making an authenticated HTTP POST request to:

    YOUR_MANAGEMENT_API_URL/roleassignments
    

    JSON 本文は次のようになります。With JSON body:

    {
      "roleId": "YOUR_DESIRED_ROLE_IDENTIFIER",
      "objectId": "YOUR_USER_DEFINED_FUNCTION_ID",
      "objectIdType": "YOUR_USER_DEFINED_FUNCTION_TYPE_ID",
      "path": "YOUR_ACCESS_CONTROL_PATH"
    }
    
    Value 置換後の文字列Replace with
    YOUR_DESIRED_ROLE_IDENTIFIERYOUR_DESIRED_ROLE_IDENTIFIER 目的の役割の識別子The identifier for the desired role
    YOUR_USER_DEFINED_FUNCTION_IDYOUR_USER_DEFINED_FUNCTION_ID 使用するユーザー定義関数の IDThe ID for the user-defined function you want to use
    YOUR_USER_DEFINED_FUNCTION_TYPE_IDYOUR_USER_DEFINED_FUNCTION_TYPE_ID ユーザー定義関数の種類を指定する IDThe ID specifying the user-defined function type
    YOUR_ACCESS_CONTROL_PATHYOUR_ACCESS_CONTROL_PATH アクセス制御パスThe access control path

ヒント

ユーザー定義関数の Management API の操作とエンドポインについて詳しくは、ロールの割り当てを作成および管理する方法に関する記事をご覧ください。Read the article How to create and manage role assignments for more information about user-defined function Management API operations and endpoints.

処理するテレメトリを送信するSend telemetry to be processed

空間インテリジェンス グラフで定義されているセンサーによってテレメトリが送信されます。The sensor defined in the spatial intelligence graph sends telemetry. さらに、テレメトリでは、アップロードされたユーザー定義関数の実行がトリガーされます。In turn, the telemetry triggers the execution of the user-defined function that was uploaded. データ プロセッサがテレメトリを取得します。The data processor picks up the telemetry. 次に、ユーザー定義関数の呼び出し用の実行プランが作成されます。Then an execution plan is created for the invocation of the user-defined function.

  1. 測定値の生成元であるセンサーのマッチャーを取得します。Retrieve the matchers for the sensor the reading was generated from.
  2. どのマッチャーが正常に評価されたかに応じて、関連付けられているユーザー定義関数を取得します。Depending on what matchers were evaluated successfully, retrieve the associated user-defined functions.
  3. 各ユーザー定義関数を実行します。Execute each user-defined function.

次の手順Next steps