Payload telemetri, properti, dan perintah

Artikel
02/06/2024

Model perangkat mendefinisikan:

Telemetri yang dikirim perangkat ke layanan.
Properti yang disinkronkan perangkat dengan layanan.
Perintah yang dipanggil layanan pada perangkat.

Tip

Azure IoT Central adalah layanan yang mengikuti konvensi Plug and Play. Di IoT Central, model perangkat adalah bagian dari templat perangkat. IoT Central saat ini mendukung DTDL v2 dengan ekstensi IoT Central. Aplikasi IoT Central mengharapkan untuk menerima data JSON yang dikodekan UTF-8.

Artikel ini menjelaskan payload JSON yang dikirim dan diterima perangkat untuk telemetri, properti, dan perintah yang ditentukan dalam model perangkat DTDL.

Artikel ini tidak menjelaskan setiap jenis payload telemetri, properti, dan perintah yang mungkin, tetapi contohnya menggambarkan jenis kunci.

Setiap contoh menunjukkan cuplikan dari model perangkat yang menentukan jenis dan contoh payload JSON untuk menggambarkan bagaimana perangkat harus berinteraksi dengan layanan sadar Plug and Play seperti IoT Central.

Contoh cuplikan JSON dalam artikel ini menggunakan Digital Twin Definition Language (DTDL) V2. Ada juga beberapa ekstensi DTDL yang digunakan IoT Central .

Untuk contoh kode perangkat yang menunjukkan beberapa payload ini yang digunakan, lihat Koneksi contoh aplikasi perangkat IoT Plug and Play yang berjalan di Tutorial Linux atau Windows ke IoT Hub atau tutorial Membuat dan menyambungkan aplikasi klien ke aplikasi Azure IoT Central Anda.

Menampilkan data mentah

Jika Anda menggunakan IoT Central, Anda dapat melihat data mentah yang dikirim perangkat ke aplikasi. Tampilan ini berguna untuk memecahkan masalah dengan payload yang dikirim dari perangkat. Untuk melihat data mentah yang dikirim perangkat:

Navigasikan ke perangkat dari halaman Perangkat.
Pilih tab Data mentah:

Pada tampilan ini, Anda dapat memilih kolom yang akan ditampilkan dan mengatur rentang waktu untuk ditampilkan. Kolom Data yang tidak dimodelkan memperlihatkan data dari perangkat yang tidak cocok dengan definisi properti atau telemetri apa pun di templat perangkat.

Untuk tips pemecahan masalah selengkapnya, lihat Memecahkan masalah mengapa data dari perangkat Anda tidak muncul di Azure IoT Central.

telemetri

Untuk mempelajari selengkapnya tentang aturan penamaan telemetri DTDL, lihat Telemetri DTDL>. Anda tidak dapat memulai nama telemetri menggunakan _ karakter .

Jangan membuat jenis telemetri dengan nama berikut. IoT Central menggunakan nama yang dicadangkan ini secara internal. Jika Anda mencoba menggunakan nama-nama ini, IoT Central akan mengabaikan data Anda:

EventEnqueuedUtcTime
EventProcessedUtcTime
PartitionId
EventHub
User
$metadata
$version

Telemetri dalam komponen

Jika telemetri ditentukan dalam komponen, tambahkan properti pesan kustom bernama $.sub dengan nama komponen seperti yang ditentukan dalam model perangkat. Untuk mempelajari lebih lanjut, lihat Tutorial: Koneksi aplikasi perangkat beberapa komponen IoT Plug and Play. Tutorial ini menunjukkan cara menggunakan bahasa pemrograman yang berbeda untuk mengirim telemetri dari komponen.

Penting

Untuk menampilkan telemetri dari komponen yang dihosting di modul IoT Edge dengan benar, gunakan IoT Edge versi 1.2.4 atau yang lebih baru. Jika Anda menggunakan versi yang lebih lama, telemetri dari komponen Anda dalam modul IoT Edge ditampilkan sebagai _unmodeleddata.

Telemetri dalam antarmuka yang diwariskan

Jika telemetri didefinisikan dalam antarmuka yang diwariskan, perangkat Anda akan mengirim telemetri seolah-olah didefinisikan dalam antarmuka akar. Mengingat model perangkat berikut:

[
    {
        "@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"
    }
]

Perangkat mengirim telemetri tegangan meter menggunakan payload berikut. Perangkat tidak menyertakan nama antarmuka dalam payload:

