遙測、屬性和命令承載

發行項
05/13/2024

裝置傳送至服務的遙測。
裝置與服務同步的屬性。
服務在裝置上呼叫的命令。

提示

Azure IoT Central 是遵循即插即用慣例的服務。在 IoT Central 中，裝置模型是裝置範本的一部分。 IoT Central 目前支援具有 IoT Central 延伸模組的 DTDL v2。 IoT Central 應用程式預期會收到 UTF-8 編碼的 JSON 資料。

本文說明裝置傳送和接收的 JSON 承載，用於 DTDL 裝置模型中定義的遙測、屬性和命令。

本文不會說明每個可能類型的遙測、屬性和命令承載，但範例會說明關鍵類型。

每個範例會顯示裝置模型的程式碼片段，其會定義類型和範例 JSON 承載，藉以說明裝置如何與 IoT Central 等隨插即用感知服務互動。

本文中的範例 JSON 代碼段會使用 Digital Twin Definition Language （DTDL） v2。 IoT Central 也會使用一些 DTDL 延伸模組。

如需顯示其中一些使用中承載的範例裝置程式碼，請參閱將在 Linux 或 Windows 上執行的範例 IoT 隨插即用裝置應用程式連線至 IoT 中樞教學課程或建立用戶端應用程式並將其連線至您的 Azure IoT Central 應用程式教學課程。

檢視未經處理資料

如果您使用 IoT Central，則可以檢視裝置傳送至應用程式的未經處理資料。對於疑難排解從裝置傳送承載的問題，此檢視相當實用。若要檢視裝置傳送的未經處理資料：

從 [裝置] 頁面瀏覽至裝置。
選取 [未經處理資料] 索引標籤：

在此檢視中，您可以選取要顯示的資料行，並設定要檢視的時間範圍。 [未模型化的資料] 資料行會顯示裝置內不符合裝置範本中任何屬性或遙測定義的資料。

如需更多疑難排解秘訣，請參閱針對裝置中的資料未顯示在 Azure IoT Central 的原因進行疑難排解。

遙測

若要深入了解 DTDL 遙測命名規則，請參閱 DTDL > 遙測。您無法使用 _ 字元作為遙測名稱的開頭。

請勿使用下列名稱建立下列遙測類型。 IoT Central 會內部使用這些保留名稱。如果您嘗試使用這些名稱，IoT Central 將忽略您的資料：

EventEnqueuedUtcTime
EventProcessedUtcTime
PartitionId
EventHub
User
$metadata
$version

元件中的遙測

如果遙測是在元件中定義，請新增名為 $.sub 的訊息屬性及裝置模型中定義的元件名稱。若要深入了解，請參閱教學課程：連線 IoT 隨插即用多個元件裝置應用程式。本教學課程示範如何使用不同的程式設計語言，從元件傳送遙測。

重要

若要正確顯示在 IoT Edge 模組中裝載元件的遙測，請使用 IoT Edge 版本 1.2.4 或更新版本。如果您使用舊版本，IoT Edge 模組中元件的遙測會顯示為 _unmodeleddata。

繼承介面中的遙測

如果遙測是在繼承介面中定義，您的裝置就會傳送遙測，如同在根介面中定義一樣。指定下列裝置型號：

[
    {
        "@id": "dtmi:contoso:device;1",
        "@type": "Interface",
        "contents": [
            {
                "@type": [
                    "Property",
                    "Cloud",
                    "StringValue"
                ],
                "displayName": {
                    "en": "Device Name"
                },
                "name": "DeviceName",
                "schema": "string"
            }
        ],
        "displayName": {
            "en": "Contoso Device"
        },
        "extends": [
            "dtmi:contoso:sensor;1"
        ],
        "@context": [
            "dtmi:iotcentral:context;2",
            "dtmi:dtdl:context;2"
        ]
    },
    {
        "@context": [
            "dtmi:iotcentral:context;2",
            "dtmi:dtdl:context;2"
        ],
        "@id": "dtmi:contoso:sensor;1",
        "@type": [
            "Interface",
            "NamedInterface"
        ],
        "contents": [
            {
                "@type": [
                    "Telemetry",
                    "NumberValue"
                ],
                "displayName": {
                    "en": "Meter Voltage"
                },
                "name": "MeterVoltage",
                "schema": "double"
            }
        ],
        "displayName": {
            "en": "Contoso Sensor"
        },
        "name": "ContosoSensor"
    }
]

