دليل واجهة برمجة التطبيقات REST

← العودة إلى الوثائق الرئيسية

يوفر هذا الدليل وثائق شاملة لواجهة برمجة التطبيقات REST API و Swagger UI الخاصة بـ OmniSS7.

جدول المحتويات

1. نظرة عامة
2. تكوين خادم HTTP
3. Swagger UI
4. نقاط نهاية واجهة برمجة التطبيقات
5. المصادقة
6. تنسيقات الاستجابة
7. معالجة الأخطاء
8. المقاييس (بروميثيوس)
9. طلبات مثال

---

نظرة عامة

يوفر OmniSS7 واجهة برمجة تطبيقات REST للوصول البرمجي إلى عمليات MAP (جزء تطبيق الهاتف المحمول). تتيح لك واجهة برمجة التطبيقات:

• إرسال طلبات MAP (SRI، SRI-for-SM، UpdateLocation، إلخ)
• استرجاع استجابات MAP
• مراقبة مقاييس النظام عبر بروميثيوس

بنية واجهة برمجة التطبيقات

---

تكوين خادم HTTP

تفاصيل الخادم

المعامل	القيمة	قابل للتكوين
البروتوكول	HTTP	لا
عنوان IP	0.0.0.0 (جميع الواجهات)	عبر الكود فقط
المنفذ	8080	عبر الكود فقط
النقل	Plug.Cowboy	لا

رابط الوصول: http://[server-ip]:8080

تمكين/تعطيل خادم HTTP

تحكم فيما إذا كان خادم HTTP سيبدأ:

config :omniss7,
  start_http_server: true  # تعيين إلى false لتعطيل

الإعداد الافتراضي: true (مفعل)

عند التعطيل: لن يبدأ خادم HTTP، وستكون واجهة برمجة التطبيقات REST/Swagger UI غير متاحة.

---

Swagger UI

تتضمن واجهة برمجة التطبيقات Swagger UI لوثائق واجهة برمجة التطبيقات التفاعلية والاختبار.

الوصول إلى Swagger UI

الرابط: http://[server-ip]:8080/swagger

الميزات:

• وثائق واجهة برمجة التطبيقات التفاعلية
• وظيفة جربها لاختبار نقاط النهاية
• مخططات الطلب/الاستجابة
• أحمال مثال

Swagger JSON

مواصفة OpenAPI متاحة على:

الرابط: http://[server-ip]:8080/swagger.json

حالات الاستخدام:

• الاستيراد إلى Postman أو عملاء واجهة برمجة التطبيقات الآخرين
• توليد مكتبات العملاء
• أتمتة وثائق واجهة برمجة التطبيقات

---

نقاط نهاية واجهة برمجة التطبيقات

تتبع جميع نقاط نهاية عمليات MAP النمط: POST /api/{operation}

ملخص نقاط النهاية

نقطة النهاية	الطريقة	الغرض	المهلة
/api/sri	POST	إرسال معلومات التوجيه	10s
/api/sri-for-sm	POST	إرسال معلومات التوجيه لـ SM	10s
/api/send-auth-info	POST	إرسال معلومات المصادقة	10s
/api/MT-forwardSM	POST	إعادة توجيه SMS إلى الهاتف المحمول	10s
/api/forwardSM	POST	إعادة توجيه SMS	10s
/api/updateLocation	POST	تحديث الموقع	10s
/api/prn	POST	توفير رقم التجوال	10s
/metrics	GET	مقاييس بروميثيوس	N/A
/swagger	GET	Swagger UI	N/A
/swagger.json	GET	مواصفة OpenAPI	N/A

ملاحظة: جميع طلبات MAP تحتوي على مهلة محددة مسبقًا مدتها 10 ثوانٍ.

---

SendRoutingInfo (SRI)

استرجاع معلومات التوجيه لإنشاء مكالمة لمشترك الهاتف المحمول.

نقطة النهاية: POST /api/sri

جسم الطلب:

{
  "msisdn": "1234567890",
  "gmsc": "5551234567"
}

المعلمات:

الحقل	النوع	مطلوب	الوصف
msisdn	سلسلة	نعم	MSISDN الطرف المتصل
gmsc	سلسلة	نعم	عنوان بوابة MSC العالمي

الاستجابة (200 OK):

{
  "result": {
    "imsi": "001001234567890",
    "msrn": "5551234999",
    "vlr_number": "5551234800",
    ...
  }
}

خطأ (504 Gateway Timeout):