{
    "MeterVoltage": 5.07
}

Jenis primitif

Bagian ini menunjukkan contoh jenis telemetri primitif yang dapat dialirkan perangkat.

Cuplikan berikut dari model perangkat menunjukkan definisi jenis telemetri boolean:

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

Klien perangkat harus mengirim telemetri sebagai JSON yang terlihat seperti contoh berikut:

{ "BooleanTelemetry": true }

Cuplikan berikut dari model perangkat menunjukkan definisi jenis telemetri string:

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

Klien perangkat harus mengirim telemetri sebagai JSON yang terlihat seperti contoh berikut:

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

Cuplikan berikut dari model perangkat menunjukkan definisi jenis telemetri integer:

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

Klien perangkat harus mengirim telemetri sebagai JSON yang terlihat seperti contoh berikut:

{ "IntegerTelemetry": 23 }

Cuplikan berikut dari model perangkat menunjukkan definisi jenis telemetri double:

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

Klien perangkat harus mengirim telemetri sebagai JSON yang terlihat seperti contoh berikut:

{ "DoubleTelemetry": 56.78 }

Cuplikan berikut dari model perangkat menunjukkan definisi jenis telemetri dateTime:

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

Klien perangkat harus mengirim telemetri sebagai JSON yang terlihat seperti contoh berikut - jenis DateTime harus dalam format ISO 8061:

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

Cuplikan berikut dari model perangkat menunjukkan definisi jenis telemetri duration:

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

Klien perangkat harus mengirim telemetri sebagai JSON yang terlihat seperti contoh berikut - durasi harus dalam format ISO 8601:

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

Jenis kompleks

Bagian ini menunjukkan contoh jenis telemetri kompleks yang dapat dialirkan perangkat.

Cuplikan berikut dari model perangkat menunjukkan definisi jenis telemetri 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"
      }
    ]
  }
}

Klien perangkat harus mengirim telemetri sebagai JSON yang terlihat seperti contoh berikut. Nilai yang mungkin adalah 0, 1, dan 2 yang ditampilkan di IoT Central sebagai Item1, Item2, dan Item3:

{ "EnumTelemetry": 1 }

Cuplikan berikut dari model perangkat menunjukkan definisi jenis telemetri Object. Objek ini memiliki tiga bidang dengan jenis dateTime, integer, dan 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"
            }
          ]
        }
      }
    ]
  }
}

Klien perangkat harus mengirim telemetri sebagai JSON yang terlihat seperti contoh berikut. Jenis DateTime sesuai dengan ISO 8061. Nilai yang mungkin untuk Property3 adalah 0, 1, dan tampilan di IoT Central sebagai Item1, Item2, dan Item3:

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

Cuplikan berikut dari model perangkat menunjukkan definisi jenis telemetri vector:

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

Klien perangkat harus mengirim telemetri sebagai JSON yang terlihat seperti contoh berikut:

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

Cuplikan berikut dari model perangkat menunjukkan definisi jenis telemetri geopoint:

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

Catatan

Jenis skema geopoint adalah bagian dari ekstensi IoT Central ke DTDL. IoT Central saat ini mendukung jenis skema geopoint dan tipe semantik lokasi untuk kompatibilitas mundur.

Klien perangkat harus mengirim telemetri sebagai JSON yang terlihat seperti contoh berikut. IoT Central menampilkan nilai sebagai pin pada peta:

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

Jenis acara dan status

Bagian ini menunjukkan contoh peristiwa telemetri dan menyatakan bahwa perangkat dikirim ke aplikasi IoT Central.

Catatan

Jenis skema peristiwa dan status adalah bagian dari ekstensi IoT Central ke DTDL.

Cuplikan berikut dari model perangkat menunjukkan definisi jenis peristiwa integer:

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

Klien perangkat harus mengirim data peristiwa sebagai JSON yang terlihat seperti contoh berikut:

{ "IntegerEvent": 74 }

Cuplikan berikut dari model perangkat menunjukkan definisi jenis status 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"
      }
    ]
  }
}

Klien perangkat harus mengirim status sebagai JSON yang terlihat seperti contoh berikut. Nilai status bilangan bulat yang mungkin adalah 1, 2, atau 3:

{ "IntegerState": 2 }

Properti

Untuk mempelajari selengkapnya tentang aturan penamaan properti DTDL, lihat Properti DTDL>. Anda tidak dapat memulai nama properti menggunakan _ karakter .