裝置會使用下列承載來傳送計量電壓遙測。裝置不包含承載中的介面名稱：

{
    "MeterVoltage": 5.07
}

基本類型

本節說明裝置可串流的基本遙測類型範本。

下列裝置模型的程式碼片段顯示 boolean 遙測類型的定義：

{
  "@type": "Telemetry",
  "displayName": {
    "en": "BooleanTelemetry"
  },
  "name": "BooleanTelemetry",
  "schema": "boolean"
}

裝置用戶端應以 JSON 的形式傳送遙測，如下列範例所示：

{ "BooleanTelemetry": true }

下列裝置模型的程式碼片段顯示 string 遙測類型的定義：

{
  "@type": "Telemetry",
  "displayName": {
    "en": "StringTelemetry"
  },
  "name": "StringTelemetry",
  "schema": "string"
}

裝置用戶端應以 JSON 的形式傳送遙測，如下列範例所示：

{ "StringTelemetry": "A string value - could be a URL" }

下列裝置模型的程式碼片段顯示 integer 遙測類型的定義：

{
  "@type": "Telemetry",
  "displayName": {
    "en": "IntegerTelemetry"
  },
  "name": "IntegerTelemetry",
  "schema": "integer"
}

裝置用戶端應以 JSON 的形式傳送遙測，如下列範例所示：

{ "IntegerTelemetry": 23 }

下列裝置模型的程式碼片段顯示 double 遙測類型的定義：

{
  "@type": "Telemetry",
  "displayName": {
    "en": "DoubleTelemetry"
  },
  "name": "DoubleTelemetry",
  "schema": "double"
}

裝置用戶端應以 JSON 的形式傳送遙測，如下列範例所示：

{ "DoubleTelemetry": 56.78 }

下列裝置模型的程式碼片段顯示 dateTime 遙測類型的定義：

{
  "@type": "Telemetry",
  "displayName": {
    "en": "DateTimeTelemetry"
  },
  "name": "DateTimeTelemetry",
  "schema": "dateTime"
}

裝置用戶端應以 JSON 的形式傳送遙測，如下列範例所示 - DateTime 類型的格式必須為 ISO 8061：

{ "DateTimeTelemetry": "2020-08-30T19:16:13.853Z" }

下列裝置模型的程式碼片段顯示 duration 遙測類型的定義：

{
  "@type": "Telemetry",
  "displayName": {
    "en": "DurationTelemetry"
  },
  "name": "DurationTelemetry",
  "schema": "duration"
}

裝置用戶端應以 JSON 的形式傳送遙測，如下列範例所示 - 持續時間的格式必須為 ISO 8601：

{ "DurationTelemetry": "PT10H24M6.169083011336625S" }

複雜類型

本節說明裝置可串流的複雜遙測類型範本。

下列裝置模型的程式碼片段顯示 Enum 遙測類型的定義：

{
  "@type": "Telemetry",
  "displayName": {
    "en": "EnumTelemetry"
  },
  "name": "EnumTelemetry",
  "schema": {
    "@type": "Enum",
    "displayName": {
      "en": "Enum"
    },
    "valueSchema": "integer",
    "enumValues": [
      {
        "displayName": {
          "en": "Item1"
        },
        "enumValue": 0,
        "name": "Item1"
      },
      {
        "displayName": {
          "en": "Item2"
        },
        "enumValue": 1,
        "name": "Item2"
      },
      {
        "displayName": {
          "en": "Item3"
        },
        "enumValue": 2,
        "name": "Item3"
      }
    ]
  }
}

裝置用戶端應以 JSON 的形式傳送遙測，如下列範例所示。可能的值為 0、1 和 2，其在 IoT Central 中顯示為 Item1、Item2 和 Item3：

{ "EnumTelemetry": 1 }

下列裝置模型的程式碼片段顯示 Object 遙測類型的定義。此物件有三個欄位，其類型為 dateTime、integer 和 Enum：

