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

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

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

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

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

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

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

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

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

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

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

בקשה
{
  "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. אפשר לדווח על חריגים כחסימה או כאי-חסימה.

  • חריגים שלא חוסמים שמדווחים עם הסטטוס 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"
              }
            ]
          }
        }
      ]
    }
  }

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

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

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

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

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

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

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

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