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

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": "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
        }
      }
    ]
  }
}