{
  "@type": "Telemetry",
  "displayName": {
    "en": "ObjectTelemetry"
  },
  "name": "ObjectTelemetry",
  "schema": {
    "@type": "Object",
    "displayName": {
      "en": "Object"
    },
    "fields": [
      {
        "displayName": {
          "en": "Property1"
        },
        "name": "Property1",
        "schema": "dateTime"
      },
      {
        "displayName": {
          "en": "Property2"
        },
        "name": "Property2",
        "schema": "integer"
      },
      {
        "displayName": {
          "en": "Property3"
        },
        "name": "Property3",
        "schema": {
          "@type": "Enum",
          "displayName": {
            "en": "Enum"
          },
          "valueSchema": "integer",
          "enumValues": [
            {
              "displayName": {
                "en": "Item1"
              },
              "enumValue": 0,
              "name": "Item1"
            },
            {
              "displayName": {
                "en": "Item2"
              },
              "enumValue": 1,
              "name": "Item2"
            },
            {
              "displayName": {
                "en": "Item3"
              },
              "enumValue": 2,
              "name": "Item3"
            }
          ]
        }
      }
    ]
  }
}

裝置用戶端應以 JSON 的形式傳送遙測，如下列範例所示。 DateTime 類型必須符合 ISO 8061 規範。 Property3 的可能值為 0、1，且在 IoT Central 中會顯示為 Item1、Item2 和 Item3：

{
  "ObjectTelemetry": {
      "Property1": "2020-09-09T03:36:46.195Z",
      "Property2": 37,
      "Property3": 2
  }
}

下列裝置模型的程式碼片段顯示 vector 遙測類型的定義：

{
  "@type": "Telemetry",
  "displayName": {
    "en": "VectorTelemetry"
  },
  "name": "VectorTelemetry",
  "schema": "vector"
}

裝置用戶端應以 JSON 的形式傳送遙測，如下列範例所示：

{
  "VectorTelemetry": {
    "x": 74.72395045538597,
    "y": 74.72395045538597,
    "z": 74.72395045538597
  }
}

下列裝置模型的程式碼片段顯示 geopoint 遙測類型的定義：

{
  "@type": "Telemetry",
  "displayName": {
    "en": "GeopointTelemetry"
  },
  "name": "GeopointTelemetry",
  "schema": "geopoint"
}

注意

geopoint 結構描述類型是 DTDL IoT Central 延伸模組的一部分。為顧及回溯相容性，IoT Central 目前支援 geopoint 結構描述類型和 location 語意類型。

裝置用戶端應以 JSON 的形式傳送遙測，如下列範例所示。 IoT Central 會顯示值作為地圖上的釘選：

{
  "GeopointTelemetry": {
    "lat": 47.64263,
    "lon": -122.13035,
    "alt": 0
  }
}

事件和狀態類型

本節會顯示裝置傳送至 IoT Central 應用程式的遙測事件和狀態範例。

注意

事件和狀態結構描述類型是 DTDL IoT Central 延伸模組的一部分。

下列裝置模型的程式碼片段顯示 integer 事件類型的定義：

{
  "@type": [
    "Telemetry",
    "Event"
  ],
  "displayName": {
    "en": "IntegerEvent"
  },
  "name": "IntegerEvent",
  "schema": "integer"
}

裝置用戶端應以 JSON 的形式傳送事件資料，如下列範例所示：

{ "IntegerEvent": 74 }

下列裝置模型的程式碼片段顯示 integer 狀態類型的定義：

{
  "@type": [
    "Telemetry",
    "State"
  ],
  "displayName": {
    "en": "IntegerState"
  },
  "name": "IntegerState",
  "schema": {
    "@type": "Enum",
    "valueSchema": "integer",
    "enumValues": [
      {
        "displayName": {
          "en": "Level1"
        },
        "enumValue": 1,
        "name": "Level1"
      },
      {
        "displayName": {
          "en": "Level2"
        },
        "enumValue": 2,
        "name": "Level2"
      },
      {
        "displayName": {
          "en": "Level3"
        },
        "enumValue": 3,
        "name": "Level3"
      }
    ]
  }
}

裝置用戶端應以 JSON 的形式傳送狀態，如下列範例所示。可能的整數狀態值為 1、2 或 3：

{ "IntegerState": 2 }

屬性

若要深入了解 DTDL 屬性命名規則，請參閱 DTDL > 屬性。您無法使用 _ 字元作為屬性名稱的開頭。

元件中的屬性

