دليل نظام أمان المنزل الذكي

action.devices.types.SECURITYSYSTEM - يمكن تفعيل جهاز الإنذار وإيقافه في أنظمة الأمان. ويمكن تسليح هذه الأجهزة عند مستويات أمان متعددة (على سبيل المثال، داخل المنزل وخارجه)، كما يمكنها الإبلاغ عن معلومات حول أجهزة استشعار معيّنة، مثل جهاز الاستشعار الذي يرصد حركة أو فتح نافذة.

ويشير هذا النوع إلى أن الجهاز يحصل على رمز نظام الأمان وبعض العناصر ذات الصلة المرادفات والأسماء المستعارة.

إمكانيات الجهاز

راجع وثائق السمات المقابلة تفاصيل التنفيذ، مثل السمات والحالات التي يجب أن تتيحها خدمتك، وكيفية إنشاء ردود EXECUTE وQUERY.

السمات المطلوبة

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

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

متطلبات الجودة

  • وقت الاستجابة: يجب أن يكون أقل من أو يساوي 2000 ملي ثانية.
  • الموثوقية: يجب أن تكون أكبر من أو تساوي 97%.

مثال على جهاز: نظام أمان بسيط

يحتوي هذا القسم على مثال على حمولات بيانات intent التي تمثل "نظام أمان" شائعًا. بناءً على نوع الجهاز والسمات المذكورة أعلاه. إذا قمتَ بإضافة أو إزالة سمات في التنفيذ، عدِّل ردودك وفقًا لهذه التغييرات

نموذج رد المزامنة

طلب
{
  "requestId": "6894439706274654512",
  "inputs": [
    {
      "intent": "action.devices.SYNC"
    }
  ]
}
الرد
{
  "requestId": "6894439706274654512",
  "payload": {
    "agentUserId": "user123",
    "devices": [
      {
        "id": "123",
        "type": "action.devices.types.SECURITYSYSTEM",
        "traits": [
          "action.devices.traits.StatusReport",
          "action.devices.traits.ArmDisarm"
        ],
        "name": {
          "name": "Simple security system"
        },
        "willReportState": true,
        "attributes": {
          "availableArmLevels": {
            "levels": [
              {
                "level_name": "home_key",
                "level_values": [
                  {
                    "level_synonym": [
                      "Home and Guarding",
                      "level 1",
                      "home",
                      "SL1"
                    ],
                    "lang": "en"
                  }
                ]
              },
              {
                "level_name": "away_key",
                "level_values": [
                  {
                    "level_synonym": [
                      "Away and Guarding",
                      "level 2",
                      "away",
                      "SL2"
                    ],
                    "lang": "en"
                  }
                ]
              }
            ],
            "ordered": true
          }
        },
        "deviceInfo": {
          "manufacturer": "smart-home-inc",
          "model": "hs1234",
          "hwVersion": "3.2",
          "swVersion": "11.4"
        }
      }
    ]
  }
}

نموذج رد QUERY

طلب
{
  "requestId": "6894439706274654514",
  "inputs": [
    {
      "intent": "action.devices.QUERY",
      "payload": {
        "devices": [
          {
            "id": "123"
          }
        ]
      }
    }
  ]
}
الرد
{
  "requestId": "6894439706274654514",
  "payload": {
    "devices": {
      "123": {
        "status": "SUCCESS",
        "online": true,
        "isArmed": true,
        "currentArmLevel": "home_key",
        "currentStatusReport": [
          {
            "blocking": false,
            "deviceTarget": "123",
            "priority": 0,
            "statusCode": "lowBattery"
          }
        ]
      }
    }
  }
}

نماذج أوامر التنفيذ

ArmDisarm

للحصول على تفاصيل إضافية حول معاملات الأوامر، عرض action.devices.traits.ArmDisarm المرجع.

