تُرجمت هذه الوثيقة آليًا من الإنجليزية باستخدام Claude AI. ينبغي مراجعة المصطلحات المتعلقة بمجال WMO/الأرصاد الجوية من قِبل متحدث أصلي قبل الاستخدام الإنتاجي. راجع النسخة الإنجليزية الأصلية للاطلاع على النسخة المرجعية.

1. نظرة عامة

يوفر WIS2 Downloader واجهة برمجية REST لإدارة الاشتراكات ومراقبة النظام.

2. المصادقة

لا تتطلب واجهة API حاليًا أي مصادقة. في بيئة الإنتاج، يُنصح بوضعها خلف بروكسي عكسي يوفر المصادقة.

3. API الاشتراكات

3.1. عرض الاشتراكات

يعيد جميع الاشتراكات النشطة.

GET /subscriptions

3.1.1. الاستجابة

الحالة الوصف

200

نجاح — يعيد خريطة من الموضوع إلى تفاصيل الاشتراك

503

Redis غير متاح

3.1.2. مثال

curl http://localhost:5002/subscriptions
{
  "cache/a/wis2/+/data/core/weather/surface-based-observations/#": {
    "topic": "cache/a/wis2/+/data/core/weather/surface-based-observations/#",
    "save_path": "surface-obs",
    "filters": {
      "accepted_media_types": ["application/bufr", "application/grib"]
    }
  }
}

3.2. إنشاء اشتراك

ينشئ اشتراكًا جديدًا في موضوع WIS2.

POST /subscriptions
Content-Type: application/json

3.2.1. جسم الطلب

الحقل النوع مطلوب الوصف

topic

string

نعم

نمط موضوع MQTT في WIS2. يدعم + (مستوى واحد) و`#` (متعدد المستويات) كأحرف بدل.

target

string

لا

مجلد فرعي تحت /data لحفظ الملفات فيه.

filters

object

لا

إعداد الفلتر.

filters.accepted_media_types

array

لا

قائمة أنواع MIME المسموح بها. تدعم أحرف البدل (مثل application/x-grib*).

3.2.2. الاستجابة

الحالة الوصف

202

مقبول — تم إدراج الاشتراك في قائمة الانتظار للمعالجة

400

طلب غير صحيح — الموضوع مفقود أو غير صالح

503

الخدمة غير متاحة — فشل الاتصال بـ Redis

3.2.3. ترويسات الاستجابة

الترويسة الوصف

Location

عنوان URL لاسترداد تفاصيل الاشتراك

3.2.4. مثال

curl -X POST http://localhost:5002/subscriptions \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "cache/a/wis2/+/data/core/weather/surface-based-observations/#",
    "target": "surface-obs",
    "filters": {
      "accepted_media_types": ["application/bufr", "application/grib"]
    }
  }'
{
  "status": "accepted",
  "topic": "cache/a/wis2/+/data/core/weather/surface-based-observations/#",
  "target": "surface-obs"
}

3.3. الحصول على اشتراك

يعيد تفاصيل اشتراك محدد.

GET /subscriptions/{topic}

3.3.1. معاملات المسار

المعامل النوع الوصف

topic

string