如果屬性是在元件中定義，請將屬性包裝在元件名稱中。下列範例會設定 thermostat2 元件中的 maxTempSinceLastReboot。標記 __t 表示此區段會定義元件：

{
  "thermostat2" : {  
    "__t" : "c",  
    "maxTempSinceLastReboot" : 38.7
    } 
}

若要深入了解，請參閱教學課程：建立用戶端應用程式並將其連線至您的 Azure IoT Central 應用程式。

基本類型

本節說明裝置傳送至服務的基本屬性類型範圍。

下列裝置模型的程式碼片段顯示 boolean 屬性類型的定義：

{
  "@type": "Property",
  "displayName": {
    "en": "BooleanProperty"
  },
  "name": "BooleanProperty",
  "schema": "boolean",
  "writable": false
}

裝置用戶端應傳送 JSON 承載作為裝置對應項中的報告屬性，如下列範例所示：

{ "BooleanProperty": false }

下列裝置模型的程式碼片段顯示 long 屬性類型的定義：

{
  "@type": "Property",
  "displayName": {
    "en": "LongProperty"
  },
  "name": "LongProperty",
  "schema": "long",
  "writable": false
}

裝置用戶端應傳送 JSON 承載作為裝置對應項中的報告屬性，如下列範例所示：

{ "LongProperty": 439 }

下列裝置模型的程式碼片段顯示 date 屬性類型的定義：

{
  "@type": "Property",
  "displayName": {
    "en": "DateProperty"
  },
  "name": "DateProperty",
  "schema": "date",
  "writable": false
}

裝置用戶端應傳送 JSON 承載作為裝置對應項中的報告屬性，如下列範例所示。 Date 類型必須符合 ISO 8061 規範：

{ "DateProperty": "2020-05-17" }

下列裝置模型的程式碼片段顯示 duration 屬性類型的定義：

{
  "@type": "Property",
  "displayName": {
    "en": "DurationProperty"
  },
  "name": "DurationProperty",
  "schema": "duration",
  "writable": false
}

裝置用戶端應傳送 JSON 承載作為裝置對應項中的報告屬性 - 持續時間必須符合 ISO 8601 規範，如下列範例所示：

{ "DurationProperty": "PT10H24M6.169083011336625S" }

下列裝置模型的程式碼片段顯示 float 屬性類型的定義：

{
  "@type": "Property",
  "displayName": {
    "en": "FloatProperty"
  },
  "name": "FloatProperty",
  "schema": "float",
  "writable": false
}

裝置用戶端應傳送 JSON 承載作為裝置對應項中的報告屬性，如下列範例所示：

{ "FloatProperty": 1.9 }

下列裝置模型的程式碼片段顯示 string 屬性類型的定義：

{
  "@type": "Property",
  "displayName": {
    "en": "StringProperty"
  },
  "name": "StringProperty",
  "schema": "string",
  "writable": false
}

裝置用戶端應傳送 JSON 承載作為裝置對應項中的報告屬性，如下列範例所示：

{ "StringProperty": "A string value - could be a URL" }

複雜類型

本節說明裝置傳送至服務的複雜屬性類型範圍。

下列裝置模型的程式碼片段顯示 Enum 屬性類型的定義：

{
  "@type": "Property",
  "displayName": {
    "en": "EnumProperty"
  },
  "name": "EnumProperty",
  "writable": false,
  "schema": {
    "@type": "Enum",
    "displayName": {
      "en": "Enum"
    },
    "valueSchema": "integer",
    "enumValues": [
      {
        "displayName": {
          "en": "Item1"
        },
        "enumValue": 0,
        "name": "Item1"
      },
      {
        "displayName": {
          "en": "Item2"
        },
        "enumValue": 1,
        "name": "Item2"
      },
      {
        "displayName": {
          "en": "Item3"
        },
        "enumValue": 2,
        "name": "Item3"
      }
    ]
  }
}

裝置用戶端應傳送 JSON 承載作為裝置對應項中的報告屬性，如下列範例所示。可能的值為 0、1，其在 IoT Central 中顯示為 Item1、Item2 和 Item3：

{ "EnumProperty": 1 }

下列裝置模型的程式碼片段顯示 Object 屬性類型的定義。此物件有兩個欄位，其類型為 string 和 integer：