طلب
{
  "requestId": "6894439706274654516",
  "inputs": [
    {
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [
          {
            "devices": [
              {
                "id": "123"
              }
            ],
            "execution": [
              {
                "command": "action.devices.commands.ArmDisarm",
                "params": {
                  "arm": true,
                  "armLevel": "away_key"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}
الرد
{
  "requestId": "6894439706274654516",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "online": true,
          "isArmed": true,
          "currentArmLevel": "away_key"
        }
      }
    ]
  }
}

أخطاء الجهاز

اطّلع على القائمة الكاملة الأخطاء والاستثناءات.

الإبلاغ عن استثناءات تفعيل جهاز الإنذار

عند محاولة تشغيل النظام أو إيقافه، يمكنك تقديم معلومات والسياق من خلال رموز الاستثناءات التي تبلغ عنها من خلال سمة StatusReport يمكن الإبلاغ عن الاستثناءات باعتبارها حظرًا أو غير محظور.

  • تم الإبلاغ عن استثناءات عدم الحظر مع الحالة "ناجح". الحالة تشير إلى أن لم يمنع الاستثناء تسليح أو إيقاف الجهاز.
  • استثناءات الحظر التي تم الإبلاغ عنها بعبارة "الاستثناءات" تشير الحالة إلى أن تسليح أو إيقافها بسبب هذه الاستثناءات.

تتضمن رموز الاستثناء المقترنة بشكل شائع بأنظمة الأمان ما يلي:

  • doorOpen: باب مفتوح
  • windowOpen: هناك نافذة مفتوحة.
  • isOpen: يرصد أحد المستشعرات وجود شيء مفتوح (ولكنه لا يعرف ذلك سواء كان بابًا أو نافذة).

مثال: استثناء عدم الحظر

يعرض هذا المثال استثناءً لا يحظر الإعلانات حيث يكون نظام الأمان تشغيل حتى إذا تم الإبلاغ عن أن إحدى النوافذ مفتوحة.

المستخدم ضَبْطْ نِظَامِ الْأَمَانْ عَلَى مُسْتَوَى أَمَانْ عَالِي.
مساعد Google تَمَامْ، النَّافِذَة الْأَمَامِيَّة مفتوحة. يَتِمُّ الْآنْ تَفْعِيلْ جِهَازِ الْإِنْذَارْ فِي نِظَامِ الْأَمَانْ عَلَى مُسْتَوَى أَمَانْ عَالٍ.
.
طلب
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [{
          "devices": [{
            "id": "123"
          }],
          "execution": [{
            "command": "action.devices.commands.ArmDisarm",
            "params": {
              "arm": true,
              "armLevel": "L2"
            }
          }]
        }]
      }
    }]
  }
الرد
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
      "commands": [
        {
          "ids": [
            "123"
          ],
          "status": "SUCCESS",
          "states": {
            "online": true,
            "isArmed": true,
            "currentArmLevel": "L2",
            "currentStatusReport": [
              {
                "blocking": false,
                "priority": 0,
                "statusCode": "windowOpen",
                "deviceTarget": "sensor_id1"
              }
            ]
          }
        }
      ]
    }
  }

مثال: استثناء الحظر

المستخدم ضَبْطْ نِظَامِ الْأَمَانْ عَلَى مُسْتَوَى أَمَانْ عَالِي.
مساعد Google حدث خطأ التَّحَكُّمْ بِنِظَامِ الْأَمَانْ. النافذة الأمامية مفتوحة.
.
طلب
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [{
          "devices": [{
            "id": "123"
          }],
          "execution": [{
            "command": "action.devices.commands.ArmDisarm",
            "params": {
              "arm": true,
              "armLevel": "L2"
            }
          }]
        }]
      }
    }]
  }
الرد 2
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
      "commands": [
        {
          "ids": [
            "123"
          ],
          "status": "EXCEPTIONS",
          "states": {
            "online": true,
            "isArmed": false,
            "currentArmLevel": "L2",
            "currentStatusReport": [
              {
                "blocking": true,
                "priority": 0,
                "statusCode": "windowOpen",
                "deviceTarget": "sensor_id1"
              }
            ]
          }
        }
      ]
    }
  }

تفعيل المصادقة الثنائية

إذا كان تدفق التسليح يتطلب من المستخدمين إدخال رقم تعريف شخصي من خلال المصادقة الثنائية، يجب الإقرار بما إذا كان العميل يريد مواصلة تسليح النظام عندما يكون نشطًا. الاستثناءات (مثلاً، عندما تكون النافذة أو الباب مفتوحًا).

قد يتطلب هذا السيناريو إدخال كلاً من رقم التعريف الشخصي أو عبارة المرور، متبوعًا بإقرار.

مثال: تحدي الإقرار

