如何使用 IotJsonPathContent 範本搭配醫療技術服務裝置對應

發行項
05/16/2024

本文提供如何在醫療技術服務裝置對應中使用 IotJsonPathContent 範本的概觀。

IotJsonPathContent 範本基礎

當醫療技術服務從 Azure IoT 中樞擷取裝置訊息路由時，可以使用 IotJsonPathContent 範本。當 IotJsonPathContent 範本用於裝置對應時，醫療技術服務會從 IoT 中樞提供的中繼資料擷取裝置識別碼和度量時間戳記。 DeviceIdExpression 和 TimestampExpression 不應該包含在 IotJsonPathContent 範本中。

醫療技術服務 IotJsonPathContent 範本支援 JSON 運算式語言 JSONPath。運算式可用來識別要與指定 JSON 裝置訊息搭配使用的範本 (例如：TypeMatchExpression)，以及擷取建立正規化訊息所需的特定值 (例如：PatientIdExpression、ValueExpression 等)。 IotJsonPathContent 範本與 CalculatedContent 範本相似，除了 DeviceIdExpression 和 TimestampExpression 不支援以外。

注意

IotJsonPathContent 範本不支援 JMESPath。

運算式定義為：

<name of expression> : <the expression>

在以下範例中，typeMatchExpression 定義為：

"templateType": "IotJsonPathContent",
"template": {
   "typeName": "heartrate",
   "typeMatchExpression": "$..[?(@heartRate)]",
...
}

如果您的醫療技術服務設定為從 IoT 中樞內嵌裝置訊息，您就不需要使用 IotJsonPathContent 範本。假設您已正確定義 DeviceIdExpression 和 TimestampExpression，CalculatedContent 範本可以使用。

IotJsonPathContent 範本允許透過下列運算式，從 Azure 事件中樞事件中樞讀取的裝置訊息中比對和擷取：

元素	描述	JSONPath 運算式範例
typeMatchExpression	醫療技術服務針對裝置訊息承載評估的運算式。如果服務找到符合權杖值，它會將範本視為相符專案。	`$..[?(@heartRate)]`
patientIdExpression	用於擷取病患識別碼的運算式。醫療技術服務的解析類型設定為建立時，則為必要；醫療技術服務的解析類型設定為查詢時，則為選用。	`$.SystemProperties.iothub-connection-device-id`
encounterIdExpression	選擇性：用於擷取就診事件識別碼的運算式。	`$.Body.encounterId`
correlationIdExpression	選擇性：用於擷取相互關聯識別碼的運算式。您可以使用此輸出將值分組為 FHIR® 目的地對應中的單一觀察。	`$.Body.correlationId`
values[].valueExpression	用於擷取所需值的運算式。	`$.Body.heartRate`

重要

醫療技術服務會使用 IoT 中樞中定義的裝置識別碼作為 FHIR 資源裝置識別碼。如果醫療技術服務設定為使用查詢的身分識別解析類型，則具有相符裝置標識碼的裝置資源必須存在於 FHIR 服務中，否則會在處理裝置訊息時發生錯誤。如果醫療技術服務的身分識別解析類型設定為建立，則必須將 patientIdExpression 包含在裝置對應中，以便在尚未存在時建立新的病患資源和裝置資源。

注意

解析類型指定醫療技術服務如何將裝置資料和裝置資源與病患資源產生關聯。醫療技術服務會使用裝置識別碼和病患識別碼，從 FHIR 服務讀取裝置和病患資源。如果指定遇到標識碼並從裝置資料承載擷取，則如果具有該識別碼的 FHIR 服務上存在遇到，則會連結到觀察。如果遇到識別碼成功正規化，但找不到遇到識別碼的 FHIR，則會擲回 FhirResourceNotFound 例外狀況。如需設定醫療技術服務解析類型的詳細資訊，請參閱設定目的地索引標籤。

運算式語言

