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

وتحدّد واجهة برمجة التطبيقات /osc/checkForUpdates تحديثات الحالة من خلال مقارنة آخر stateFingerprint معروف للعميل مع fingerprint الحالي للكاميرا.

إدخال

الاسم النوع الوصف
stateFingerprint سلسلة بصمة الإصبع لحالة الكاميرا من آخر مرة كان العميل يُسمى /osc/state أو /osc/checkForUpdates.
waitTimeout عدد صحيح (اختياري) عدد الثواني التي يجب انتظارها حتى يحدث تغيُّر الحالة في الكاميرا قبل عرض الاستجابة. عند انتهاء صلاحية waitTimeout، من المفترض أن تعرض الكاميرا استجابة حتى إذا لم يتم تغيير بصمة الإصبع. إذا تم رصد تغيير في الحالة قبل انتهاء صلاحية waitTimeout، أو إذا تم حذف waitTimeout، من المفترض أن تعرض الكاميرا الاستجابة على الفور.ملاحظة: بإمكان الكاميرا إرسال الردّ قبل انتهاء صلاحية waitTimeout حتى إذا لم يتم تغيير بصمة الإصبع، ولكن أفضل الممارسات هي الانتظار حتى انتهاء صلاحية waitTimeout.

ملاحظات حول تنفيذ الكاميرا:

  • عند تلقّي هذه المكالمة، تقارن الكاميرا الملف المرجعي للحالة الحالية مع مَعلمة stateFingerprint التي تم استلامها. إذا تم تغيير بصمة الإصبع، يجب أن تعرض الكاميرا البصمة الجديدة على الفور.

الناتج
stateFingerprint سلسلة بصمة إصبع جديدة لحالة الكاميرا (كما هي الحال في واجهة برمجة تطبيقات /osc/state).
throttleTimeout عدد صحيح عدد الثواني المقترَح للعميل انتظاره قبل الاتصال التالي على checkForUpdates. يمكن للعملاء إرسال الطلبات قبل انتهاء صلاحية throttleTimeout، ومن المفترض أن تسمح الكاميرات بهذه الطلبات المبكّرة إن أمكن.

ملاحظات حول تنفيذ العميل:

  • بعد تلقّي ردّ، على العميل مقارنة stateFingerprint الذي تم استلامه بنسخته. وفي حال عدم تطابُقهما، على العميل طلب الحالة الراهنة للكاميرا باستخدام واجهة برمجة التطبيقات _/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."
    }
}