API ของ /osc/checkForUpdates
จะระบุการอัปเดตสถานะโดยเปรียบเทียบ stateFingerprint
ล่าสุดที่ทราบของไคลเอ็นต์กับ fingerprint
ปัจจุบันของกล้อง
ชื่อ |
ประเภท |
คำอธิบาย |
stateFingerprint |
สตริง |
ลายนิ้วมือสถานะกล้องจากครั้งล่าสุดที่ไคลเอ็นต์โทรหา /osc/state หรือ /osc/checkForUpdates |
waitTimeout |
จำนวนเต็ม (ไม่บังคับ) |
จำนวนวินาทีที่รอให้ระบบเปลี่ยนสถานะในกล้องก่อนส่งคืนการตอบสนอง เมื่อ waitTimeout หมดอายุ กล้องควรตอบกลับแม้ว่าจะไม่มีการเปลี่ยนแปลงลายนิ้วมือก็ตาม หากตรวจพบการเปลี่ยนแปลงสถานะก่อน waitTimeout จะหมดอายุ หรือหากเว้น waitTimeout ไว้ กล้องจะตอบกลับทันทีหมายเหตุ: กล้องอาจตอบกลับคำขอก่อน waitTimeout จะหมดอายุได้แม้ว่าลายนิ้วมือจะไม่เปลี่ยนไป แต่แนวทางปฏิบัติแนะนำคือให้รอจนกว่า waitTimeout จะหมดอายุ |
หมายเหตุเกี่ยวกับการใช้งานกล้อง
- เมื่อรับสายนี้ กล้องจะเปรียบเทียบลายนิ้วมือสถานะปัจจุบันกับพารามิเตอร์
stateFingerprint
ที่ได้รับ หากลายนิ้วมือมีการเปลี่ยนแปลง กล้องต้องส่งคืนลายนิ้วมือใหม่ทันที
เอาต์พุต
|
|
|
stateFingerprint |
สตริง |
ลายนิ้วมือใหม่ของสถานะกล้อง (เหมือนกับใน /osc/state API) |
throttleTimeout |
จำนวนเต็ม |
จำนวนวินาทีที่แนะนำให้ลูกค้ารอก่อนการโทร checkForUpdates ครั้งถัดไป ลูกค้าสามารถส่งคำขอก่อนที่ throttleTimeout จะหมดอายุ และกล้องควรอนุญาตคำขอล่วงหน้าเหล่านี้หากเป็นไปได้ |
หมายเหตุการใช้งานไคลเอ็นต์:
- เมื่อได้รับคําตอบแล้ว ไคลเอ็นต์ควรเปรียบเทียบ
stateFingerprint
ที่ได้รับกับสําเนา หากไม่ตรงกัน ไคลเอ็นต์ควรขอสถานะปัจจุบันของกล้องโดยใช้ _/osc/state
API
- ไคลเอ็นต์อัจฉริยะจะควบคุมคำขอโดยไม่คำนึงถึงการตอบสนองของกล้อง ตัวอย่างเช่น หากกล้องส่งการตอบสนองที่ไม่ใช่แบบมาตรฐาน (ในทันที ในทันทีที่ไม่มีการเปลี่ยนแปลง และมีค่าต่ำหรือ
throttleTimeout)
เป็น 0 ไคลเอ็นต์ควรกำหนด throttleTimeout
ของตัวเองก่อนที่จะขอ checkForUpdates
อีกรายการจากกล้อง
หมายเหตุเกี่ยวกับการใช้งานกล้อง
- เมื่อตอบสนองต่อ
checkForUpdates
กล้องควรกำหนด throttleTimeout
ที่สมเหตุสมผล หากกล้องรองรับตรรกะคำขอเป็นระยะเวลานาน (ตอบกลับหลังจาก waitTimeout
เท่านั้น หากสถานะไม่เปลี่ยนแปลง) สามารถคืนค่า throttleTimeout
เป็น 0
ได้ ในกรณีนี้ ลูกค้าสามารถขอการอัปเดตได้ทันที
- หากกล้องรองรับเฉพาะการตอบกลับเร็ว (ไม่แนะนำ) ก็ควรแสดงผล
throttleTimeout
ที่สมเหตุสมผลเพื่อหลีกเลี่ยงการรับส่งข้อมูลคำขอ/การตอบกลับที่ต่อเนื่องกับไคลเอ็นต์ ตัวอย่างเช่น throttleTimeout
ที่สมเหตุสมผลคือ 60 วินาทีเพื่อให้อนุญาตคำขอไคลเอ็นต์ 1 รายการต่อนาที
- แนวทางปฏิบัติแนะนำคือการแสดงค่า
throttleTimeout
ที่เหมาะกับความสามารถของกล้อง หากเซิร์ฟเวอร์ระบุ throttleTimeout
ที่เหมาะสมไม่ได้เนื่องจากเซิร์ฟเวอร์มีปัญหา กล้องควรตอบกลับด้วยรหัสสถานะ 5XX และเนื้อความ JSON ที่มีรหัสข้อผิดพลาด serverError
ข้อผิดพลาด
รหัสข้อผิดพลาด |
|
missingParameter |
ไม่ได้ระบุ stateFingerprint |
invalidParameterName |
ไม่รู้จักชื่อพารามิเตอร์อินพุตอย่างน้อย 1 รายการ |
invalidParameterValue |
ระบบรู้จักชื่อพารามิเตอร์ แต่ค่าอย่างน้อย 1 ค่าไม่ถูกต้อง ตัวอย่างเช่น waitTimeout อยู่นอกช่วงหรือประเภทของค่าไม่ถูกต้อง |
serverError |
เซิร์ฟเวอร์กำหนดค่า throttleTimeout ที่เหมาะสมสำหรับการตอบสนองไม่ได้ ปัญหาของเซิร์ฟเวอร์จะระบุโดยค่า 5XX ที่แสดงผลในการตอบกลับ ผู้ผลิตกล้องควรระบุตารางรหัส 5XX และสถานะของเซิร์ฟเวอร์ที่เกี่ยวข้องที่อาจทำให้เกิดข้อผิดพลาดนี้ |
ตัวอย่าง |
คำขอ |
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
} |
คำตอบ |
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
} |
คำขอ |
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
} |
คำตอบ |
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."
}
} |