API /osc/checkForUpdates
xác định 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.
Tên |
Loại |
Mô tả |
stateFingerprint |
Chuỗi |
Vân tay số của trạng thái camera 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 máy ảnh thay đổi trạng thái 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 thay đổi về trạng thái trước khi waitTimeout hết hạn hoặc nếu bạn bỏ qua waitTimeout , thì máy ảnh sẽ trả về ngay phản hồi.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 không thay đổi, nhưng 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, camera sẽ so sánh vân tay trạng thái hiện tại với tham số
stateFingerprint
đã nhận. Nếu vân tay đã thay đổi, máy ảnh phải ngay lập tức trả về vân tay mới.
Đầu ra
|
|
|
stateFingerprint |
Chuỗi |
Vân tay số mới của trạng thái máy ảnh (tương tự như trong API /osc/state ). |
throttleTimeout |
Số nguyên |
Số giây đề xuất để ứng dụ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à máy ảnh sẽ cho phép thực hiện các yêu cầu sớm này nếu có thể. |
Ghi chú về việc triển khai ứng dụng:
- Sau 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 không khớp, ứng dụng cần yêu cầu trạng thái hiện tại của camera bằng cách sử dụng API _/osc/state
.
- Ứng dụng thông minh sẽ điều tiết 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, khi không có thay đổi và
throttleTimeout)
thấp hoặc bằng 0), ứng dụng nên á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 cần xác định 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 cập nhật ngay lập tức.
- Nếu chỉ hỗ trợ phản hồi nhanh (không nên), máy ảnh sẽ 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ụ: một throttleTimeout
hợp lý sẽ là 60 giây để cho phép thực hiện một yêu cầu của ứ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 chức năng của máy ảnh. Nếu máy chủ không xác định được throttleTimeout
thích 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 |
|
missingParameter |
stateFingerprint chưa được chỉ định. |
invalidParameterName |
Không nhận dạng được một hoặc nhiều tên thông số đầu vào. |
invalidParameterValue |
Các tên thông số được nhận dạng, nhưng một hoặc nhiều giá trị không hợp lệ; ví dụ: waitTimeout nằm ngoài phạm vi hoặc loại thông số không chính xác. |
serverError |
Máy chủ không thể xác định giá trị throttleTimeout thích 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. Nhà sản xuất máy ảnh nên cung cấp một bảng gồm mã 5XX và trạng thái máy chủ tương ứng có thể phát sinh 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."
}
} |