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

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

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

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

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

התכונות הנדרשות

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

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

דרישות איכות

  • זמן אחזור: חייב להיות קטן מ-2,000 אלפיות שנייה או שווה לו.
  • אמינות: חייבת להיות יותר מ-97% או שווה לו.

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

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

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

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": "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 תמשיך לטפל בבקשה שתכיל את מספר ה-PIN שסופק. כדי לתמוך בפנייה השנייה, עליך להשיב באמצעות אתגר 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
        }
      }
    ]
  }
}