Проверить обновления

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 с его копией. Если они не совпадают, клиент должен запросить текущее состояние камеры с помощью API _/osc/state .
  • Умные клиенты будут регулировать запросы независимо от реакции камеры. Например, если камера возвращает нестандартный ответ (сразу же, без изменений и с низким или нулевым значением 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."
    }
}