Properti dalam komponen

Jika properti ditentukan dalam komponen, bungkus properti dalam nama komponen. Contoh berikut mengatur maxTempSinceLastReboot dalam komponen thermostat2. Penanda __t menunjukkan bahwa bagian ini mendefinisikan komponen:

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

Untuk mempelajari selengkapnya, lihat Tutorial: Membuat dan menghubungkan aplikasi klien ke aplikasi Azure IoT Central Anda.

Jenis primitif

Bagian ini memperlihatkan contoh jenis properti primitif yang dikirim perangkat ke layanan.

Cuplikan berikut dari model perangkat menunjukkan definisi jenis properti boolean:

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

Klien perangkat harus mengirim payload JSON yang terlihat seperti contoh berikut sebagai properti yang dilaporkan dalam perangkat kembar:

{ "BooleanProperty": false }

Cuplikan berikut dari model perangkat menunjukkan definisi jenis properti long:

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

Klien perangkat harus mengirim payload JSON yang terlihat seperti contoh berikut sebagai properti yang dilaporkan dalam perangkat kembar:

{ "LongProperty": 439 }

Cuplikan berikut dari model perangkat menunjukkan definisi jenis properti date:

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

Klien perangkat harus mengirim payload JSON yang terlihat seperti contoh berikut sebagai properti yang dilaporkan dalam perangkat kembar. Jenis Date harus sesuai dengan ISO 8061:

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

Cuplikan berikut dari model perangkat menunjukkan definisi jenis properti duration:

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

Klien perangkat harus mengirim payload JSON yang terlihat seperti contoh berikut sebagai properti yang dilaporkan dalam perangkat kembar - durasi harus sesuai dengan Durasi ISO 8601:

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

Cuplikan berikut dari model perangkat menunjukkan definisi jenis properti float:

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

Klien perangkat harus mengirim payload JSON yang terlihat seperti contoh berikut sebagai properti yang dilaporkan dalam perangkat kembar:

{ "FloatProperty": 1.9 }

Cuplikan berikut dari model perangkat menunjukkan definisi jenis properti string:

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

Klien perangkat harus mengirim payload JSON yang terlihat seperti contoh berikut sebagai properti yang dilaporkan dalam perangkat kembar:

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

Jenis kompleks

Bagian ini memperlihatkan contoh jenis properti kompleks yang dikirim perangkat ke layanan.

Cuplikan berikut dari model perangkat menunjukkan definisi jenis properti 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"
      }
    ]
  }
}

Klien perangkat harus mengirim payload JSON yang terlihat seperti contoh berikut sebagai properti yang dilaporkan dalam perangkat kembar. Nilai yang mungkin adalah 0, 1, dan yang ditampilkan di IoT Central sebagai Item1, Item2, dan Item3:

{ "EnumProperty": 1 }

Cuplikan berikut dari model perangkat menunjukkan definisi jenis properti Object. Objek ini memiliki dua bidang dengan jenis string dan 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"
      }
    ]
  }
}

Klien perangkat harus mengirim payload JSON yang terlihat seperti contoh berikut sebagai properti yang dilaporkan dalam perangkat kembar:

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

Cuplikan berikut dari model perangkat menunjukkan definisi jenis properti vector:

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

Klien perangkat harus mengirim payload JSON yang terlihat seperti contoh berikut sebagai properti yang dilaporkan dalam perangkat kembar:

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

Cuplikan berikut dari model perangkat menunjukkan definisi jenis properti geopoint:

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

Catatan

Jenis skema geopoint adalah bagian dari ekstensi IoT Central ke DTDL. IoT Central saat ini mendukung jenis skema geopoint dan tipe semantik lokasi untuk kompatibilitas mundur.

Klien perangkat harus mengirim payload JSON yang terlihat seperti contoh berikut sebagai properti yang dilaporkan dalam perangkat kembar:

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

Jenis properti bisa-tulis

Bagian ini memperlihatkan contoh jenis properti bisa-tulis yang diterima perangkat dari layanan.

Jika properti bisa-tulis didefinisikan dalam komponen, pesan properti yang diinginkan menyertakan nama komponen. Contoh berikut menunjukkan pesan yang meminta perangkat untuk memperbarui targetTemperature dalam komponen thermostat2. Penanda __t menunjukkan bahwa bagian ini mendefinisikan komponen:

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

