CheckForUpdates

Interfejs /osc/checkForUpdates API identyfikuje aktualizacje stanu przez porównanie ostatniego znanego parametru stateFingerprint klienta z bieżącym fingerprint kamery.

Dane wejściowe

Nazwa Typ Opis
stateFingerprint Ciąg znaków Odcisk cyfrowy stanu aparatu używany podczas ostatniego połączenia z /osc/state lub /osc/checkForUpdates przez klienta.
waitTimeout Liczba całkowita (opcjonalnie) Liczba sekund oczekiwania na zmianę stanu kamery przed zwróceniem odpowiedzi. Gdy waitTimeout utraci ważność, aparat powinien zwrócić odpowiedź, nawet jeśli odcisk palca się nie zmienił. Jeśli zmiana stanu zostanie wykryta przed wygaśnięciem zasady waitTimeout lub jeśli waitTimeout zostanie pominięta, kamera powinna od razu zwrócić odpowiedź.Uwaga: kamera może zwrócić odpowiedź przed wygaśnięciem atrybutu waitTimeout, nawet jeśli odcisk cyfrowy nie uległ zmianie. Sprawdzoną metodą jest poczekanie na wygaśnięcie zasady waitTimeout.

Uwagi o wdrażaniu aparatu:

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

Wyniki
stateFingerprint Ciąg znaków Nowy odcisk cyfrowy stanu aparatu (taki sam jak w interfejsie /osc/state API).
throttleTimeout Liczba całkowita Zalecany czas oczekiwania klienta przed następnym połączeniem checkForUpdates. Klienci mogą przesyłać żądania przed wygaśnięciem zasady throttleTimeout, a kamery powinny zezwalać na takie wcześniejsze żądania, jeśli to możliwe.

Uwagi dotyczące implementacji klienta:

  • Po otrzymaniu odpowiedzi klient powinien porównać otrzymaną kopię stateFingerprint ze swoją kopią. Jeśli nie, klient powinien zażądać bieżącego stanu kamery za pomocą interfejsu API _/osc/state.
  • Klienty inteligentne będą ograniczać żądania niezależnie od odpowiedzi kamery. Jeśli na przykład kamera zwróci niestandardową odpowiedź (natychmiast: bez zmian i o niskiej wartości lub 0 throttleTimeout), klient powinien zastosować własny parametr throttleTimeout, zanim zażąda od kamery innego parametru checkForUpdates.

Uwagi o wdrażaniu aparatu:

  • W odpowiedzi na żądanie checkForUpdates kamera powinna określić uzasadnioną wartość throttleTimeout. Jeśli kamera obsługuje żądania długoterminowe (odpowiedź otrzymasz dopiero po waitTimeout, o ile stan się nie zmienił), możesz zwrócić wartość throttleTimeout jako 0. W takim przypadku klienci mogą natychmiast poprosić o aktualizację.
  • Jeśli kamera obsługuje tylko szybkie odpowiedzi (niezalecane), powinna zwracać rozsądną wartość throttleTimeout, aby uniknąć ciągłego ruchu związanego z żądaniami/odpowiedziami po stronie klienta. Na przykład uzasadniona wartość throttleTimeout to 60 sekund, aby umożliwić przesyłanie 1 żądania klienta na minutę.
  • Sprawdzoną metodą jest zwrócenie wartości throttleTimeout odpowiedniego dla możliwości kamery. Jeśli z powodu problemu z serwerem serwer nie może określić odpowiedniej wartości throttleTimeout, kamera powinna w odpowiedzi podać kod stanu 5XX i treści JSON zawierające kod błędu serverError.

Błąd

Kod błędu
missingParameter Nie określono stateFingerprint.
invalidParameterName Co najmniej jedna 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 ma nieprawidłowy typ.
serverError Serwer nie mógł określić odpowiedniej wartości throttleTimeout dla swojej odpowiedzi. Problem z serwerem można zidentyfikować po wartości 5XX zwróconej w odpowiedzi. Producenci aparatów powinni udostępnić tabelę z kodami 5XX i odpowiadającymi im 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."
    }
}