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

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

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

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

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

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

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

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

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

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

דוגמה לתגובת סנכרון

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

דוגמה לתשובה של שאילתה

בקשה
{
  "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": "PENDING",
        "states": {
          "online": true,
          "isArmed": true,
          "currentArmLevel": "away_key"
        }
      }
    ]
  }
}

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

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

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

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

  • חריגים שלא חוסמים שמדווחים עם הסטטוס SUCCESS מציינים ש החריג לא מנע את הפעלת האזעקה או את השבתתה.
  • חריגים לחסימה שמדווחים עם הסטטוס 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"
            }
          }]
        }]
      }
    }]
  }
תשובה 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"
              }
            ]
          }
        }
      ]
    }
  }

הגנה באמצעות אימות דו-שלבי

אם תהליך הפעלת האזעקה דורש מהמשתמשים להזין קוד אימות באמצעות דו-שלבי (2FA), עליכם לאפשר להם להמשיך בהפעלת האזעקה גם אם יש חריגים פעילים (למשל, אם חלון או דלת פתוחים).

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

דוגמה: אישור אתגר

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

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

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

Request 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
        }
      }
    ]
  }
}