遙測、屬性和命令承載

發行項
02/06/2024

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

提示

Azure IoT Central 是遵循隨插即用慣例的服務。在 IoT Central 中，裝置型號是裝置範本的一部分。 IoT Central 目前支援具有 IoT Central 擴充功能的 DTDL v2。 IoT Central 應用程式預期會收到 UTF-8 編碼的 JSON 數據。

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

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

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

本文中的範例 JSON 代碼段會使用 Digital Twin Definition Language （DTDL） V2。 IoT Central 也會使用一些 DTDL 擴充功能。

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

檢視原始數據

如果您使用IoT Central，您可以檢視裝置傳送給應用程式的原始資料。此檢視適用於針對從裝置傳送的承載問題進行疑難解答。若要檢視裝置正在傳送的原始資料：

從 [裝置 ] 頁面流覽至裝置。
選取 [ 原始資料] 索引 標籤：

在此檢視上，您可以選取要顯示的數據行，並設定要檢視的時間範圍。 Unmodeled 資料行會顯示不符合裝置範本中任何屬性或遙測定義的裝置數據。

如需更多疑難解答秘訣，請參閱針對來自您裝置的數據未顯示在 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，如下列範例所示。可能的值為、 1和，這些2值0會顯示在 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會顯示在 IoT Central 中，例如 Item1、 Item2和 Item3： 10

{
  "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 目前支援 地理點 架構類型和位置語意類型，以提供回溯相容性。

裝置客戶端應該將遙測傳送為 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 > 屬性。您無法使用 _ 字元啟動屬性名稱。

元件中的屬性

如果屬性是在元件中定義，請將屬性包裝在元件名稱中。下列範例會設定 maxTempSinceLastReboot 元件中的 thermostat2 。標記 __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會顯示在 IoT Central 中，如 Item1、 Item2和 Item3： 1

{ "EnumProperty": 1 }

來自裝置模型的下列代碼段會顯示屬性類型的定義 Object 。此物件有兩個具有類型和 stringinteger的欄位：

{
  "@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 目前支援 地理點 架構類型和位置語意類型，以提供回溯相容性。

裝置客戶端應該傳送類似下列範例的 JSON 承載，作為裝置對應項中的報告屬性：

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

可寫入的屬性類型

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

如果在元件中定義可寫入屬性，所需的屬性訊息會包含元件名稱。下列範例顯示要求裝置在元件中更新 targetTemperature 的 thermostat2 訊息。標記 __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 HTTP 回應碼傳回回應中空的承載，以指出成功。

裝置模型中的下列代碼段會顯示具有整數參數且預期裝置傳回整數值的命令定義：

{
  "@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 有自己的慣例，可實作長時間執行的命令和離線命令。

下一步

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

遙測、屬性和命令承載

檢視原始數據

遙測

元件中的遙測

繼承介面中的遙測

基本類型

複雜類型

事件和狀態類型

屬性

元件中的屬性

基本類型

複雜類型

可寫入的屬性類型

命令

下一步

其他資源