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

1. نظرة عامة

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

استبدل localhost:5002 بعنوان خادمك في حال النشر عن بُعد. يُهيَّأ عنوان URL الأساسي عبر WIS2DOWNLOADER_SUBSCRIPTION_MANAGER_URL في .env.

2. المصادقة

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

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

يُعرَّف كل اشتراك بـ UUID ويربط موضوع MQTT ومسار حفظ وفلتر اختياري وبيانات اعتماد اختيارية وقائمة انتظار. يمكن أن تشترك اشتراكات متعددة في نفس الموضوع — يُفتح اتصال MQTT مرة واحدة وتُوجَّه الرسائل إلى جميع الاشتراكات المطابقة.

3.1. عرض قائمة الاشتراكات

يُعيد جميع الاشتراكات النشطة مجمَّعةً حسب الموضوع.

GET /subscriptions

3.1.1. الاستجابة

الحالة الوصف

200

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

503

Redis غير متوفر

3.1.2. مثال

curl http://localhost:5002/subscriptions
{
  "cache/a/wis2/+/data/core/weather/surface-based-observations/#": {
    "550e8400-e29b-41d4-a716-446655440000": {
      "save_path": "surface-obs",
      "filter": {}
    },
    "661f9511-f30c-52e5-b827-557766551111": {
      "save_path": "surface-obs-bufr",
      "filter": {
        "name": "bufr-only",
        "rules": [
          { "id": "accept-bufr", "order": 1, "match": { "media_type": { "equals": "application/bufr" } }, "action": "accept" }
        ]
      }
    }
  }
}

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

يُنشئ اشتراكًا جديدًا. يُعيِّن UUID ويُعيد سجل الاشتراك الكامل.

إذا كان هذا أول اشتراك للموضوع المحدد، يُفتح اتصال MQTT. تستخدم الاشتراكات الإضافية لنفس الموضوع الاتصال القائم.

POST /subscriptions
Content-Type: application/json

3.2.1. جسم الطلب

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

topic

string

نعم

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

target

string

لا

المجلد الفرعي تحت جذر البيانات حيث تُحفظ الملفات.

filter

كائن

لا

فلتر قائم على قواعد. راجع مخطط الفلتر.

credentials

كائن

لا

بيانات اعتماد HTTP لمجموعات البيانات ذات الوصول المقيَّد. راجع مخطط بيانات الاعتماد.

queue

string

لا

قائمة انتظار التنزيل: high_priority أو small_files (الافتراضي) أو large_files.

3.2.2. الاستجابة

الحالة الوصف

201

تم الإنشاء — يُعيد سجل الاشتراك الكامل

400

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

503

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

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

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

Location

عنوان URL لاسترداد الاشتراك المُنشأ (/subscriptions/{id})

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"
  }'
# اشتراك مع فلتر
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-bufr",
    "filter": {
      "name": "bufr-only",
      "rules": [
        { "id": "accept-bufr", "order": 1, "match": { "media_type": { "equals": "application/bufr" } }, "action": "accept" },
        { "id": "default-reject", "order": 999, "match": { "always": true }, "action": "reject" }
      ]
    }
  }'
# اشتراك في مجموعة بيانات ذات وصول مقيَّد باستخدام المصادقة الأساسية
curl -X POST http://localhost:5002/subscriptions \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "cache/a/wis2/+/data/recommended/weather/surface-based-observations/#",
    "target": "restricted-obs",
    "credentials": { "type": "basic", "username": "myuser", "password": "s3cr3t" }
  }'
# توجيه التنزيلات الكبيرة إلى قائمة انتظار large-files
curl -X POST http://localhost:5002/subscriptions \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "cache/a/wis2/fr-meteofrance/data/core/weather/space-based-observations/noaa-21/cris",
    "target": "space-obs",
    "queue": "large_files"
  }'
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "topic": "cache/a/wis2/+/data/core/weather/surface-based-observations/#",
  "save_path": "surface-obs",
  "filter": {},
  "credentials": null,
  "queue": "small_files"
}

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

يُعيد السجل الكامل لاشتراك محدد.

GET /subscriptions/{id}

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

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

id

string (UUID)

UUID الاشتراك المُعاد عند إنشائه

3.3.2. الاستجابة

الحالة الوصف

200

نجاح

404

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

3.3.3. مثال

curl http://localhost:5002/subscriptions/550e8400-e29b-41d4-a716-446655440000
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "topic": "cache/a/wis2/+/data/core/weather/surface-based-observations/#",
  "save_path": "surface-obs",
  "filter": {},
  "credentials": null,
  "queue": "small_files"
}
لا تُعاد أسرار بيانات الاعتماد (password و`token`) أبدًا. تُضمَّن في الاستجابات type و`username` فقط (للمصادقة الأساسية).

3.4. تحديث اشتراك

يُحدِّث مسار الحفظ أو الفلتر أو بيانات الاعتماد أو قائمة الانتظار لاشتراك قائم. لا يمكن تغيير الموضوع — احذف الاشتراك وأعد إنشاءه لتغيير الموضوع.

PUT /subscriptions/{id}
Content-Type: application/json

3.4.1. جسم الطلب

جميع الحقول اختيارية. تُحدَّث الحقول المُقدَّمة فقط.

الحقل النوع الوصف

target

string

المجلد الفرعي الجديد تحت جذر البيانات

filter

كائن

الفلتر الجديد القائم على قواعد (يستبدل الفلتر الحالي)

credentials

كائن

بيانات الاعتماد الجديدة (تستبدل بيانات الاعتماد الحالية)

queue

string

قائمة الانتظار الجديدة: high_priority أو small_files أو large_files

3.4.2. الاستجابة

الحالة الوصف

