دليل نظام أمان المنزل المزوّد بأجهزة ذكية
action.devices.types.SECURITYSYSTEM
- يمكن تفعيل أنظمة الأمان وإيقافها. يمكن تفعيل جهاز الإنذار على مستويات أمان متعدّدة (مثلاً في المنزل والخارج)، ويمكنه الإبلاغ عن معلومات حول أجهزة استشعار معيّنة، مثل جهاز استشعار يرصد حركة أو نافذة مفتوحة.
يشير هذا النوع إلى أنّ الجهاز يعرض رمز "نظام الأمان" وبعض المرادفات والأسماء المستعارة ذات الصلة.
إمكانات الجهاز
يمكنك الرجوع إلى وثائق السمات المقابلة لتفاصيل التنفيذ، مثل السمات والحالات التي يجب أن تدعمها خدمتك، وكيفية إنشاء استجابات EXECUTE وQUERY.
السمات المطلوبة
هذه السمات والأوامر مطلوبة، إذا كانت منطبقة على جهازك. إذا كان جهازك لا يتيح استخدام هذه السمات، أدخِل رمز الخطأ
functionNotSupported
في الاستجابة QUERY أو EXECUTE. يمكنك الاطّلاع على الأخطاء والاستثناءات لمعرفة مزيد من المعلومات.
السمات المقترَحة
يُنصح باستخدام هذه السمات إذا كانت مناسبة لجهازك. ومع ذلك، لك مطلق الحرية في مزج جميع السمات المتاحة ومطابقتها لمطابقة وظائف منتجك الحالية بأفضل شكل.
متطلبات الجودة
- وقت الاستجابة: يجب أن يكون أقل من 2000 ملي ثانية أو يساويه.
- الموثوقية: يجب أن تزيد عن 97% أو تساويها.
مثال على الجهاز: نظام أمان بسيط
يحتوي هذا القسم على أمثلة على حمولات النية التي تمثّل "نظام أمان" شائعًا استنادًا إلى نوع الجهاز والسمات الواردة أعلاه. في حال إضافة سمات أو إزالتها في عملية التنفيذ، عدِّل إجاباتك وفقًا لذلك لتعكس هذه التغييرات.
نموذج استجابة المزامنة
{ "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" } ] } } } }
نموذج أوامر EXECUTE
مسل ذراع
للاطّلاع على تفاصيل إضافية عن معلَمات الأوامر، يمكنك الاطّلاع على مرجع
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" } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "online": true, "isArmed": false, "currentArmLevel": "L2", "currentStatusReport": [ { "blocking": true, "priority": 0, "statusCode": "windowOpen", "deviceTarget": "sensor_id1" } ] } } ] } }
تفعيل ميزة "المصادقة الثنائية"
إذا كانت عملية التفعيل تتطلّب من المستخدمين إدخال رقم التعريف الشخصي من خلال مربّع حوار المصادقة الثنائية، عليك الموافقة على ما إذا كانوا يريدون مواصلة تفعيل النظام عند وجود استثناءات نشطة (على سبيل المثال، عندما يكون هناك نافذة أو باب مفتوح).
قد يتطلب هذا السيناريو كلاً من إدخال رقم التعريف الشخصي أو عبارة المرور، متبوعًا بإقرار.
مثال: تحدّي الإقرار
يعرض هذا المثال مستخدمًا يحاول تفعيل نظام الأمان، ولكن تم رصد فتح باب أمامي. يقرّ المستخدم بأنّه يجب تفعيل نظام الأمان على الرغم من فتح الباب الأمامي.
المستخدم | تَفْعِيلْ جِهَازِ الْإِنْذَارْ فِي نِظَامِ الْأَمَانْ. |
مساعد Google | الْبَابُ الْأَمَامِي مَفْتُوحْ. هَلْ مَطْلُوبْ فِعْلًا تَفْعِيلْ جِهَازِ الْإِنْذَارْ فِي نِظَامِ الْأَمَانْ؟ |
المستخدم | نعم. |
مساعد Google | حسنًا، جارٍ تفعيل نظام الأمان. |
في الدور الأول، يجب أن ترد باستخدام تحدي ackNeeded
.
{ "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": [ "123" ], "status": "ERROR", "errorCode": "challengeNeeded", "challengeNeeded": { "type": "ackNeeded" }, "states": { "isArmed": true, "currentArmLevel": "L2", "currentStatusReport": [ { "blocking": false, "priority": 0, "statusCode": "doorOpen", "deviceTarget": "456" } ] } } ] } }
سيتضمّن الطلب اللاحق الذي تم إرساله إليك من Google نتيجة ack
.
{ "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
عادي.
{ "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
مع توفير معلومات إضافية، بما في ذلك مستوى المجموعة المستهدفة وتقرير الحالة الحالي مع استثناءات الحظر.
{ "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
فقط،
وليس رقم التعريف الشخصي الذي تم تقديمه في المرة الأولى.
{ "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 } } ] } }