Untuk mempelajari lebih lanjut, lihat Koneksi beberapa aplikasi perangkat komponen IoT Plug and Play.

Perangkat atau modul harus mengonfirmasi bahwa telah menerima properti dengan mengirimkan properti yang dilaporkan. Properti yang dilaporkan harus menyertakan:

value - nilai sebenarnya properti (biasanya nilai yang diterima, tetapi perangkat mungkin memutuskan untuk melaporkan nilai yang berbeda).
ac - kode konfirmasi yang menggunakan kode status HTTP.
av - versi konfirmasi yang merujuk ke $version dari properti yang diinginkan. Anda dapat menemukan nilai ini dalam payload JSON properti yang diinginkan.
ad – deskripsi konfirmasi opsional.

Untuk mempelajari selengkapnya tentang bidang ini, lihat Respons pengakuan konvensi > IoT Plug and Play

Cuplikan berikut dari model perangkat menunjukkan definisi jenis properti bisa-tulis string:

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

Perangkat menerima payload berikut dari layanan:

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

Perangkat harus mengirim payload JSON berikut ke layanan setelah memproses pembaruan. Pesan ini mencakup nomor versi pembaruan asli yang diterima dari layanan.

Tip

Jika layanan adalah IoT Central, layanan menandai properti sebagai disinkronkan di UI saat menerima pesan ini:

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

Cuplikan berikut dari model perangkat menunjukkan definisi jenis properti bisa-tulis 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"
      }
    ]
  }
}

Perangkat menerima payload berikut dari layanan:

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

Perangkat harus mengirim payload JSON berikut ke layanan setelah memproses pembaruan. Pesan ini mencakup nomor versi pembaruan asli yang diterima dari layanan.

Tip

Jika layanan adalah IoT Central, layanan menandai properti sebagai disinkronkan di UI saat menerima pesan ini:

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

Perintah

Untuk mempelajari selengkapnya tentang aturan penamaan perintah DTDL, lihat Perintah DTDL>. Anda tidak dapat memulai nama perintah menggunakan _ karakter .

Jika perintah didefinisikan dalam komponen, nama perintah yang diterima perangkat menyertakan nama komponen. Misalnya, jika perintah disebut getMaxMinReport dan komponen disebut thermostat2, perangkat menerima permintaan untuk menjalankan perintah yang disebut thermostat2*getMaxMinReport.

Cuplikan berikut dari model perangkat menunjukkan definisi perintah yang tidak memiliki parameter dan yang tidak mengharapkan perangkat mengembalikan apa pun:

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

Perangkat menerima payload kosong dalam permintaan dan harus mengembalikan payload kosong dalam respons dengan kode respons HTTP 200 untuk menunjukkan keberhasilan.

Cuplikan berikut dari model perangkat menunjukkan definisi perintah yang memiliki parameter bilangan bulat dan yang mengharapkan perangkat mengembalikan nilai bilangan bulat:

{
  "@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"
}

Perangkat menerima nilai bilangan bulat sebagai payload permintaan. Perangkat harus mengembalikan nilai bilangan bulat sebagai payload respons dengan kode respons HTTP 200 untuk menunjukkan keberhasilan.

Cuplikan berikut dari model perangkat menunjukkan definisi perintah yang memiliki parameter objek dan yang mengharapkan perangkat mengembalikan objek. Dalam contoh ini, kedua objek memiliki bidang bilangan bulat dan string:

{
  "@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"
}

Cuplikan berikut menunjukkan contoh payload permintaan yang dikirim ke perangkat:

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

Cuplikan berikut menunjukkan contoh payload respons yang dikirim dari perangkat. Gunakan kode respons HTTP 200 untuk menunjukkan keberhasilan:

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

Tip

IoT Central memiliki konvensi sendiri untuk menerapkan perintah Jangka Panjang dan perintah Offline.

Langkah berikutnya

Sekarang setelah Anda mempelajari tentang payload perangkat, langkah selanjutnya yang disarankan adalah membaca panduan Pengembang perangkat.

Payload telemetri, properti, dan perintah

Menampilkan data mentah

telemetri

Telemetri dalam komponen

Telemetri dalam antarmuka yang diwariskan

Jenis primitif

Jenis kompleks

Jenis acara dan status

Properti

Properti dalam komponen

Jenis primitif

Jenis kompleks

Jenis properti bisa-tulis

Perintah

Langkah berikutnya

Sumber Daya Tambahan: