Информация об устройствах пользователя

Запрашивает информацию о поддерживаемых устройствах пользователя.

Платформа умного дома отправит провайдеру текущий запрос при выполнении условий:

• Аккаунты на Яндексе и на стороне провайдера связаны.
• Пользователь зашел в приложение Дом с Алисой →  → Устройство умного дома и напротив названия производителя нажал кнопку Обновить.

В ответ на такой запрос провайдеру необходимо вернуть список всех поддерживаемых устройств пользователя с описанием доступных умений и свойств. Максимальное количество устройств пользователя — 301.

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

Формат запроса платформы умного дома

Платформа умного дома отправляет запрос на Endpoint URL провайдера (https://example.com).

GET https://example.com/v1.0/user/devices

Заголовки запроса

Формат ответа провайдера

Провайдер должен ответить на полученный от платформы умного дома запрос согласно формату.

{
  "request_id": String,
  "payload": {
      "user_id": String,
      "devices": [
        {
          "id": String,
          "name": String,
          "status_info": {
            "reportable": Boolean
          },
          "description": String,
          "room": String,
          "type": String,
          "custom_data": Object,
          "capabilities": [
            "<capability1>": Object,
            "<capability2>": Object,
            ...
          ],
          "properties": [
            "<property1>": Object,
            "<property2>": Object,
            ...
          ],
          "device_info": {
            "manufacturer": String,
            "model": String,
            "hw_version": String,
            "sw_version": String
          }
        },
        ...
      ]
  }
}

HTTP/1.1 404 Not Found

Поля retrievable и reportableв описании умений и свойств

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

В объекте capabilities

В объекте properties

Поля retrievable и reportable описывают отдельное умение или отдельное свойство. Не путайте их с полем status_info.reportable, которое относится к устройству целиком и отвечает за передачу статуса доступности online и offline. Подробнее см. в разделе Информация об устройствах пользователя.

Пример

В примере описаны свойства светильника с регулировкой цвета.

Запрос

Успешный ответ

Ответ с ошибкой

curl -i -X GET 'https://example.com/v1.0/user/devices' \
-H 'Authorization: Bearer 123qwe456a...' \
-H 'X-Request-Id: ff36a3cc-ec...'

HTTP/1.1 200 OK

{
    "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "user_id": "Misha-01-super-545",
        "devices": [{
                "id": "abc-123",
                "name": "лампa",
                "status_info": {
                  "reportable": true
                },
                "description": "цветная лампа",
                "room": "спальня",
                "type": "devices.types.light",
                "custom_data": {
                  "foo": 1,
                  "bar": "two",
                  "baz": false,
                  "qux": [1, "two", false],
                  "quux": {
                    "quuz": {
                      "corge": []
                    }
                  }
                },
                "capabilities": [{
                        "type": "devices.capabilities.range",
                        "retrievable": true,
                        "parameters": {
                            "instance": "brightness",
                            "unit": "unit.percent",
                            "range": {
                                "min": 0,
                                "max": 100,
                                "precision": 10
                            }
                        }
                    },
                    {
                        "type": "devices.capabilities.on_off"
                    },
                    {
                        "type": "devices.capabilities.color_setting",
                        "parameters": {
                            "color_model": "hsv",
                            "temperature_k": {
                                "min": 2700,
                                "max": 9000,
                                "precision": 1
                            }
                        }
                    }
                ],
                "device_info": {
                    "manufacturer": "Provider2",
                    "model": "hue g11",
                    "hw_version": "1.2",
                    "sw_version": "5.4"
                }
            }

        ]
    }
}

HTTP/1.1 401 Unauthorized

{
  "name": "John",
  "surname": "Smith"
}

"cities": ["Moscow", "Tokyo", "New York"]