Azure Digital Twins でユーザー定義関数をデバッグする方法

重要

Azure Digital Twins サービスの新しいバージョンがリリースされました。新しいサービスの拡張機能に照らして、元の Azure Digital Twins サービス (このドキュメントセットで説明) は廃止されました。

新しいサービスのドキュメントを表示するには、アクティブな Azure Digital Twins のドキュメントを参照してください。

この記事では、Azure Digital Twins でユーザー定義関数を診断およびデバッグする方法について説明します。次に、デバッグ時に見つかった最も一般的なシナリオの一部を識別します。

ヒント

アクティビティログ、診断ログ、Azure Monitor を使用して Azure Digital Twins でデバッグツールを設定する方法の詳細については、「監視とログ記録のを構成する方法」を参照してください。

問題のデバッグ

Azure Digital Twins 内の問題を診断する方法を知ることで、問題を効果的に分析し、問題の原因を特定し、それらに適切な解決策を提供することができます。

その最後には、さまざまなログ記録、分析、診断ツールが用意されています。

インスタンスのログ記録を有効にする

Azure Digital Twins では、堅牢なログ記録、監視、分析がサポートされています。ソリューション開発者は、Azure Monitor ログ、診断ログ、アクティビティログ、およびその他のサービスを使用して、IoT アプリの複雑な監視ニーズをサポートできます。ログオプションを組み合わせて、複数のサービス間でレコードのクエリまたは表示を行ったり、多くのサービスに詳細なログ記録範囲を提供したりできます。

Azure Digital Twins に固有のログ記録構成については、「監視とログ記録のを構成する方法」を参照してください。
Azure Monitor で有効になっている強力なログ設定については、Azure Monitor の概要を参照してください。
Azure portal、Azure CLI、または PowerShell を使用して Azure Digital Twins で診断ログ設定を構成する、Azure リソースからログデータを収集して使用する記事を確認します。

構成したら、すべてのログカテゴリ、メトリックを選択し、強力な Azure Monitor ログ分析ワークスペースを使用してデバッグ作業をサポートできるようになります。

トレースセンサーのテレメトリー

センサーテレメトリをトレースするには、Azure Digital Twins インスタンスの診断設定が有効になっていることを確認します。次に、必要なすべてのログカテゴリが選択されていることを確認します。最後に、目的のログが Azure Monitor ログに送信されていることを確認します。

センサーテレメトリメッセージをそれぞれのログと照合するには、送信するイベントデータに関連付け ID を指定します。これを行うには、x-ms-client-request-id プロパティを GUID に設定します。

テレメトリを送信した後、Azure Monitor ログ分析を開き、設定された関連付け ID を使用してログを照会します。

AzureDiagnostics
| where CorrelationId == 'YOUR_CORRELATION_IDENTIFIER'

クエリ値	に置き換える
あなたの相関識別子	イベントデータで指定された関連付け ID

最近のすべてのテレメトリログクエリを読み取る方法:

AzureDiagnostics
| order by CorrelationId desc

ユーザー定義関数のログ記録を有効にした場合、それらのログは、カテゴリ UserDefinedFunctionと共にログ分析インスタンスに表示されます。それらを取得するには、ログ分析で次のクエリ条件を入力します。

AzureDiagnostics
| where Category == 'UserDefinedFunction'

強力なクエリ操作の詳細については、「クエリの概要」を参照してください。

一般的な問題を特定する

ソリューションのトラブルシューティングでは、一般的な問題の診断と特定の両方が重要です。次のサブセクションでは、ユーザー定義関数の開発時に一般的に発生する問題をいくつかまとめます。

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

ロールの割り当てが作成されたかどうかを確認する

Management API 内で作成されたロールの割り当てがない場合、ユーザー定義関数は、通知の送信、メタデータの取得、トポロジ内での計算値の設定などのアクションを実行するためのアクセス権を持ちません。

Management API を使用して、ユーザー定義関数のロールの割り当てが存在するかどうかを確認します。

GET YOUR_MANAGEMENT_API_URL/roleassignments?path=/&traverse=Down&objectId=YOUR_USER_DEFINED_FUNCTION_ID

