دليل نظام أمان المنزل المزوّد بأجهزة ذكية
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
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" } }] }] } }] }
{ "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" } ] } } ] } }
تفعيل ميزة "المصادقة الثنائية"
إذا كان خطوات التفعيل يتطلّب من المستخدمين إدخال رقم التعريف الشخصي من خلال مربّع حوار المصادقة الثنائية، عليك الإقرار بما إذا كانوا يريدون مواصلة تفعيل النظام في حال وجود استثناءات نشطة (على سبيل المثال، عندما يكون هناك نافذة أو باب مفتوحة).
قد يتطلب هذا السيناريو كلاً من إدخال رقم التعريف الشخصي (PIN) أو عبارة المرور، متبوعًا بالإقرار.
مثال: تحدّي الإقرار
يعرض هذا المثال مستخدمًا يحاول تفعيل نظام الأمن، ولكن تم رصد أنّ الباب الأمامي مفتوح. يقرّ المستخدم بأنّه يجب تشغيل نظام الأمن حتى لو كان الباب الأمامي مفتوحًا.
المستخدم | تَفْعِيلْ جِهَازِ الْإِنْذَارْ فِي نِظَامِ الْأَمَانْ. |
مساعد 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 } } ] } }