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

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"
            }
          }]
        }]
      }
    }]
  }
תשובה שנייה
{
    "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
            }
          }]
        }]
      }
    }]
  }
תשובה שנייה
{
    "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
        }
      }
    ]
  }
}