מדריך למערכות אבטחה לבית חכם

action.devices.types.SECURITYSYSTEM – אפשר להפעיל ולהשבית מערכות אבטחה. אפשר להפעיל אותם במספר רמות אבטחה (לדוגמה, 'בית' ו'חוץ'), והם יכולים לדווח על מידע לגבי חיישנים מסוימים, כמו חיישן שמזהה תנועה או חלון פתוח.

הסוג הזה מציין שהמכשיר מקבל את הסמל של מערכת האבטחה וגם כמה שמות נרדפים וכינויים קשורים.

יכולות המכשיר

פרטי ההטמעה, כמו המאפיינים והמצבים שהשירות צריך לתמוך בהם, והאופן שבו יוצרים תגובות EXECUTE ו-QUERY, מפורטים במסמכי העזרה של המאפיינים המתאימים.

מאפיינים נדרשים

המאפיינים והפקודות האלה נדרשים, אם הם רלוונטיים למכשיר שלכם. אם המכשיר לא תומך במאפיינים האלה, מזינים את קוד השגיאה functionNotSupported בתגובה של QUERY או EXECUTE. מידע נוסף זמין במאמר שגיאות וחריגות.

מומלץ להשתמש במאפיינים האלה אם הם רלוונטיים למכשיר שלכם. עם זאת, אתם יכולים לשלב בין כל המאפיינים הזמינים כדי להתאים את התכונות האלה לפונקציונליות הקיימת של המוצר.

דרישות איכות

  • זמן אחזור: חייב להיות קטן מ-2000ms או שווה לו.
  • אמינות: הערך חייב להיות שווה ל-97% או גדול ממנו.

דוגמה למכשיר: מערכת אבטחה פשוטה

בקטע הזה מפורטות דוגמאות של עומסי נתונים של כוונה שמייצגים 'מערכת אבטחה' נפוצה, על סמך סוג המכשיר והמאפיינים שלמעלה. אם מוסיפים או מסירים מאפיינים בהטמעה, צריך לשנות את התשובות בהתאם כדי לשקף את השינויים האלה.

דוגמה לתגובת 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"
        }
      }
    ]
  }
}

שגיאות במכשיר

הרשימה המלאה של השגיאות והחריגות

דיווח על חריגות בהפעלה

כשמנסים להפעיל או להשבית את המערכת, אפשר לספק הקשר נוסף באמצעות קודי חריגות שמדווחים באמצעות המאפיין StatusReport. אפשר לדווח על חריגים כחסומים או כלא חסומים.

  • החרגות לא חסימות שמדווחות עם סטטוס 'הצלחה' מצביעות על כך שההחרגה לא מנעה את ההפעלה או השבתה.
  • חסימת חריגות שמדווחות עם הסטטוס 'חריגות' מצביעות על כך שההפעלה או ההשבתה הופסקו בגלל החריגות האלה.

קודי החריגה שמשויכים בדרך כלל למערכות אבטחה הם:

  • 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"
            }
          }]
        }]
      }
    }]
  }
תשובה 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 Assistant הדלת הקדמית פתוחה. האם ברצונך להפעיל את מערכת האבטחה?
משתמש כן.
Google Assistant בסדר, דריכת מערכת האבטחה.

בסיבוב הראשון, צריך להגיב עם אתגר 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 Assistant מה קוד האימות שלך?
משתמש 1234.
Google Assistant נראה שהחלון הקדמי והחלון האחורי פתוחים. להמשיך להפעיל את מערכת האבטחה למצב 'אין מענה'?
משתמש כן.
Google Assistant בסדר, המערכת מופעלת למצב 'אין מענה'

בסיבוב הראשון, צריך להגיב עם אתגר 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 challenge עם מידע נוסף, כולל רמת הזרוע של היעד ודוח הסטטוס הנוכחי עם חריגות החסימה.

בקשה 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, ולא את מספר ה-PIN שסיפקתם בשלב הראשון.

בקשה 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
        }
      }
    ]
  }
}