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.
  • לקוחות חכמים יווסתו בקשות ללא קשר לתגובת המצלמה. לדוגמה, אם מצלמה מחזירה תגובה לא סטנדרטית (באופן מיידי, עם ללא שינוי ועם ערך נמוך או 0 throttleTimeout), הלקוח צריך להטיל 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."
    }
}