يوضح هذا المثال مستخدمًا يحاول تفعيل نظام الأمان، لكنه لَقَدْ رَصَدَ الْبَابِ الْأَمَامِي مَفْتُوحًا. يقرّ المستخدم بأنّ الأمان يجب تشغيل نظام التدفئة حتى وإن كان الباب الأمامي مفتوحًا.

المستخدم تَفْعِيلْ جِهَازِ الْإِنْذَارْ فِي نِظَامِ الْأَمَانْ.
مساعد Google الْبَابِ الْأَمَامِي مَفْتُوحْ. هَلْ مَطْلُوبْ فِعْلًا تَفْعِيلْ جِهَازِ الْإِنْذَارْ فِي نِظَامِ الْأَمَانْ؟
المستخدم نعم.
مساعد Google حسنًا، جارٍ تفعيل جهاز الإنذار نظام الأمان.

في الدور الأول، يجب الرد بتحدي ackNeeded.

الطلب 1
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [{
          "devices": [{
            "id": "123"
          }],
          "execution": [{
            "command": "action.devices.commands.ArmDisarm",
            "params": {
              "arm": true
            }
          }]
        }]
      }
    }]
  }
الرد 2
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
      "commands": [
        {
          "ids": [
            "123"
          ],
          "status": "ERROR",
          "errorCode": "challengeNeeded",
          "challengeNeeded": {
            "type": "ackNeeded"
          },
          "states": {
            "isArmed": true,
            "currentArmLevel": "L2",
            "currentStatusReport": [
              {
                "blocking": false,
                "priority": 0,
                "statusCode": "doorOpen",
                "deviceTarget": "456"
              }
            ]
          }
        }
      ]
    }
  }

سيتضمّن الطلب اللاحق من Google الذي يتم إرساله إليك نتيجة "ack".

الطلب 2
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [{
          "devices": [{
            "id": "123"
          }],
          "execution": [{
            "command": "action.devices.commands.ArmDisarm",
            "params": {
              "arm": true
            },
            "challenge": {
              "ack": true
            }
          }]
        }]
      }
    }]
  }
الرد
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
      "commands": [
        {
          "ids": [
            "123"
          ],
          "status": "SUCCESS",
          "states": {
            "isArmed": true
          }
        }
      ]
    }
  }

مثال: رقم التعريف الشخصي وتحدي الإقرار

يوضّح هذا المثال مستخدمًا يحاول تفعيل نظام الأمان الذي يتطلب إدخال رقم التعريف الشخصي. يرصد النظام أن النوافذ الأمامية والخلفية مفتوحة ويطلب من المستخدم الموافقة. يجب أن تستمر عملية التسليح.

المستخدم ذراع إلى الخلف.
مساعد Google ما هو رقم التعريف الشخصي؟
المستخدم 1234.
مساعد Google يبدو أن النافذة الأمامية والخلفية مفتوحة. هل تريد فعلاً المواصلة؟ هل تريد تسليح نظام الأمن بعيدًا عن الجهاز؟
المستخدم نعم.
مساعد Google حسنًا، جارٍ تفعيل جهاز من نظام الأمان إلى خارج المنزل

في الأدوار الأولى، يجب الرد بتحدي pinNeeded عادي.

الطلب 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.ArmDisarm",
          "params": {
            "arm": true
          }
        }]
      }]
    }
  }]
}
الرد
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["456"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

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

الطلب 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [...],
        "execution": [{
          "command": "action.devices.commands.ArmDisarm",
          "params": {
            "arm": true,
            "armLevel": "away"
          },
          "challenge": {
            "pin": "1234"
          }
        }]
      }]
    }
  }]
}
الرد
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["456"],
      "status": "ERROR",
      "states": {
        "targetArmLevel": "away",
        "currentStatusReport": [{
            "blocking": true,
            "priority": 1,
            "deviceTarget": "front_window_id",
            "statusCode": "deviceOpen"
          },
          {
            "blocking": true,
            "priority": 1,
            "deviceTarget": "back_window_id",
            "statusCode": "deviceOpen"
          }
        ]
      },
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}

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

الطلب 3
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [...],
        "execution": [{
          "command": "action.devices.commands.ArmDisarm",
          "params": {
            "arm": true,
            "armLevel": "away"
          },
          "challenge": {
            "ack": true
          }
        }]
      }]
    }
  }]
}
الرد
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "isArmed": true
        }
      }
    ]
  }
}