200

سجل الاشتراك المُحدَّث

400

قيمة حقل غير صالحة

404

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

503

Redis غير متوفر

3.4.3. مثال

curl -X PUT http://localhost:5002/subscriptions/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -d '{ "target": "surface-obs-v2", "queue": "high_priority" }'

3.5. حذف اشتراك

يحذف اشتراكًا. إذا كان آخر اشتراك لموضوعه، يُغلَق اتصال MQTT لذلك الموضوع.

DELETE /subscriptions/{id}

3.5.1. الاستجابة

الحالة الوصف

200

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

404

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

503

Redis غير متوفر

3.5.2. مثال

curl -X DELETE http://localhost:5002/subscriptions/550e8400-e29b-41d4-a716-446655440000
{ "status": "deleted", "id": "550e8400-e29b-41d4-a716-446655440000" }

4. API المراقبة

4.1. فحص الصحة

GET /health

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

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

4.2. مقاييس Prometheus

يُعيد المقاييس بتنسيق نص Prometheus.

GET /metrics

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

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

wis2downloader_notifications_total

Counter

status

إجمالي الإشعارات المعالَجة بواسطة Celery

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.2. مثال

curl http://localhost:5002/metrics

4.3. مواصفة OpenAPI

GET /openapi

4.4. واجهة Swagger

وثائق API التفاعلية متاحة على:

GET /
GET /swagger

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

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

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

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

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

400

"No topic provided"

POST /subscriptions بدون حقل topic

400

"credentials.type must be 'basic' or 'bearer'"

نوع بيانات اعتماد غير صالح

400

"queue must be one of: high_priority, large_files, small_files"

اسم قائمة انتظار غير معروف

404

"Subscription '{id}' not found"

UUID غير موجود

503

"Failed to connect to Redis: …​"

Redis غير متوفر

503

"Failed to queue subscription command…​"

فشل Redis pub/sub

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

6.1. الاشتراك

سجل الاشتراك الكامل كما يُخزَّن ويُعاد بواسطة الـ API.

الحقل النوع الوصف

id

string (UUID)

معرِّف فريد يُعيَّن عند الإنشاء

topic

string

نمط موضوع MQTT لـ WIS2

save_path

string | null

المجلد الفرعي تحت جذر البيانات حيث تُحفظ الملفات

filter

كائن

فلتر قائم على قواعد (الكائن الفارغ {} يعني عدم الفلترة)

credentials

كائن | null

بيانات الاعتماد المستخدمة للتنزيل. تُخفى الأسرار في الاستجابات.

queue

string

قائمة انتظار التنزيل: high_priority أو small_files أو large_files

6.2. مخطط الفلتر

تستخدم الفلاتر قائمة مرتَّبة من القواعد. تُقيَّم القواعد بالترتيب؛ يُطبَّق إجراء أول قاعدة مطابقة. إذا لم تتطابق أي قاعدة، يُقبَل الملف.

الحقل النوع الوصف

name

string

اسم الفلتر للتعريف

rules

مصفوفة

قائمة مرتَّبة من قواعد الفلتر

6.2.1. مخطط قاعدة الفلتر

الحقل النوع الوصف

id

string

معرِّف القاعدة الفريد

order

integer

ترتيب التنفيذ — القيم الأصغر تُنفَّذ أولًا

match

كائن

الشرط للتحقق منه. راجع شروط التطابق.

action

string

accept أو reject أو continue

6.2.2. شروط التطابق

الشرط الوصف

media_type

التطابق على نوع MIME للملف

size

التطابق على حجم الملف بالبايت

centre_id

التطابق على معرِّف المركز المُصدِر (مثال: de-dwd، fr-meteofrance). الحقل الأول هو رمز البلد ISO2C، والثاني هو اسم وصفي للمركز.

data_id

التطابق على معرِّف بيانات WIS2

href

التطابق على عنوان URL التنزيل

always: true

تطابق غير مشروط (يُستخدم كقاعدة افتراضية شاملة)

عوامل السلسلة النصية: equals، not_equals، in، not_in، pattern (glob)، regex

عوامل الحجم/العددية: gt_bytes، lt_bytes، gte_bytes، lte_bytes، between_bytes

المجمِّعات المنطقية: all (AND)، any (OR)، not

6.2.3. مثال على الفلتر

قبول ملفات BUFR فقط بحجم أقل من 10 ميجابايت؛ رفض كل شيء آخر:

{
  "name": "bufr-small",
  "rules": [
    {
      "id": "accept-small-bufr",
      "order": 1,
      "match": {
        "all": [
          { "media_type": { "equals": "application/bufr" } },
          { "size": { "lt_bytes": 10485760 } }
        ]
      },
      "action": "accept"
    },
    {
      "id": "default-reject",
      "order": 999,
      "match": { "always": true },
      "action": "reject"
    }
  ]
}

6.3. مخطط بيانات الاعتماد

يُستخدم لمصادقة تنزيلات HTTP من مجموعات البيانات ذات الوصول المقيَّد.

password و`token` للكتابة فقط — تُقبَل في الطلبات لكنها لا تُعاد أبدًا في الاستجابات.
الحقل النوع الوصف

type

string

basic أو bearer

username

string

مطلوب عندما يكون type هو basic

password

string (كتابة فقط)

مطلوب عندما يكون type هو basic

token

string (كتابة فقط)

مطلوب عندما يكون type هو bearer

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

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

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

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

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

  • {centre-id} — معرِّف المركز. الحقل الأول هو رمز البلد ISO2C والثاني هو اسم وصفي للمركز (مثال: de-dwd لـ Deutscher Wetterdienst، fr-meteofrance لـ Météo-France)

  • {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/#

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