موضوع WIS2 (يتطلب # فقط ترميز URL كـ %23)

3.3.2. ترميز URL

يتطلب ترميز URL للحرف # فقط:

الحرف المُرمَّز السبب

#

%23

وإلا يُفسَّر كجزء من URL
لا تتطلب الشُّرَط المائلة (/) والـ`+` أي ترميز في المسار.

3.3.3. الاستجابة

الحالة الوصف

200

نجاح

400

موضوع غير صالح

404

الاشتراك غير موجود

503

Redis غير متاح

3.3.4. مثال

curl "http://localhost:5002/subscriptions/cache/a/wis2/+/data/core/weather/surface-based-observations/%23"
{
  "topic": "cache/a/wis2/+/data/core/weather/surface-based-observations/#",
  "save_path": "surface-obs",
  "filters": {
    "accepted_media_types": ["application/bufr", "application/grib"]
  }
}

3.4. حذف اشتراك

يزيل اشتراكًا.

DELETE /subscriptions/{topic}

3.4.1. معاملات المسار

المعامل النوع الوصف

topic

string

موضوع WIS2 مُرمَّز بـ URL

3.4.2. الاستجابة

الحالة الوصف

200

تم الحذف بنجاح

400

موضوع غير صالح

503

Redis غير متاح

3.4.3. مثال

curl -X DELETE "http://localhost:5002/subscriptions/cache/a/wis2/+/data/core/weather/surface-based-observations/%23"
{
  "status": "deleted",
  "topic": "cache/a/wis2/+/data/core/weather/surface-based-observations/#"
}

4. API المراقبة

4.1. فحص الصحة

يعيد حالة صحة الخدمة.

GET /health

4.1.1. الاستجابة

يعيد دائمًا 200. تحقق من حقل status للحالة الفعلية.

الحقل القيم

status

healthy أو unhealthy

4.1.2. مثال

curl http://localhost:5002/health
{"status": "healthy"}

4.2. مقاييس Prometheus

يعيد المقاييس بصيغة نص Prometheus.

GET /metrics

4.2.1. الاستجابة

الحالة الوصف

200

مقاييس بصيغة نص Prometheus

500

خطأ في توليد المقاييس

4.2.2. المقاييس المتاحة

المقياس النوع التسميات الوصف

wis2downloader_notifications_total

Counter

status

إجمالي الإشعارات المعالَجة

wis2downloader_downloads_total

Counter

cache, media_type

الملفات المُنزَّلة بنجاح

wis2downloader_downloads_bytes_total

Counter

cache, media_type

إجمالي البايتات المُنزَّلة

wis2downloader_skipped_total

Counter

reason

الإشعارات المتخطاة حسب السبب

wis2downloader_failed_total

Counter

cache, reason

التنزيلات الفاشلة

wis2downloader_celery_queue_length

Gauge

queue_name

المهام الحالية في قائمة انتظار Celery

4.2.3. مثال

curl http://localhost:5002/metrics
# HELP wis2downloader_downloads_total Total number of files downloaded.
# TYPE wis2downloader_downloads_total counter
wis2downloader_downloads_total{cache="example.cache.com",media_type="application/bufr"} 42.0

# HELP wis2downloader_notifications_total Total notifications processed.
# TYPE wis2downloader_notifications_total counter
wis2downloader_notifications_total{status="success"} 42.0
wis2downloader_notifications_total{status="skipped"} 5.0

4.3. مواصفة OpenAPI

تعيد مواصفة OpenAPI 3.0 بصيغة JSON.

GET /openapi

4.4. واجهة Swagger

توثيق API تفاعلي.

GET /
GET /swagger

5. استجابات الأخطاء

تتبع جميع استجابات الأخطاء هذا التنسيق:

{
  "error": "Error message describing the problem"
}

5.1. رسائل الخطأ الشائعة

الحالة الخطأ السبب

400

"No topic provided"

POST /subscriptions بدون حقل الموضوع

400

"No topic passed"

GET/DELETE بموضوع فارغ

404

"Subscription for topic X not found"

الموضوع غير مشترك

503

"Failed to connect to Redis: …​"

Redis غير متاح

503

"Failed to queue subscription command…​"

فشل Redis pub/sub

503

"Failed to persist subscription…​"

فشل الكتابة في Redis

6. مخططات البيانات

6.1. الاشتراك

{
  "topic": "string (required) - WIS2 MQTT topic pattern",
  "save_path": "string | null - Subdirectory for downloads",
  "filters": {
    "accepted_media_types": ["array of MIME type strings"]
  }
}

6.2. الفلاتر

{
  "accepted_media_types": [
    "application/bufr",
    "application/grib",
    "application/x-netcdf*"
  ]
}

6.2.1. أنواع الوسائط المقبولة افتراضيًا

عند عدم تحديد أي فلتر، تُقبل هذه الأنواع:

[
  "image/gif", "image/jpeg", "image/png", "image/tiff",
  "application/pdf", "application/postscript",
  "application/bufr", "application/grib",
  "application/x-hdf", "application/x-hdf5",
  "application/x-netcdf", "application/x-netcdf4",
  "text/plain", "text/html", "text/xml", "text/csv",
  "text/tab-separated-values"
]

7. مرجع أنماط الموضوعات

7.1. هيكل موضوع WIS2

{origin|cache}/a/wis2/{centre-id}/data/{data-policy}/{earth-system-domain}/{category}/...

  • origin - البيانات الأصلية من مزود البيانات

  • cache - نسخة مخزنة مؤقتًا من ذاكرة تخزين عالمية (مُنصح به للموثوقية)

  • {centre-id} - رمز الدولة/المنظمة، مسبوقًا برمز الدولة ISO2C (مثل de-dwd)

  • {data-policy} - سياسة البيانات الموحدة لـ WMO: core أو recommended

  • {earth-system-domain} - نطاق النظام الأرضي من سياسة البيانات الموحدة لـ WMO

7.2. أحرف البدل

النمط الرمز الوصف

مستوى واحد

+

يطابق مستوى واحدًا تمامًا

متعدد المستويات

#

يطابق صفرًا أو أكثر من المستويات (يجب أن يكون في النهاية)

7.3. أمثلة

النمط ما يطابقه

cache/a/wis2/de-dwd/data/#

جميع البيانات من Deutscher Wetterdienst

cache/a/wis2/+/data/core/weather/surface-based-observations/#

ملاحظات سطحية من جميع المراكز

cache/a/wis2/+/data/core/#

جميع البيانات الأساسية من أي مركز

cache/a/wis2//data//weather/#

جميع بيانات الطقس (أي سياسة) من أي مركز