راهنمای سیستم امنیتی خانه هوشمند
action.devices.types.SECURITYSYSTEM - سیستم‌های امنیتی می‌توانند فعال و غیرفعال شوند. آنها می‌توانند در سطوح امنیتی چندگانه (مثلاً خانه و بیرون از خانه) فعال شوند و می‌توانند اطلاعات مربوط به حسگرهای خاصی مانند حسگری که حرکت یا پنجره باز را تشخیص می‌دهد، گزارش دهند.
این نوع نشان می‌دهد که دستگاه نماد سیستم امنیتی و برخی مترادف‌ها و نام‌های مستعار مرتبط را دریافت می‌کند.
قابلیت‌های دستگاه
برای جزئیات پیاده‌سازی، مانند ویژگی‌ها و حالت‌هایی که سرویس شما باید پشتیبانی کند، و نحوه ساخت پاسخ‌های EXECUTE و QUERY، به مستندات مربوط به ویژگی‌ها مراجعه کنید.
صفات مورد نیاز
این ویژگی‌ها و دستورات، در صورت وجود برای دستگاه شما، الزامی هستند. اگر دستگاه شما از این ویژگی‌ها پشتیبانی نمی‌کند، کد خطای functionNotSupported را در یک پاسخ QUERY یا EXECUTE وارد کنید. برای اطلاعات بیشتر به بخش خطاها و استثنائات مراجعه کنید.
ویژگی‌های توصیه‌شده
این ویژگی‌ها، در صورت وجود، برای دستگاه شما توصیه می‌شوند. با این حال، شما می‌توانید از بین تمام ویژگی‌های موجود، آنها را با هم ترکیب و تطبیق دهید تا به بهترین شکل با عملکرد محصول فعلی شما مطابقت داشته باشد.
دستگاه نمونه: سیستم امنیتی ساده
این بخش شامل نمونه‌هایی از payloadهای intent است که نشان‌دهنده‌ی یک «سیستم امنیتی» رایج بر اساس نوع دستگاه و ویژگی‌های بالا هستند. اگر ویژگی‌هایی را در پیاده‌سازی خود اضافه یا حذف می‌کنید، پاسخ‌های خود را متناسب با آن تغییرات تغییر دهید.
نمونه پاسخ SYNC
{
"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" } ] } } } }
نمونه دستورات اجرایی
خلع سلاح بازو
برای جزئیات بیشتر در مورد پارامترهای دستور، به مرجع 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 گزارش می‌دهید، زمینه بیشتری فراهم کنید. استثناها را می‌توان به صورت مسدودکننده یا غیرمسدودکننده گزارش کرد.
- استثنائات غیر مسدودکننده که با وضعیت "SUCCESS" گزارش شده‌اند، نشان می‌دهند که این استثنا مانع از مسلح شدن یا خلع سلاح شدن نشده است.
- استثنائات مسدودسازی که با وضعیت "EXCEPTIONS" گزارش شده‌اند، نشان می‌دهند که مسلح‌سازی یا خلع سلاح به دلیل این استثنائات متوقف شده است.
کدهای استثنا که معمولاً با سیستم‌های امنیتی مرتبط هستند عبارتند از:
-
doorOpen: یک در باز است. -
windowOpen: یک پنجره باز است. -
isOpen: یک حسگر تشخیص می‌دهد که چیزی باز است (اما نمی‌داند که آیا در است یا پنجره).
مثال: استثنای غیر مسدودکننده
این مثال یک استثنای غیر مسدودکننده را نشان می‌دهد که در آن سیستم امنیتی فعال است، حتی اگر یک پنجره به عنوان باز گزارش شده باشد.
| کاربر | سیستم امنیتی را روی امنیت بالا تنظیم کنید. |
| دستیار گوگل | باشه، شیشه جلو بازِ. سیستم امنیتی رو به بالاترین سطح امنیتی ارتقا می‌دم. |
{
"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"
}
]
}
}
]
}
}مثال: مسدود کردن استثنا
| کاربر | سیستم امنیتی را روی امنیت بالا تنظیم کنید. |
| دستیار گوگل | خطایی در کنترل سیستم امنیتی رخ داده است. شیشه جلو باز است. |
{
"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": "EXCEPTIONS",
"states": {
"online": true,
"isArmed": false,
"currentArmLevel": "L2",
"currentStatusReport": [
{
"blocking": true,
"priority": 0,
"statusCode": "windowOpen",
"deviceTarget": "sensor_id1"
}
]
}
}
]
}
}مجهز شدن به احراز هویت دو مرحله‌ای
اگر روند مسلح‌سازی شما مستلزم آن است که کاربران از طریق پنجره‌ی احراز هویت دو مرحله‌ای ، پین کد را وارد کنند، باید تأیید کنید که آیا آنها مایلند در صورت وجود استثنائات فعال (مثلاً وقتی پنجره یا در باز است) به مسلح‌سازی سیستم ادامه دهند یا خیر .
این سناریو ممکن است به وارد کردن پین یا عبارت عبور و به دنبال آن یک تأیید نیاز داشته باشد.
مثال: چالش قدردانی
این مثال کاربری را نشان می‌دهد که سعی در فعال کردن سیستم امنیتی دارد، اما درب ورودی باز تشخیص داده می‌شود. کاربر اذعان می‌کند که سیستم امنیتی باید فعال شود، حتی اگر درب ورودی باز باشد.
| کاربر | سیستم امنیتی را مسلح کنید. |
| دستیار گوگل | درِ ورودی باز است. آیا مطمئنید که می‌خواهید سیستم امنیتی را فعال کنید؟ |
| کاربر | بله. |
| دستیار گوگل | باشه، فعال کردن سیستم امنیتی. |
در نوبت اول، باید با یک چالش 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"
}
]
}
}
]
}
} درخواست بعدی گوگل از شما حاوی نتیجه‌ی 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
}
}
]
}
}مثال: چالش پین و تأیید
این مثال کاربری را نشان می‌دهد که سعی دارد سیستم امنیتی را که نیاز به وارد کردن پین کد دارد، فعال کند. سیستم تشخیص می‌دهد که پنجره‌های جلو و عقب باز هستند و از کاربر می‌خواهد که تأیید کند که فعال کردن باید ادامه یابد.
| کاربر | دست به دست دور شو. |
| دستیار گوگل | پین شما چیست؟ |
| کاربر | ۱۲۳۴. |
| دستیار گوگل | به نظر می‌رسد که پنجره جلو و پنجره عقب باز هستند. آیا مطمئن هستید که می‌خواهید سیستم امنیتی را در حالت آماده به کار قرار دهید؟ |
| کاربر | بله. |
| دستیار گوگل | باشه، مسلح کردن سیستم امنیتی برای دور شدن از دسترس |
در نوبت اول، باید با یک چالش استاندارد 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" } }] } }
سپس گوگل با درخواستی حاوی پین ارائه شده، ادامه می‌دهد. برای پشتیبانی از نوبت دوم، باید با یک چالش 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" } }] } }
درخواست بعدی گوگل از شما فقط شامل نتیجه‌ی 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 } } ] } }