{
  "@type": "Property",
  "displayName": {
    "en": "ObjectProperty"
  },
  "name": "ObjectProperty",
  "writable": false,
  "schema": {
    "@type": "Object",
    "displayName": {
      "en": "Object"
    },
    "fields": [
      {
        "displayName": {
          "en": "Field1"
        },
        "name": "Field1",
        "schema": "integer"
      },
      {
        "displayName": {
          "en": "Field2"
        },
        "name": "Field2",
        "schema": "string"
      }
    ]
  }
}

裝置用戶端應傳送 JSON 承載作為裝置對應項中的報告屬性，如下列範例所示：

{
  "ObjectProperty": {
    "Field1": 37,
    "Field2": "A string value"
  }
}

下列裝置模型的程式碼片段顯示 vector 屬性類型的定義：

{
  "@type": "Property",
  "displayName": {
    "en": "VectorProperty"
  },
  "name": "VectorProperty",
  "schema": "vector",
  "writable": false
}

裝置用戶端應傳送 JSON 承載作為裝置對應項中的報告屬性，如下列範例所示：

{
  "VectorProperty": {
    "x": 74.72395045538597,
    "y": 74.72395045538597,
    "z": 74.72395045538597
  }
}

下列裝置模型的程式碼片段顯示 geopoint 屬性類型的定義：

{
  "@type": "Property",
  "displayName": {
    "en": "GeopointProperty"
  },
  "name": "GeopointProperty",
  "schema": "geopoint",
  "writable": false
}

注意

geopoint 結構描述類型是 DTDL IoT Central 延伸模組的一部分。為顧及回溯相容性，IoT Central 目前支援 geopoint 結構描述類型和 location 語意類型。

裝置用戶端應傳送 JSON 承載作為裝置對應項中的報告屬性，如下列範例所示：

{
  "GeopointProperty": {
    "lat": 47.64263,
    "lon": -122.13035,
    "alt": 0
  }
}

可寫入的屬性類型

本節說明裝置從服務接收的可寫入屬性類型範例。

如果可寫入的屬性是在元件中定義，所需屬性訊息會包含元件名稱。下列範例顯示要求裝置更新 thermostat2 元件中 targetTemperature 的訊息。標記 __t 表示此區段會定義元件：

{
  "thermostat2": {
    "targetTemperature": {
      "value": 57
    },
    "__t": "c"
  },
  "$version": 3
}

若要深入了解，請參閱連線 IoT 隨插即用多個元件裝置應用程式。

裝置或模組應該藉由傳送報告屬性來確認其已接收屬性。報告的屬性應該包括：

value - 屬性的實際值 (通常接收的值，但裝置可能會決定報告不同的值)。
ac - 使用 HTTP 狀態碼的確認代碼。
av - 參考所需屬性 $version 的確認版本。您可以在所需的屬性 JSON 承載中找到此值。
ad - 選擇性確認描述。

若要深入了解這些欄位，請參閱 IoT 隨插即用慣例 > 通知回應

下列裝置模型的程式碼片段顯示可寫入 string 屬性類型的定義：

{
  "@type": "Property",
  "displayName": {
    "en": "StringPropertyWritable"
  },
  "name": "StringPropertyWritable",
  "writable": true,
  "schema": "string"
}

裝置會收到來自服務的下列承載：

{  
  "StringPropertyWritable": "A string from IoT Central", "$version": 7
}

裝置處理更新之後，應將下列 JSON 承載傳送至服務。此訊行包含自服務所接收原始更新的版本號碼。

提示

如果服務為 IoT Central，則當其收到此訊息時，會在 UI 中將屬性標示為 [已同步]：

{
  "StringPropertyWritable": {
    "value": "A string from IoT Central",
    "ac": 200,
    "ad": "completed",
    "av": 7
  }
}

下列裝置模型的程式碼片段顯示可寫入 Enum 屬性類型的定義：

{
  "@type": "Property",
  "displayName": {
    "en": "EnumPropertyWritable"
  },
  "name": "EnumPropertyWritable",
  "writable": true,
  "schema": {
    "@type": "Enum",
    "displayName": {
      "en": "Enum"
    },
    "valueSchema": "integer",
    "enumValues": [
      {
        "displayName": {
          "en": "Item1"
        },
        "enumValue": 0,
        "name": "Item1"
      },
      {
        "displayName": {
          "en": "Item2"
        },
        "enumValue": 1,
        "name": "Item2"
      },
      {
        "displayName": {
          "en": "Item3"
        },
        "enumValue": 2,
        "name": "Item3"
      }
    ]
  }
}

