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

‫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, ולא את ה-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
        }
      }
    ]
  }
}