{
  "error": "timeout"
}

مثال cURL:

curl -X POST http://localhost:8080/api/sri \
  -H "Content-Type: application/json" \
  -d '{
    "msisdn": "1234567890",
    "gmsc": "5551234567"
  }'

---

SendRoutingInfoForSM (SRI-for-SM)

استرجاع معلومات التوجيه لتسليم SMS لمشترك الهاتف المحمول.

نقطة النهاية: POST /api/sri-for-sm

جسم الطلب:

{
  "msisdn": "1234567890",
  "service_center": "5551234567"
}

المعلمات:

الحقل	النوع	مطلوب	الوصف
msisdn	سلسلة	نعم	MSISDN الوجهة
service_center	سلسلة	نعم	عنوان مركز الخدمة العالمي

الاستجابة (200 OK):

{
  "result": {
    "imsi": "001001234567890",
    "msc_number": "5551234800",
    "location_info": {...},
    ...
  }
}

مثال cURL:

curl -X POST http://localhost:8080/api/sri-for-sm \
  -H "Content-Type: application/json" \
  -d '{
    "msisdn": "1234567890",
    "service_center": "5551234567"
  }'

---

SendAuthenticationInfo

طلب متجهات المصادقة لمشترك.

نقطة النهاية: POST /api/send-auth-info

جسم الطلب:

{
  "imsi": "001001234567890",
  "vectors": 3
}

المعلمات:

الحقل	النوع	مطلوب	الوصف
imsi	سلسلة	نعم	IMSI المشترك
vectors	عدد صحيح	نعم	عدد متجهات المصادقة لتوليدها

الاستجابة (200 OK):

{
  "result": {
    "authentication_sets": [
      {
        "rand": "0123456789ABCDEF...",
        "xres": "...",
        "ck": "...",
        "ik": "...",
        "autn": "..."
      }
    ],
    ...
  }
}

مثال cURL:

curl -X POST http://localhost:8080/api/send-auth-info \
  -H "Content-Type: application/json" \
  -d '{
    "imsi": "001001234567890",
    "vectors": 3
  }'

---

MT-ForwardSM

تسليم SMS إلى مشترك.

نقطة النهاية: POST /api/MT-forwardSM

جسم الطلب:

{
  "imsi": "001001234567890",
  "destination_service_centre": "5551234567",
  "originating_service_center": "5551234568",
  "smsPDU": "0001000A8121436587F900001C48656C6C6F20576F726C64"
}

المعلمات:

الحقل	النوع	مطلوب	الوصف
imsi	سلسلة	نعم	IMSI المشترك الوجهة
destination_service_centre	سلسلة	نعم	GT لمركز الخدمة الوجهة
originating_service_center	سلسلة	نعم	GT لمركز الخدمة المنشئ
smsPDU	سلسلة	نعم	SMS TPDU بتنسيق سداسي عشري

ملاحظة: يجب أن يكون smsPDU سلسلة مشفرة بتنسيق سداسي عشري (كبيرة أو صغيرة).

الاستجابة (200 OK):

{
  "result": {
    "delivery_status": "success",
    ...
  }
}

مثال cURL:

curl -X POST http://localhost:8080/api/MT-forwardSM \
  -H "Content-Type: application/json" \
  -d '{
    "imsi": "001001234567890",
    "destination_service_centre": "5551234567",
    "originating_service_center": "5551234568",
    "smsPDU": "0001000A8121436587F900001C48656C6C6F20576F726C64"
  }'

---

ForwardSM

إعادة توجيه رسالة SMS (MO-SMS من المشترك).

نقطة النهاية: POST /api/forwardSM

جسم الطلب: نفس MT-ForwardSM

مثال cURL:

curl -X POST http://localhost:8080/api/forwardSM \
  -H "Content-Type: application/json" \
  -d '{
    "imsi": "001001234567890",
    "destination_service_centre": "5551234567",
    "originating_service_center": "5551234568",
    "smsPDU": "0001000A8121436587F900001C48656C6C6F20576F726C64"
  }'

---

UpdateLocation

إخطار HLR بتغيير موقع المشترك (تسجيل VLR).

نقطة النهاية: POST /api/updateLocation

جسم الطلب:

{
  "imsi": "001001234567890",
  "vlr": "5551234800"
}

المعلمات:

الحقل	النوع	مطلوب	الوصف
imsi	سلسلة	نعم	IMSI المشترك
vlr	سلسلة	نعم	عنوان VLR العالمي

