CheckForUpdates

API-интерфейс/osc/checkForUpdates определяет состояние обновлений, сравнивая последнюю доступную контрольную сумму stateFingerprint с текущей контрольной суммой fingerprint на клиенте.

Ввод

Имя Тип Описание
stateFingerprint Строка Контрольная сумма состояния камеры при последнем вызове /osc/state или /osc/checkForUpdates.
waitTimeout Целое число (дополнительно) Количество секунд, в течение которого ожидается изменение состояния камеры до возврата ответа. Если ожидание waitTimeout истекло, камера должна вернуть ответ, даже если контрольная сумма не изменилась. Если изменение состояния обнаружено до истечения ожидания waitTimeout, а также если ожидание waitTimeout пропущено, камера должна немедленно вернуть ответ.Примечание. Камера может вернуть ответ до истечения ожидания waitTimeout, даже если контрольная сумма не изменилась, однакорекомендуется дождаться истечения waitTimeout.

Примечания по реализации для камеры:

  • При получении вызова камера сравнивает текущую контрольную сумму с полученным параметром stateFingerprint. Если контрольная сумма изменена, камера должна немедленно вернуть новую контрольную сумму.

Вывод

Имя Тип Описание
stateFingerprint Строка Новая контрольная сумма состояния камеры (совпадает с /osc/state API).
throttleTimeout Целое число Рекомендуемое количество секунд, в течение которого ожидается следующий вызов checkForUpdates. Клиенты могут отправлять запросы до истечения ожидания throttleTimeout, и камера, по возможности, должна разрешать преждевременные запросы.

Примечания по внедрению для клиента:

  • При получении ответа клиент должен сравнить полученную контрольную сумму stateFingerprint с ее копией. Если они не совпадают, клиент должен запросить текущее состояние камеры с помощью _/osc/state API.
  • Смарт-клиенты будут регулировать подачу запросов независимо от ответа камеры. Например, если камера возвращает нестандартный ответ (если нет изменений то сразу, с нулевым или минимальным ожиданием throttleTimeout), клиент должен установить собственное ожидание throttleTimeout до выполнения повторного запроса checkForUpdates с камеры.

Примечания по реализации для камеры:

  • При ответе на checkForUpdates камера должна определить разумное время ожидания throttleTimeout. Если камера поддерживает долгосрочную логику выполнения запросов (ответ только после ожидания waitTimeout, если состояние не изменилось), то можно возвращать для ожидания throttleTimeout значение 0. В этом случае клиенты могут немедленно запрашивать обновления.
  • Если камера поддерживает только быстрые ответы (не рекомендуется), она должна вернуть разумное время throttleTimeout во избежание непрерывного трафика запросов-ответов от клиента. Например, разумным временем throttleTimeout будет 60 секунд, что позволит выполнять один запрос в минуту.
  • Оптимальным решением будет вернуть throttleTimeout, соответствующий возможностям камеры. Если сервер не может определить соответствующее время throttleTimeout из-за возникающей на нем ошибки, камера должна вернуть код состояния 5XX и тело JSON с кодом ошибки serverError.

Ошибка

Код ошибки Описание
missingParameter stateFingerprint не указано.
invalidParameterName Одно или несколько имен параметров не распознано.
invalidParameterValue Имена параметров распознаны, но одно или несколько значений не являются допустимыми; например, ожидание waitTimeout находится вне разрешенного диапазона или имеет неверный тип.
serverError Серверу не удалось определить соответствующее значение ожидания throttleTimeout для ответа. Ошибка сервера будет указана с помощью значения 5XX в ответе. Производители камеры должны предоставить таблицу кодов 5XX и соответствующих им состояний сервера.

Пример
Запрос 
POST /osc/checkForUpdates HTTP/1.1
Host: [camera ip address]:[httpUpdatesPort]
Content-Type: application/json;charset=utf-8
Accept: application/jsonContent-Length: {CONTENT_LENGTH}
X-XSRF-Protected: 1

{
    "stateFingerprint": "12EGA33",
    "waitTimeout": 300
}
Ответ 
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Content-Length: {CONTENT_LENGTH}
X-Content-Type-Options: nosniff

{
    "stateFingerprint": "12EGA86",
    "throttleTimeout": 60
}
Запрос 
POST /osc/checkForUpdates HTTP/1.1
Host: [camera ip address]:[httpUpdatesPort]
Content-Type: application/json;charset=utf-8
Accept: application/jsonContent-Length: {CONTENT_LENGTH}
X-XSRF-Protected: 1

{
    "stateFingerprint": "12EGA33",
    "waitTimeout": 300
}
Ответ 
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=utf-8
Content-Length: {CONTENT_LENGTH}
X-Content-Type-Options: nosniff

{
    "name": "camera.checkForUpdates",
    "state": "error",
    "error": {
        "code": "missingParameter",
        "message": "parameter stateFingerprint is missing."
    }
}