بيانات تتبع الاستخدام والخصائص وحمولة الأوامر

مقالة
02/06/2024

بيانات تتبع الاستخدام التي يرسلها جهاز إلى خدمة.
خصائص مزامنة الجهاز مع خدمة.
الأوامر التي تستدعيها الخدمة على جهاز.

تلميح

Azure IoT Central هي خدمة تتبع اصطلاحات أجهزة التوصيل و التشغيل. في IoT Central، يعد نموذج الجهاز جزءا من قالب الجهاز. يدعم IoT Central حاليا DTDL v2 مع ملحق IoT Central. يتوقع تطبيق IoT Central تلقي بيانات JSON المشفرة UTF-8.

توضح هذه المقالة حمولات JSON التي ترسلها الأجهزة وتستقبلها لبيانات تتبع الاستخدام والخصائص والأوامر المحددة في نموذج جهاز DTDL.

لا تصف المقالة كل نوع ممكن من بيانات تتبع الاستخدام والخصائص وحمولة الأوامر، ولكن الأمثلة توضح أنواع المفاتيح.

يظهر كل مثال قصاصة برمجية من طراز الجهاز تحدد النوع ومثال حمولات JSON لتوضيح كيفية تفاعل الجهاز مع خدمة مدركة أجهزة التوصيل و التشغيل مثل IoT Central.

تستخدم القصاصات البرمجية JSON المثال في هذه المقالة Digital Twin Definition Language (DTDL) V2. هناك أيضا بعض ملحقات DTDL التي يستخدمها IoT Central .

للحصول على نموذج التعليمات البرمجية للجهاز الذي يظهر بعض هذه الحمولات قيد الاستخدام، راجع الاتصال نموذج تطبيق جهاز IoT أجهزة التوصيل و التشغيل يعمل على Linux أو Windows إلى IoT Hub أو البرنامج التعليمي إنشاء تطبيق عميل وتوصيله بالبرنامج التعليمي لتطبيق 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"
}

إشعار

نوع مخطط نقطة جغرافية هو جزء من ملحق IoT Central إلى DTDL. يدعم IoT Central حاليا نوع مخطط نقطة جغرافية ونوع دلالي الموقع للتوافق مع الإصدارات السابقة.

يجب أن يرسل عميل الجهاز بيانات تتبع الاستخدام ك JSON التي تبدو مثل المثال التالي. يعرض IoT Central القيمة ك دبوس على الخريطة:

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

أنواع الأحداث والحالات

يعرض هذا القسم أمثلة لأحداث بيانات تتبع الاستخدام ويذكر أن الجهاز يرسل إلى تطبيق IoT Central.

إشعار

أنواع مخطط الحدث والحالة هي جزء من ملحق IoT Central إلى DTDL.

توضح القصاصة البرمجية التالية من نموذج الجهاز تعريف 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 Duration:

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

إشعار

يجب أن يرسل عميل الجهاز حمولة JSON التي تبدو مثل المثال التالي كخاصية تم الإبلاغ عنها في الجهاز المزدوج:

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

أنواع الخصائص القابلة للكتابة

يعرض هذا القسم أمثلة على أنواع الخصائص القابلة للكتابة التي يتلقاها الجهاز من خدمة.

إذا تم تعريف الخاصية القابلة للكتابة في مكون، تتضمن رسالة الخاصية المطلوبة اسم المكون. يوضح المثال التالي الرسالة التي تطلب من الجهاز تحديث في targetTemperaturethermostat2 المكون. تشير العلامة __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، فإنها تشير إلى الخاصية على أنها متزامنة في واجهة المستخدم عندما تتلقى هذه الرسالة:

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

تلميح

إذا كانت الخدمة IoT Central، فإنها تشير إلى الخاصية على أنها متزامنة في واجهة المستخدم عندما تتلقى هذه الرسالة:

{
  "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 الاصطلاحات الخاصة به لتنفيذ الأوامر طويلة الأمد والأوامر غير المتصلة.

الخطوات التالية

الآن بعد أن تعرفت على حمولات الأجهزة، فإن الخطوات التالية المقترحة هي قراءة دليل مطور الجهاز.

بيانات تتبع الاستخدام والخصائص وحمولة الأوامر

عرض البيانات الأولية

قياس تتبع الاستخدام

بيانات تتبع الاستخدام في المكونات

بيانات تتبع الاستخدام في الواجهات الموروثة

أنواع بدائية

الأنواع المعقدة

أنواع الأحداث والحالات

خصائص

الخصائص في المكونات

أنواع بدائية

الأنواع المعقدة

أنواع الخصائص القابلة للكتابة

الأوامر

الخطوات التالية

الموارد الإضافية