CheckForUpdates

API /osc/checkForUpdates mengidentifikasi pembaruan status dengan membandingkan stateFingerprint klien yang terakhir dikenali dengan fingerprint terbaru kamera.

Input

Nama Tipe Keterangan
stateFingerprint String Sidik jari status kamera sejak terakhir klien memanggil /osc/state atau /osc/checkForUpdates.
waitTimeout Integer (opsional) Jumlah detik menunggu terjadinya perubahan status pada kamera sebelum mengembalikan respons. Bila waitTimeout kedaluwarsa, kamera harus mengembalikan respons meskipun sidik jari belum berubah. Jika perubahan status terdeteksi sebelum waitTimeout kedaluwarsa, atau jika waitTimeout dihapus, kamera harus segera mengembalikan respons.Catatan: kamera bisa mengembalikan respons sebelum waitTimeout kedaluwarsa meskipun sidik jari belum berubah, tetapi praktik terbaiknya adalah menunggu sampai waitTimeout kedaluwarsa.

Catatan implementasi kamera:

  • Saat menerima panggilan ini, kamera akan membandingkan sidik jari status saat ini dengan parameter stateFingerprint yang diterima. Jika sidik jari berubah, kamera harus segera mengembalikan sidik jari baru.

Output

Nama Tipe Keterangan
stateFingerprint String Sidik jari baru atas status kamera (sama dengan di API /osc/state).
throttleTimeout Integer Jumlah detik yang disarankan bagi klien untuk menunggu sebelum panggilan checkForUpdates berikutnya. Klien bisa membuat permintaan sebelum throttleTimeout kedaluwarsa, dan kamera harus memperbolehkan permintaan dini ini jika memungkinkan.

Catatan implementasi klien:

  • Saat menerima respons, klien harus membandingkan stateFingerprint yang diterima dengan salinannya. Jika tidak sama, klien harus meminta status terbaru kamera dengan menggunakan API _/osc/state.
  • Klien yang pintar akan mengerem permintaan, apa pun respons kamera. Misalnya, jika kamera mengembalikan respons non-standar (segera, dengan tidak mengubah dan throttleTimeout) yang rendah atau 0, klien harus menekankan throttleTimeout dirinya sendiri sebelum meminta checkForUpdates lain dari kamera tersebut.

Catatan implementasi kamera:

  • Saat merespons checkForUpdates, kamera harus menentukan throttleTimeout yang sewajarnya. Jika kamera mendukung logika permintaan jangka lama (hanya merespons setelah waitTimeout jika status belum berubah), tidak masalah untuk mengembalikan throttleTimeout sebagai 0. Dalam hal ini, klien bisa segera meminta pembaruan.
  • Jika kamera hanya mendukung respons cepat (tidak disarankan), kamera harus mengembalikan throttleTimeout yang sewajarnya untuk mencegah lalu lintas permintaan/respons yang terus-menerus dengan klien. Misalnya, throttleTimeout yang sewajarnya adalah 60 detik, untuk memungkinkan satu permintaan klien per menit.
  • Praktik terbaik adalah mengembalikan throttleTimeout yang sesuai dengan kemampuan kamera. Jika server tidak bisa menentukan throttleTimeout yang sesuai karena ada masalah server, kamera harus merespons dengan kode status 5XX dan tubuh JSON berisi kode kesalahan serverError.

Kesalahan

Kode kesalahan Keterangan
missingParameter stateFingerprint tidak ditetapkan.
invalidParameterName Satu atau beberapa nama parameter input tidak dikenal.
invalidParameterValue Nama parameter dikenali, namun satu atau beberapa nilainya tidak valid; misalnya waitTimeout di luar kisaran atau tipenya salah.
serverError Server tidak bisa menentukan nilai throttleTimeout yang sesuai karena responsnya. Masalah server akan diidentifikasi melalui nilai 5XX yang dikembalikan dalam responsnya. Produsen kamera harus memberikan tabel kode 5XX dan status server terkait yang bisa melontarkan kesalahan ini.

Contoh
Permintaan 
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
}
Respons 
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
}
Permintaan 
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
}
Respons 
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."
    }
}