الاستجابة (200 OK):

{
  "result": {
    "hlr_number": "5551234567",
    "subscriber_data": {...},
    ...
  }
}

ملاحظة: في وضع HLR، يؤدي هذا إلى بدء تسلسل InsertSubscriberData (ISD) مع مهلة مدتها 10 ثوانٍ لكل ISD.

مثال cURL:

curl -X POST http://localhost:8080/api/updateLocation \
  -H "Content-Type: application/json" \
  -d '{
    "imsi": "001001234567890",
    "vlr": "5551234800"
  }'

---

ProvideRoamingNumber (PRN)

طلب MSRN (رقم التجوال لمحطة الهاتف المحمول) لتوجيه المكالمات إلى المشترك المتجول.

نقطة النهاية: POST /api/prn

جسم الطلب:

{
  "msisdn": "1234567890",
  "gmsc": "5551234567",
  "msc_number": "5551234800",
  "imsi": "001001234567890"
}

المعلمات:

الحقل	النوع	مطلوب	الوصف
msisdn	سلسلة	نعم	MSISDN المشترك
gmsc	سلسلة	نعم	GT لبوابة MSC
msc_number	سلسلة	نعم	رقم MSC للمشترك
imsi	سلسلة	نعم	IMSI المشترك

الاستجابة (200 OK):

{
  "result": {
    "msrn": "5551234999",
    ...
  }
}

مثال cURL:

curl -X POST http://localhost:8080/api/prn \
  -H "Content-Type: application/json" \
  -d '{
    "msisdn": "1234567890",
    "gmsc": "5551234567",
    "msc_number": "5551234800",
    "imsi": "001001234567890"
  }'

---

المصادقة

الحالة الحالية: لا تتطلب واجهة برمجة التطبيقات المصادقة.

اعتبارات الأمان:

• واجهة برمجة التطبيقات مخصصة للاستخدام في الشبكات الداخلية/الموثوقة
• ضع في اعتبارك استخدام قواعد جدار الحماية لتقييد الوصول
• بالنسبة لنشر الإنتاج، ضع في اعتبارك تنفيذ وسيط المصادقة

---

تنسيقات الاستجابة

تستخدم جميع الاستجابات تنسيق JSON.

استجابة النجاح

حالة HTTP: 200 OK

الهيكل:

{
  "result": {
    // بيانات الاستجابة الخاصة بالعملية
  }
}

استجابة الخطأ

حالة HTTP:

• 400 Bad Request - جسم الطلب غير صالح
• 504 Gateway Timeout - انتهاء مهلة طلب MAP (10 ثوانٍ)
• 404 Not Found - نقطة نهاية غير صالحة

الهيكل:

{
  "error": "timeout"
}

أو

{
  "error": "invalid request"
}

---

معالجة الأخطاء

الأخطاء الشائعة

الخطأ	رمز HTTP	الوصف	الحل
JSON غير صالح	400	جسم الطلب ليس JSON صالحًا	تحقق من بناء جملة JSON
الحقول المفقودة	400	الحقول المطلوبة مفقودة	قم بتضمين جميع المعلمات المطلوبة
انتهاء المهلة	504	تجاوز طلب MAP المهلة المحددة 10 ثوا��ٍ	تحقق من اتصال M3UA، وتوفر HLR/VLR
غير موجود	404	نقطة نهاية غير صالحة	تحقق من عنوان URL لنقطة النهاية

سلوك انتهاء المهلة

تحتوي جميع طلبات MAP على مهلة محددة مسبقًا مدتها 10 ثوانٍ:

1. يتم إرسال الطلب إلى MapClient GenServer
2. ينتظر الاستجابة لمدة تصل إلى 10 ثوانٍ
3. إذا لم يتم تلقي استجابة → يتم إرجاع 504 Gateway Timeout
4. إذا تم تلقي استجابة → يتم إرجاع 200 OK مع النتيجة

استكشاف أخطاء انتهاء المهلة:

• تحقق من حالة اتصال M3UA (واجهة الويب → صفحة M3UA)
• تحقق من أن العنصر الشبكي (HLR/VLR/MSC) يمكن الوصول إليه
• تحقق من تكوين التوجيه
• راجع سجلات أحداث SS7 للبحث عن الأخطاء

---

المقاييس (بروميثيوس)

تقوم واجهة برمجة التطبيقات بتعريض مقاييس بروميثيوس للمراقبة.

