Руководство по системе безопасности «Умный дом»

action.devices.types.SECURITYSYSTEM — Системы безопасности можно ставить на охрану и снимать с охраны. Они могут быть активированы на нескольких уровнях безопасности (например, «дома» и «вне дома») и могут передавать информацию с определённых датчиков, например, с датчика движения или открытого окна.

Этот тип указывает, что устройство получает значок системы безопасности и некоторые связанные с ним синонимы и псевдонимы.

Возможности устройства

Подробную информацию о реализации, например, об атрибутах и ​​состояниях, которые должна поддерживать ваша служба, а также о том, как создавать ответы EXECUTE и QUERY, см. в соответствующей документации по характеристикам.

Требуемые черты

Эти характеристики и команды обязательны, если применимы к вашему устройству. Если ваше устройство не поддерживает эти характеристики, введите код ошибки functionNotSupported в ответе QUERY или EXECUTE. Подробнее см. в разделе «Ошибки и исключения» .

Эти характеристики рекомендуются, если они применимы к вашему устройству. Однако вы можете комбинировать все доступные характеристики, чтобы наилучшим образом соответствовать функционалу вашего устройства.

Пример устройства: простая система безопасности

В этом разделе приведены примеры полезных нагрузок намерений, представляющих собой стандартную «систему безопасности» на основе типа устройства и перечисленных выше характеристик. Если вы добавляете или удаляете характеристики в своей реализации, измените свои ответы соответствующим образом, чтобы отразить эти изменения.

Пример ответа 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"
        }
      }
    ]
  }
}

Пример ответа на ЗАПРОС

Запрос 
{
  "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 . Исключения могут быть блокирующими или неблокирующими.

  • Неблокирующие исключения со статусом «УСПЕХ» указывают на то, что исключение не помешало постановке или снятию с охраны.
  • Исключения блокировки, отмеченные статусом «ИСКЛЮЧЕНИЯ», указывают на то, что постановка или снятие с охраны было остановлено из-за этих исключений.

Коды исключений, которые обычно связаны с системами безопасности, включают:

  • doorOpen : Дверь открыта.
  • windowOpen : Окно открыто.
  • isOpen : Датчик обнаруживает, что что-то открыто (но не знает, дверь это или окно).

Пример: неблокирующее исключение

В этом примере показано неблокирующее исключение, когда система безопасности ставится на охрану, даже если сообщается, что окно открыто.

Пользователь Установите высокий уровень безопасности системы.
Google Ассистент Хорошо, переднее окно открыто. Включаю систему безопасности на высокий уровень безопасности.
Запрос 
{
    "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 Ассистент Произошла ошибка управления системой безопасности. Переднее окно открыто.
Запрос 
{
    "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"
              }
            ]
          }
        }
      ]
    }
  }

Включение двухфакторной аутентификации

Если для постановки системы на охрану пользователю необходимо ввести PIN-код через диалоговое окно двухфакторной аутентификации , необходимо подтвердить, хотят ли они продолжить постановку системы на охрану при наличии активных исключений (например, когда открыто окно или дверь).

В этом сценарии может потребоваться ввод PIN-кода или парольной фразы с последующим подтверждением.

Пример: проверка подтверждения

В этом примере пользователь пытается поставить систему безопасности на охрану, но входная дверь обнаружена открытой. Пользователь подтверждает, что система безопасности должна быть поставлена ​​на охрану, несмотря на то, что входная дверь открыта.

Пользователь Включите систему безопасности.
Google Ассистент Входная дверь открыта. Вы уверены, что хотите включить охранную систему?
Пользователь Да.
Google Ассистент Хорошо, включаю систему безопасности.

В первую очередь следует ответить вызовом 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
          }
        }
      ]
    }
  }

Пример: PIN-код и запрос подтверждения

В этом примере пользователь пытается поставить систему безопасности на охрану, требующую ввода PIN-кода. Система обнаруживает, что переднее и заднее окна открыты, и запрашивает подтверждение на постановку на охрану.

Пользователь Рука в сторону.
Google Ассистент Какой у вас PIN-код?
Пользователь 1234.
Google Ассистент Похоже, переднее и заднее окна открыты. Вы уверены, что хотите продолжить постановку системы безопасности на охрану?
Пользователь Да.
Google Ассистент Хорошо, включаю систему безопасности, чтобы она не зашла.

В первую очередь следует ответить стандартным вызовом 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 , предоставив дополнительную информацию, включая целевой уровень ARM и отчёт о текущем состоянии с блокирующими исключениями.

Запрос 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
        }
      }
    ]
  }
}