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

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

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

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

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

ה-traits הנדרשות

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

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

דרישות איכות

  • זמן אחזור: חייב להיות קצר מ-2000 אלפיות שנייה או שווה לו.
  • אמינות: צריכה להיות 97% ומעלה.

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

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

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

זרוע

פרטים נוספים על הפרמטרים של הפקודות זמינים בחומר העזר בנושא 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"
          }
        }]
      }]
    }
  }]
}
תשובה 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "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
        }
      }
    ]
  }
}