パラメーター値	に置き換える
YOUR_USER_DEFINED_FUNCTION_ID	ロールの割り当てを取得するユーザー定義関数の ID

ロールの割り当てが存在しない場合に、ユーザー定義関数のロールの割り当てを作成する方法について説明します。

マッチャーがセンサーのテレメトリに対して正しく動作するかどうかを確認する

Azure Digital Twins インスタンスの Management API に対して次の呼び出しを行うと、特定のマッチャーが特定のセンサーに適用されるかどうかを判断できます。

GET YOUR_MANAGEMENT_API_URL/matchers/YOUR_MATCHER_IDENTIFIER/evaluate/YOUR_SENSOR_IDENTIFIER?enableLogging=true

パラメーター	に置き換える
YOUR_MATCHER_IDENTIFIER	評価するマッチャーの ID
YOUR_SENSOR_IDENTIFIER	評価するセンサーの ID

応答:

{
    "success": true,
    "logs": [
        "$.dataType: \"Motion\" Equals \"Motion\" => True"
    ]
}

センサーがトリガーする内容を確認する

Azure Digital Twins Management API に対して次の呼び出しを行うと、特定のセンサーの受信テレメトリによってトリガーされるユーザー定義関数の識別子を特定できます。

GET YOUR_MANAGEMENT_API_URL/sensors/YOUR_SENSOR_IDENTIFIER/matchers?includes=UserDefinedFunctions

パラメーター	に置き換える
YOUR_SENSOR_IDENTIFIER	テレメトリを送信するセンサーの ID

応答:

[
    {
        "id": "48a64768-797e-4832-86dd-de625f5f3fd9",
        "name": "MotionMatcher",
        "spaceId": "2117b3e1-b6ce-42c1-9b97-0158bef59eb7",
        "conditions": [
            {
                "id": "024a067a-414f-415b-8424-7df61392541e",
                "target": "Sensor",
                "path": "$.dataType",
                "value": "\"Motion\"",
                "comparison": "Equals"
            }
        ],
        "userDefinedFunctions": [
            {
                "id": "373d03c5-d567-4e24-a7dc-f993460120fc",
                "spaceId": "2117b3e1-b6ce-42c1-9b97-0158bef59eb7",
                "name": "Motion User-Defined Function",
                "disabled": false
            }
        ]
    }
]

通知の受信に関する問題

トリガーされたユーザー定義関数から通知を受け取らない場合は、トポロジオブジェクトの型パラメーターが、使用されている識別子の型と一致することを確認します。

正しくない の例:

var customNotification = {
    Message: 'Custom notification that will not work'
};

sendNotification(telemetry.SensorId, "Space", JSON.stringify(customNotification));

このシナリオは、指定されたトポロジオブジェクトの種類が Spaceされている間に、使用される識別子がセンサーを参照しているために発生します。

正しい の例:

var customNotification = {
    Message: 'Custom notification that will work'
};

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

この問題を解決しない最も簡単な方法は、メタデータオブジェクトで Notify メソッドを使用することです。

例：

function process(telemetry, executionContext) {
    var sensorMetadata = getSensorMetadata(telemetry.SensorId);

    var customNotification = {
        Message: 'Custom notification'
    };

    // Short-hand for above methods where object type is known from metadata.
    sensorMetadata.Notify(JSON.stringify(customNotification));
}

一般的な診断例外

診断設定を有効にすると、次の一般的な例外が発生する可能性があります。

スロットリング: ユーザー定義関数が「サービスの制限」記事で説明されている実行レート制限を超える場合、制限されます。調整制限の有効期限が切れるまで、それ以上の操作は正常に実行されません。
Data Not Found: ユーザー定義関数が存在しないメタデータにアクセスしようとすると、操作は失敗します。
承認されていない: ユーザー定義関数にロールの割り当てが設定されていないか、トポロジから特定のメタデータにアクセスするための十分なアクセス許可がない場合、操作は失敗します。

次のステップ

Azure Digital Twins で監視とログを有効にする方法について説明します。
その他の Azure ログオプションについては、Azure アクティビティログの概要記事を参照してください。

Last updated on 2020-01-21