JSONPath 是預設運算式語言，且不支援在 IotJsonPathContent 範本中包含運算式語言。如果您嘗試在運算式物件中指定運算式語言，則包含運算式物件的 IotJsonPathContent 範本會失敗。

"templateType": "IotJsonPathContent",
   "template": {
      "typeName": "heartrate",
      "typeMatchExpression": "$..[?(@heartRate)]",
...
}

提示

如需 JSONPath 詳細資訊，請參閱 JSONPath - XPath for JSON。 IotJsonPathContent 範本會使用 JSON .NET 實作以解析 JSON Path 運算式。

範例

醫療技術服務處理裝置訊息時，CollectionContent 中的範本會用於評估訊息。 typeMatchExpression 用於判斷範本是否應該用於從裝置訊息建立正規化訊息。如果 typeMatchExpression 評估為 true，則會使用 valueExpression 值，從裝置訊息中尋找和擷取 JSON 值，並建立正規化訊息。

提示

Visual Studio Code 搭配 Azure IoT 中樞擴充功能是將 IoT 裝置訊息傳送至 IoT 中樞以進行測試和疑難排解的建議方法。

您可以使用醫療技術服務對應偵錯工具，協助建立、更新及疑難排解醫療技術服務裝置和 FHIR 目的地對應。對應偵錯工具可讓您輕鬆即時檢視和進行內嵌調整，無需離開 Azure 入口網站。對應偵錯工具也可用來上傳測試裝置訊息，以查看處理為規範訊息並轉換成 FHIR 觀察之後看起來的樣子。

在此範例中，我們使用擷取 heartRate 資料的裝置訊息：

{
    "PatientId": "patient1",
    "HeartRate" : "78"
}

注意

為了避免裝置到雲端 (D2C) 訊息中的裝置詐騙，Azure IoT 中樞會先使用其他屬性擴充所有裝置訊息，再將訊息路由傳送至事件中樞。例如：屬性：iothub-creation-time-utc 和 SystemProperties：iothub-connection-device-id。如需詳細資訊，請參閱反詐騙屬性。

patientIdExpression只有在建立模式中的醫療技術服務才需要，不過，如果使用查閱，則具有相符裝置識別碼的裝置資源必須存在於目的地 FHIR 服務中。這些範例假設您的醫療技術服務處於建立模式。如需建立和查閱目的地屬性的詳細資訊，請參閱設定目的地索引標籤。

IoT 中樞會在醫療技術服務從事件中樞讀取裝置訊息之前，擴充裝置訊息並將其路由傳送至事件中樞：

{
    "Body": {
        "PatientId": "patient1",
        "HeartRate": "78"
    },
    "SystemProperties": {
        "iothub-enqueuedtime": "2023-07-25T20:41:26.046Z",
        "iothub-connection-device-id": "sampleDeviceId"
    },
    "Properties": {
        "iothub-creation-time-utc": "2023-07-25T20:41:26.046Z"
    }
}

我們在正規化階段使用此裝置對應：

{
    "templateType": "CollectionContent",
    "template": [
        {
            "templateType": "IotJsonPathContent",
            "template": {
                "typeName": "HeartRate",
                "typeMatchExpression": "$..[?(@Body.HeartRate)]",
                "patientIdExpression": "$.Body.PatientId",
                "values": [
                    {
                        "required": true,
                        "valueExpression": "$.Body.HeartRate",
                        "valueName": "HeartRate"
                    }
                ]
            }
        }
    ]    
}

產生的正規化訊息在正規化階段之後，會變成這樣：

{
    "type": "HeartRate",
    "occurrenceTimeUtc": "2023-07-25T20:41:26.046Z",
    "deviceId": "sampleDeviceId",
    "patientId": "patient1",
    "properties": [
        {
            "name": "HeartRate",
            "value": "78"
        }
    ]
}

提示

如需修正常見醫療技術服務部署錯誤的協助，請參閱醫療技術服務部署錯誤疑難排解。

如需修正醫療技術服務錯誤的協助，請參閱使用醫療技術服務記錄，進行錯誤疑難排解。