裝置會收到來自服務的下列承載：

{  
  "EnumPropertyWritable":  1 , "$version": 10
}

裝置處理更新之後，應將下列 JSON 承載傳送至服務。此訊行包含自服務所接收原始更新的版本號碼。

提示

如果服務為 IoT Central，則當其收到此訊息時，會在 UI 中將屬性標示為 [已同步]：

{
  "EnumPropertyWritable": {
    "value": 1,
    "ac": 200,
    "ad": "completed",
    "av": 10
  }
}

命令

若要深入了解 DTDL 命令命名規則，請參閱 DTDL > 命令。您無法使用 _ 字元作為命名名稱的開頭。

如果命令是在元件中定義，裝置接收的命令名稱包含元件名稱。例如，如果命令稱為 getMaxMinReport 而元件稱為 thermostat2，則裝置會收到執行名為 thermostat2*getMaxMinReport 命令的要求。

下列裝置模型的程式碼片段會顯示沒有參數且不會預期裝置傳回任何項目的命令定義：

{
  "@type": "Command",
  "displayName": {
    "en": "CommandBasic"
  },
  "name": "CommandBasic"
}

裝置會在要求中收到空白承載並應會在回應中傳回空白承載，其中包含 200 HTPP 回應碼來表示成功。

下列裝置模型的程式碼片段會顯示具有整數參數且預期裝置傳送整數值的命令定義：

{
  "@type": "Command",
  "request": {
    "@type": "CommandPayload",
    "displayName": {
      "en": "RequestParam"
    },
    "name": "RequestParam",
    "schema": "integer"
  },
  "response": {
    "@type": "CommandPayload",
    "displayName": {
      "en": "ResponseParam"
    },
    "name": "ResponseParam",
    "schema": "integer"
  },
  "displayName": {
    "en": "CommandSimple"
  },
  "name": "CommandSimple"
}

裝置會收到整數值作為要求承載。裝置應傳回整數值作為回應承載，其中包含 200 HTTP 回應碼以表示成功。

下列裝置模型的程式碼片段顯示具有物件參數且預期裝置傳回物件的命令定義。在此範例中，兩個物件皆有整數和字串欄位：

{
  "@type": "Command",
  "request": {
    "@type": "CommandPayload",
    "displayName": {
      "en": "RequestParam"
    },
    "name": "RequestParam",
    "schema": {
      "@type": "Object",
      "displayName": {
        "en": "Object"
      },
      "fields": [
        {
          "displayName": {
            "en": "Field1"
          },
          "name": "Field1",
          "schema": "integer"
        },
        {
          "displayName": {
            "en": "Field2"
          },
          "name": "Field2",
          "schema": "string"
        }
      ]
    }
  },
  "response": {
    "@type": "CommandPayload",
    "displayName": {
      "en": "ResponseParam"
    },
    "name": "ResponseParam",
    "schema": {
      "@type": "Object",
      "displayName": {
        "en": "Object"
      },
      "fields": [
        {
          "displayName": {
            "en": "Field1"
          },
          "name": "Field1",
          "schema": "integer"
        },
        {
          "displayName": {
            "en": "Field2"
          },
          "name": "Field2",
          "schema": "string"
        }
      ]
    }
  },
  "displayName": {
    "en": "CommandComplex"
  },
  "name": "CommandComplex"
}

下列程式碼片段顯示傳送至裝置的範例要求承載：

{ "Field1": 56, "Field2": "A string value" }

下列程式碼片段顯示從裝置傳送的範例回應承載。使用 200 HTTP 回應碼來表示成功：

{ "Field1": 87, "Field2": "Another string value" }

提示

IoT Central 有自己的慣例，可實作長時間執行的命令和離線命令。

下一步

既然您已了解裝置承載，建議的後續步驟是閱讀裝置開發人員指南。

共用方式為

遙測、屬性和命令承載

檢視未經處理資料

遙測

元件中的遙測

繼承介面中的遙測

基本類型

複雜類型

事件和狀態類型

屬性

元件中的屬性

基本類型

複雜類型

可寫入的屬性類型

命令

下一步

其他資源