Руководство по системам безопасности для умного дома

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

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

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

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

Необходимые характеристики

Эти параметры и команды необходимы, если они применимы к вашему устройству. Если ваше устройство не поддерживает эти параметры, введите код ошибки functionNotSupported в ответ на запрос или команду 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-кода. Система обнаруживает, что переднее и заднее окна открыты, и запрашивает у пользователя подтверждение необходимости постановки системы на охрану.

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

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