CheckForUpdate

API /osc/checkForUpdates xác định các bản cập nhật trạng thái bằng cách so sánh stateFingerprint đã biết gần đây nhất của ứng dụng với fingerprint hiện tại của máy ảnh.

Đầu vào

Tên Loại Nội dung mô tả
stateFingerprint Chuỗi Vân tay số của trạng thái máy ảnh từ lần gần đây nhất ứng dụng gọi /osc/state hoặc /osc/checkForUpdates.
waitTimeout Số nguyên (không bắt buộc) Số giây chờ cho đến khi trạng thái thay đổi trên máy ảnh diễn ra trước khi trả về phản hồi. Khi waitTimeout hết hạn, máy ảnh sẽ trả về phản hồi ngay cả khi vân tay không thay đổi. Nếu phát hiện thấy sự thay đổi trạng thái trước khi waitTimeout hết hạn hoặc nếu bỏ qua waitTimeout, thì máy ảnh sẽ trả về phản hồi ngay lập tức.Lưu ý: máy ảnh có thể trả về phản hồi trước khi waitTimeout hết hạn ngay cả khi vân tay số chưa thay đổi. Tuy nhiên, phương pháp hay nhất là đợi cho đến khi waitTimeout hết hạn.

Lưu ý khi triển khai camera:

  • Khi nhận được lệnh gọi này, máy ảnh sẽ so sánh vân tay số ở trạng thái hiện tại với thông số stateFingerprint đã nhận. Nếu vân tay đã thay đổi, thì máy ảnh phải ngay lập tức trả về vân tay mới.

Đầu ra

Tên Loại Mô tả
stateFingerprint Chuỗi Vân tay số mới của trạng thái máy ảnh (giống như trong API /osc/state).
throttleTimeout Số nguyên Số giây nên đợi khách hàng chờ trước cuộc gọi checkForUpdates tiếp theo. Ứng dụng có thể đưa ra yêu cầu trước khi throttleTimeout hết hạn, và camera nên cho phép những yêu cầu sớm này (nếu có thể).

Lưu ý khi triển khai ứng dụng:

  • Khi nhận được phản hồi, ứng dụng nên so sánh stateFingerprint đã nhận được với bản sao của nó. Nếu các trạng thái này không khớp nhau, ứng dụng cần yêu cầu trạng thái hiện tại của camera bằng API _/osc/state.
  • Ứng dụng thông minh sẽ điều tiết các yêu cầu bất kể phản hồi của máy ảnh. Ví dụ: nếu máy ảnh trả về phản hồi không chuẩn (ngay lập tức, không có thay đổi và throttleTimeout) thấp hoặc 0, thì ứng dụng phải áp dụng throttleTimeout của riêng mình trước khi yêu cầu một checkForUpdates khác từ máy ảnh.

Lưu ý khi triển khai camera:

  • Khi phản hồi checkForUpdates, máy ảnh phải xác định một throttleTimeout hợp lý. Nếu máy ảnh hỗ trợ logic yêu cầu lâu dài (chỉ phản hồi sau waitTimeout nếu trạng thái không thay đổi), thì bạn có thể trả về throttleTimeout dưới dạng 0. Trong trường hợp này, khách hàng có thể yêu cầu thông tin cập nhật ngay lập tức.
  • Nếu chỉ hỗ trợ phản hồi nhanh (không nên dùng), thì máy ảnh nên trả về một throttleTimeout hợp lý để tránh lưu lượng truy cập yêu cầu/phản hồi liên tục với ứng dụng. Ví dụ: throttleTimeout hợp lý sẽ là 60 giây để cho phép một yêu cầu ứng dụng mỗi phút.
  • Phương pháp hay nhất là trả về một throttleTimeout phù hợp với các chức năng của camera. Nếu máy chủ không xác định được throttleTimeout phù hợp do sự cố máy chủ, thì máy ảnh phải phản hồi bằng mã trạng thái 5XX và nội dung JSON chứa mã lỗi serverError.

Lỗi

Mã lỗi Mô tả
missingParameter stateFingerprint chưa được chỉ định.
invalidParameterName Một hoặc nhiều tên tham số đầu vào không nhận dạng được.
invalidParameterValue Các tên thông số được công nhận, nhưng một hoặc nhiều giá trị không hợp lệ; ví dụ: waitTimeout nằm ngoài dải ô hoặc loại của nó không chính xác.
serverError Máy chủ không thể xác định giá trị throttleTimeout phù hợp cho phản hồi. Sự cố máy chủ sẽ được xác định bằng giá trị 5XX được trả về trong phản hồi. Các nhà sản xuất máy ảnh nên cung cấp một bảng gồm mã 5XX và các trạng thái máy chủ tương ứng có thể gửi lỗi này.

Ví dụ:
Yêu cầu 
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
}
Đáp 
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
}
Yêu cầu 
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
}
Đáp 
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."
    }
}