מדריך למערכת אבטחה לבית חכם
action.devices.types.SECURITYSYSTEM
– אפשר להפעיל ולנטרל את מערכות האבטחה. אפשר להפעיל אותם בכמה רמות אבטחה (לדוגמה, בבית ובחוץ), והם יכולים לדווח על מידע לגבי חיישנים מסוימים, כמו חיישן שמזהה תנועה או חלון פתוח.
הסוג הזה מציין שהמכשיר מקבל את הסמל של מערכת האבטחה וכמה מילים נרדפות וכינויים קשורים.
יכולות המכשיר
במסמכי התיעוד המתאימים תוכלו למצוא פרטים על ההטמעה, כמו מאפיינים ומצבים שבהם השירות צריך לתמוך ואיך ליצור תגובות EXECUTE ו-QUERY.
התכונות הנדרשות
התכונות והפקודות האלה נדרשות, אם זה רלוונטי למכשיר שלכם. אם המכשיר שלכם לא תומך בתכונות האלה, צריך להזין את קוד השגיאה functionNotSupported
בתשובה של QUERY או EXECUTE. מידע נוסף זמין במאמר שגיאות וחריגים.
תכונות מומלצות
מומלץ להשתמש בתכונות האלה, אם הן רלוונטיות למכשיר שלכם. עם זאת, אתם יכולים לשלב בין כל התכונות הזמינות כדי להתאים בצורה הטובה ביותר את הפונקציונליות הקיימת של המוצר.
דרישות איכות
- זמן אחזור: חייב להיות קטן מ-2,000 אלפיות שנייה או שווה לו.
- אמינות: חייבת להיות יותר מ-97% או שווה לו.
מכשיר לדוגמה: מערכת אבטחה פשוטה
הקטע הזה כולל דוגמאות למטענים ייעודיים (payloads) של 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" } ] } } } }
פקודות 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" } } ] } }
ERRORS במכשיר
כאן מפורטת הרשימה המלאה של שגיאות וחריגים.דיווח על חריגים בכלי נשק
כשמנסים להפעיל דלוק או להשבית את המערכת, אפשר לקבל הקשר נוסף באמצעות קודי חריגים שמדווחים באמצעות התכונה StatusReport. אפשר לדווח על חריגות כחריגות או כלא חוסמות.
- החרגות ללא חסימה שדווחו בסטטוס 'הצלחה' מצביעות על כך שהחריג לא מנע את ההפעלה או הכיבוי של הנשק.
- חריגות חסימה שדווחו עם הסטטוס 'EXCEPTIONS' מראות שהחילוף או הפירוק הופסק עקב החריגים האלה.
קודי חריגים שבדרך כלל משויכים למערכות אבטחה:
doorOpen
: יש דלת פתוחה.windowOpen
: חלון פתוח.isOpen
: חיישן מזהה שמשהו פתוח (אבל לא יודע אם זו דלת או חלון).
דוגמה: חריג שלא מוגדר לחסימה
בדוגמה הזו מוצג חריג שלא מוגדר לחסימה, שבו מערכת האבטחה נערכת למרות שדווח שחלון פתוח.
משתמש | מגדירים את מערכת האבטחה לאבטחה גבוהה. |
Google Assistant | בסדר, החלון הקדמי פתוח. התאמה של מערכת האבטחה לאבטחה גבוהה. |
{
"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 Assistant | אירעה שגיאה בשליטה על מערכת האבטחה. החלון הקדמי פתוח. |
{
"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"
}
]
}
}
]
}
}
הפעלה באמצעות אימות דו-שלבי
אם תהליך הזריעה דורש מהמשתמשים להזין קוד אימות דרך תיבת דו-שיח של אימות דו-שלבי, עליכם לאשר אם הם רוצים להמשיך להפעיל את המערכת כשיש חריגים פעילים (לדוגמה, כשחלון או דלת פתוחים).
בתרחיש הזה ייתכן שיהיה צורך גם להזין קוד אימות וגם להזין ביטוי סיסמה, ואחריו אישור.
דוגמה: אתגר אישור
בדוגמה הזו מוצג משתמש שמנסה להפעיל את מערכת האבטחה, אבל זוהתה דלת קדמית פתוחה. המשתמש מאשר שצריך להפעיל את מערכת האבטחה למרות שהדלת הקדמית פתוחה.
משתמש | לדרוך את מערכת האבטחה. |
Google Assistant | הדלת הקדמית פתוחה. בחרת להפעיל את מערכת האבטחה. להמשיך? |
משתמש | כן. |
Google Assistant | בסדר, המערכת מפעילה את מערכת האבטחה. |
בפנייה הראשונה, צריך להשיב באמצעות אתגר 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 Assistant | מהו קוד האימות שלך? |
משתמש | 1234. |
Google Assistant | נראה שהחלון הקדמי והחלון האחורי פתוחים. האם אתה בטוח שברצונך להמשיך את מערכת האבטחה למצב 'לא בבית'? |
משתמש | כן. |
Google Assistant | בסדר, המערכת מאחזרת את מערכת האבטחה למצב 'לא בבית' |
בפנייה הראשונה, צריך להשיב עם אתגר 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 תמשיך לטפל בבקשה שתכיל את מספר ה-PIN שסופק. כדי לתמוך
בפנייה השנייה, צריך להשיב באמצעות אתגר 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 } } ] } }