action.devices.EXECUTE

يُرسِل هذا الإجراء أوامر لتنفيذها على الأجهزة المنزلية الذكية.

من المفترض أن يعالج موفِّر الخدمة كلّ أمر ويرسله إلى الجهاز المقابل ويعرض الحالة الجديدة في استجابة EXECUTE.

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

لمزيد من التفاصيل، يُرجى الاطّلاع على طلب البحث والتنفيذ.

تنسيق الطلب

الحقول النوع الوصف
requestId String

مطلوبة

رقم تعريف الطلب.
inputs صفيف

مطلوبة

قائمة بالمدخلات التي تتطابق مع طلب النية
[item, ...] العنصر

النوع والحمولة المرتبطة بطلب النية
intent

مطلوبة

(قيمة ثابتة: "action.devices.EXECUTE")

نوع طلب الإجراء
payload العنصر

مطلوبة

حمولة طلب التنفيذ
commands صفيف

مطلوبة

قائمة بأزواج استهداف الجهاز والأمر
[item, ...] العنصر

مجموعة من الأوامر التي سيتم تنفيذها على استهدافات الأجهزة المرفقة.
devices صفيف

مطلوبة

قائمة بالأجهزة المستهدَفة
[item, ...] العنصر

استهداف الجهاز المطلوب تنفيذه.
id String

مطلوبة

رقم تعريف الجهاز، وفقًا لرقم التعريف المقدَّم في SYNC
customData العنصر

إذا تم تقديم عنصر customData غير الشفاف في SYNC، يتم إرساله هنا.
execution صفيف

مطلوبة

قائمة الأوامر المطلوب تنفيذها على الأجهزة المستهدَفة
[item, ...] العنصر

أمر الجهاز
command String

مطلوبة

الأمر المطلوب تنفيذه، عادةً مع معلَمات مصاحبة
params العنصر

يجب أن تكون مطابِقة للمَعلمات لكلّ أمر.
أمثلة

طلب تنفيذ النية

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [
    {
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [
          {
            "devices": [
              {
                "id": "123",
                "customData": {
                  "fooValue": 74,
                  "barValue": true,
                  "bazValue": "sheepdip"
                }
              },
              {
                "id": "456",
                "customData": {
                  "fooValue": 36,
                  "barValue": false,
                  "bazValue": "moarsheep"
                }
              }
            ],
            "execution": [
              {
                "command": "action.devices.commands.OnOff",
                "params": {
                  "on": true
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

تنسيق الردّ

الحقول النوع الوصف
requestId String

مطلوبة

رقم تعريف الطلب المقابل
payload العنصر

مطلوبة

الحمولة في ردّ الطلب
errorCode String

رمز خطأ للمعاملة بأكملها بسبب حالات تعذُّر المصادقة وعدم توفّر نظام المطوّر بالنسبة إلى أخطاء الأجهزة الفردية، استخدِم errorCode ضمن عنصر الجهاز.
debugString String

خطأ استجابة مفصّل لن يتم عرضه أبدًا للمستخدمين، ولكن قد يتم تسجيله أو استخدامه أثناء التطوير.
commands صفيف

يحتوي كل عنصر على جهاز واحد أو أكثر يتضمّن تفاصيل الاستجابة. ملاحظة: قد لا يتم تجميع هذه العناصر بالطريقة نفسها الواردة في الطلب. على سبيل المثال، قد يؤدي الطلب إلى تشغيل 7 مصابيح، مع نجاح 3 مصابيح وتعذُّر تشغيل 4 مصابيح، وبالتالي توفُّر مجموعتَين في الاستجابة.
[item, ...] العنصر

نتيجة تنفيذ الجهاز
ids صفيف

مطلوبة

قائمة بأرقام تعريف الأجهزة المقابلة لهذه الحالة
[item, ...] String

رقم تعريف الجهاز
status String

مطلوبة

نتيجة عملية التنفيذ

القيم المسموح بها هي:

SUCCESS
تأكَّد من نجاح الأمر.
PENDING
تم إدراج الأمر في "قائمة الانتظار"، ولكن من المتوقّع أن ينجح.
OFFLINE
الجهاز المستهدَف غير متصل بالإنترنت أو يتعذّر الوصول إليه.
EXCEPTIONS
تشير هذه الرسالة إلى حدوث مشكلة أو تنبيه مرتبط بطلب. يمكن أن ينجح الأمر أو يتعذّر إتمامه. يتم عادةً ضبط نوع الحالة هذا عندما تريد إرسال معلومات إضافية عن جهاز آخر متصل.
ERROR
تعذّر على الجهاز المستهدَف تنفيذ الأمر.
states العنصر

أن تكون متوافقة مع حالات كل سمة موضّحة في كل مرجع لنموذج السمة هذه هي الحالات بعد التنفيذ، إن توفّرت.
online صحيح/خطأ

يشير إلى ما إذا كان الجهاز متصلاً بالإنترنت (أي يمكن الوصول إليه) أم لا.
errorCode String

توسيع حالة الخطأ إذا لزم الأمر من رموز الأخطاء المُعدّة مسبقًا، والتي سيتم ربطها بالأخطاء المعروضة للمستخدمين
debugString String

خطأ مفصّل على مستوى الأوامر لن يتم عرضه أبدًا للمستخدمين، ولكن قد يتم تسجيله أو استخدامه أثناء التطوير.
أمثلة

استجابة النية EXECUTE

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "on": true,
          "online": true
        }
      },
      {
        "ids": [
          "456"
        ],
        "status": "ERROR",
        "errorCode": "deviceTurnedOff"
      }
    ]
  }
}