CheckForUpdates

ה-API של /osc/checkForUpdates מזהה עדכוני מצב על ידי השוואה בין stateFingerprint הידוע האחרון של הלקוח לבין fingerprint הנוכחי של המצלמה.

קלט

שם סוג תיאור
stateFingerprint מחרוזת טביעת אצבע של מצב המצלמה מהפעם האחרונה שהלקוח התקשר אל /osc/state או /osc/checkForUpdates.
waitTimeout מספר שלם (אופציונלי) מספר השניות להמתנה לשינוי המצב במצלמה לפני החזרת התגובה. כשהתוקף של waitTimeout יפוג, המצלמה אמורה להחזיר תגובה גם אם טביעת האצבע לא השתנתה. אם מזוהה שינוי במצב לפני שהתוקף של waitTimeout פג, או אם waitTimeout לא מופיע, המצלמה יכולה להחזיר תגובה באופן מיידי.הערה: המצלמה יכולה להחזיר תגובה לפני שפג התוקף של waitTimeout, גם אם טביעת האצבע לא השתנתה, אבל השיטה המומלצת היא לחכות עד שתוקף waitTimeout יפוג.

הערות להטמעת המצלמה:

  • לאחר קבלת השיחה, המצלמה משווה בין טביעת האצבע של המצב הנוכחי שלה לבין הפרמטר stateFingerprint שהתקבל. אם טביעת האצבע השתנתה, המצלמה חייבת להחזיר באופן מיידי את טביעת האצבע החדשה.

פלט

שם סוג תיאור
stateFingerprint מחרוזת טביעת אצבע חדשה למצב המצלמה (כמו ב-API של /osc/state).
throttleTimeout מספר שלם מספר השניות המומלץ ללקוח להמתנה לפני שיחת checkForUpdates הבאה. הלקוחות יכולים לשלוח בקשות לפני שהתוקף של throttleTimeout פג, והמצלמות צריכות לאפשר את הבקשות המוקדמות האלה אם אפשר.

הערות להטמעת לקוח:

  • עם קבלת תשובה, הלקוח צריך להשוות את stateFingerprint שהתקבל לעותק שלו. אם הם לא תואמים, הלקוח צריך לבקש את המצב הנוכחי של המצלמה באמצעות ה-API של _/osc/state.
  • לקוחות חכמים יבצעו ויסות נתונים (throttle) לבקשות ללא קשר לתגובת המצלמה. לדוגמה, אם מצלמה מחזירה תגובה לא רגילה באופן מיידי, עם ללא שינוי ועם ערך throttleTimeout) נמוך או 0, הלקוח צריך להגדיר throttleTimeout משלו לפני שיבקש checkForUpdates נוסף מהמצלמה.

הערות להטמעת המצלמה:

  • בתגובה ל-checkForUpdates, המצלמה צריכה לקבוע ערך throttleTimeout סביר. אם המצלמה תומכת בלוגיקת בקשות לטווח ארוך (צריך להגיב רק אחרי waitTimeout אם המצב לא השתנה), אפשר להחזיר את throttleTimeout בתור 0. במקרה כזה, הלקוחות יכולים לבקש עדכונים באופן מיידי.
  • אם המצלמה תומכת בתגובות מהירות בלבד (לא מומלץ), היא צריכה להחזיר ערך throttleTimeout סביר כדי למנוע תנועה קבועה של בקשה/תגובה אצל הלקוח. לדוגמה, ערך סביר של throttleTimeout הוא 60 שניות, כדי לאפשר בקשת לקוח אחת בכל דקה.
  • השיטה המומלצת היא להחזיר throttleTimeout שמתאים ליכולות של המצלמה. אם השרת לא יכול לקבוע throttleTimeout מתאים בגלל בעיה בשרת, המצלמה אמורה להגיב עם קוד סטטוס 5XX וגוף JSON שמכיל את קוד השגיאה serverError.

שגיאה

קוד שגיאה תיאור
missingParameter stateFingerprint לא צוין.
invalidParameterName שם אחד או יותר של פרמטר קלט לא מזוהה.
invalidParameterValue שמות הפרמטרים מזוהים, אבל אחד או יותר מהערכים לא חוקי; לדוגמה, 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."
    }
}