التحقّق من التحديثات

تحدِّد واجهة برمجة التطبيقات /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.
  • وستقلل البرامج الذكية الطلبات بغض النظر عن استجابة الكاميرا. على سبيل المثال، إذا عرضت كاميرا استجابة غير عادية (فورًا، وبدون أي تغيير مع عرض منخفض أو 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."
    }
}