نقطة نهاية المقاييس

الرابط: http://[server-ip]:8080/metrics

التنسيق: تنسيق نص بروميثيوس

مثال على المخرجات:

# HELP map_requests_total Total MAP requests
# TYPE map_requests_total counter
map_requests_total{operation="sri"} 42
map_requests_total{operation="sri_for_sm"} 158
map_requests_total{operation="updateLocation"} 23

# HELP cap_requests_total Total CAP requests
# TYPE cap_requests_total counter
cap_requests_total{operation="initialDP"} 87
cap_requests_total{operation="requestReportBCSMEvent"} 91

# HELP map_request_duration_milliseconds Duration of MAP request/responses in ms
# TYPE map_request_duration_milliseconds histogram
map_request_duration_milliseconds_bucket{operation="sri",le="10"} 5
map_request_duration_milliseconds_bucket{operation="sri",le="50"} 12
map_request_duration_milliseconds_bucket{operation="sri",le="100"} 35
...

# HELP map_pending_requests Number of pending MAP TID waiters
# TYPE map_pending_requests gauge
map_pending_requests 3

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

المقياس	النوع	التسميات	الوصف
map_requests_total	عداد	operation	إجمالي عدد طلبات MAP حسب نوع العملية
cap_requests_total	عداد	operation	إجمالي عدد طلبات CAP حسب نوع العملية
map_request_duration_milliseconds	هيستوجرام	operation	مدة ��لطلب بالمللي ثانية
map_pending_requests	مقياس	-	عدد معاملات MAP المعلقة

تكوين بروميثيوس

أضف إلى prometheus.yml الخاص بك:

scrape_configs:
  - job_name: 'omniss7'
    static_configs:
      - targets: ['server-ip:8080']
    metrics_path: '/metrics'
    scrape_interval: 15s

---

طلبات مثال

مثال بايثون

import requests
import json

# طلب SRI-for-SM
url = "http://localhost:8080/api/sri-for-sm"
payload = {
    "msisdn": "1234567890",
    "service_center": "5551234567"
}

response = requests.post(url, json=payload, timeout=15)

if response.status_code == 200:
    result = response.json()
    print(f"نجاح: {result}")
elif response.status_code == 504:
    print("انتهاء المهلة - لا استجابة من الشبكة")
else:
    print(f"خطأ: {response.status_code} - {response.text}")

مثال جافا سكريبت

const axios = require('axios');

async function sendSRI() {
  try {
    const response = await axios.post('http://localhost:8080/api/sri', {
      msisdn: '1234567890',
      gmsc: '5551234567'
    }, {
      timeout: 15000
    });

    console.log('نجاح:', response.data);
  } catch (error) {
    if (error.code === 'ECONNABORTED') {
      console.error('انتهاء المهلة - لا استجابة من الشبكة');
    } else {
      console.error('خطأ:', error.response?.data || error.message);
    }
  }
}

sendSRI();

مثال Bash/cURL

#!/bin/bash

# طلب UpdateLocation
response=$(curl -s -w "\n%{http_code}" -X POST http://localhost:8080/api/updateLocation \
  -H "Content-Type: application/json" \
  -d '{
    "imsi": "001001234567890",
    "vlr": "5551234800"
  }')

http_code=$(echo "$response" | tail -n 1)
body=$(echo "$response" | sed '$d')

if [ "$http_code" -eq 200 ]; then
  echo "نجاح: $body"
elif [ "$http_code" -eq 504 ]; then
  echo "انتهاء المهلة - لا استجابة من الشبكة"
else
  echo "خطأ $http_code: $body"
fi

---

مخططات التدفق

تدفق طلب واجهة برمجة التطبيقات

---

الملخص

توفر واجهة برمجة التطبيقات REST API الخاصة بـ OmniSS7:

✅ عمليات MAP - دعم كامل لـ SRI، SRI-for-SM، UpdateLocation، تسليم SMS، المصادقة
✅ Swagger UI - وثائق واجهة برمجة التطبيقات التفاعلية والاختبار
✅ مقاييس بروميثيوس - المراقبة والرؤية
✅ مهلات محددة مسبقًا - مهلة مدتها 10 ثوانٍ لجميع طلبات MAP
✅ خادم HTTP - يعمل على المنفذ 8080 (قابل للتكوين عبر start_http_server)

للوصول إلى واجهة الويب، راجع دليل واجهة الويب.

للحصول على تفاصيل التكوين، راجع مرجع التكوين.