CheckForUpdates

Interfejs /osc/checkForUpdates API identyfikuje aktualizacje stanu, porównując ostatnią znaną wartość stateFingerprint klienta z bieżącym fingerprint kamery.

Dane wejściowe

Nazwa Typ Opis
stateFingerprint Ciąg znaków Odcisk cyfrowy stanu aparatu użyty podczas ostatniej wywołania /osc/state lub /osc/checkForUpdates przez klienta.
waitTimeout Liczba całkowita (opcjonalnie) Liczba sekund oczekiwania na zmianę stanu kamery, zanim odpowiedź zostanie zwrócona. Gdy kod waitTimeout straci ważność, aparat powinien zwrócić odpowiedź, nawet jeśli odcisk palca się nie zmienił. Jeśli przed wygaśnięciem zdarzenia waitTimeout zostanie wykryta zmiana stanu lub jeśli waitTimeout zostanie pominięty, kamera powinna natychmiast zwrócić odpowiedź.Uwaga: kamera może zwrócić odpowiedź przed wygaśnięciem rejestracji w usłudze waitTimeout, nawet jeśli odcisk palca nie uległ zmianie, ale zalecamy zaczekać, aż wygaśnie waitTimeout.

Uwagi dotyczące implementacji aparatu:

  • Po otrzymaniu tego wywołania kamera porównuje odcisk cyfrowy swojego aktualnego stanu z odebranym parametrem stateFingerprint. Jeśli odcisk palca się zmieni, aparat musi natychmiast zwrócić nowy odcisk.

Wyniki

Nazwa Typ Opis
stateFingerprint Ciąg znaków Nowy odcisk cyfrowy stanu kamery (taki sam jak w interfejsie API /osc/state).
throttleTimeout Liczba całkowita Zalecany czas oczekiwania klienta przed następnym połączeniem checkForUpdates. Klienci mogą wysyłać żądania przed wygaśnięciem usługi throttleTimeout, a kamery powinny zezwolić na takie wczesne żądania, jeśli to możliwe.

Uwagi dotyczące implementacji po stronie klienta:

  • Po otrzymaniu odpowiedzi klient powinien porównać otrzymaną wiadomość stateFingerprint z kopią. Jeśli dane się nie zgadzają, klient powinien zażądać bieżącego stanu kamery za pomocą interfejsu API _/osc/state.
  • Inteligentne klienty będą ograniczać liczbę żądań niezależnie od odpowiedzi kamery. Jeśli na przykład kamera zwróci niestandardową odpowiedź (natychmiast przy niskiej wartości bez zmian lub z wartością 0 throttleTimeout), klient powinien ustawić własny throttleTimeout przed żądaniem przesłania kolejnego checkForUpdates do kamery.

Uwagi dotyczące implementacji aparatu:

  • Podczas reagowania na działanie funkcji checkForUpdates kamera powinna określić rozsądny throttleTimeout. Jeśli kamera obsługuje długotrwałą logikę żądań (odpowiada dopiero po waitTimeout, o ile stan się nie zmieni), można zwrócić wartość throttleTimeout jako 0. W takim przypadku klienci mogą natychmiast poprosić o aktualizacje.
  • Jeśli kamera obsługuje tylko szybkie odpowiedzi (nie jest to zalecane), powinna zwracać rozsądną wartość throttleTimeout, aby uniknąć ciągłego ruchu związanego z żądaniami i odpowiedziami przez klienta. Na przykład rozsądna wartość throttleTimeout wynosi 60 sekund, ponieważ pozwala to na 1 żądanie klienta na minutę.
  • Sprawdzoną metodą jest zwrócenie wartości throttleTimeout odpowiedniej do możliwości danej kamery. Jeśli w związku z problemem z serwerem serwer nie może określić odpowiedniego elementu throttleTimeout, kamera powinna w odpowiedzi przesłać kod stanu 5XX i treści JSON zawierające kod błędu serverError.

Błąd

Kod błędu Opis
missingParameter Nie określono parametru stateFingerprint.
invalidParameterName Co najmniej 1 nazwa parametru wejściowego nie została rozpoznana.
invalidParameterValue Nazwy parametrów są rozpoznawane, ale co najmniej jedna wartość jest nieprawidłowa. np. waitTimeout jest poza zakresem lub jego typ jest nieprawidłowy.
serverError Serwer nie mógł określić odpowiedniej wartości throttleTimeout dla odpowiedzi. Problem z serwerem będzie identyfikowany na podstawie wartości 5XX zwróconej w odpowiedzi. Producenci kamer powinni udostępnić tabelę z kodami 5XX i odpowiednimi stanami serwera, które mogą powodować ten błąd.

Przykład
Wyślij prośbę 
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
}
Odpowiedź 
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
}
Wyślij prośbę 
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
}
Odpowiedź 
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."
    }
}