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

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

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

نظرة عامة
تكوين خادم HTTP
Swagger UI
نقاط نهاية API
المصادقة
تنسيقات الاستجابة
معالجة الأخطاء
المقاييس (بروميثيوس)
طلبات مثال

نظرة عامة

تقدم 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 أو عملاء API الآخرين
توليد مكتبات العملاء
أتمتة وثائق واجهة برمجة التطبيقات

نقاط نهاية API

تتبع جميع نقاط نهاية عمليات 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	إعادة توجيه SM إلى الهاتف المحمول	10s
`/api/forwardSM`	POST	إعادة توجيه SM	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`	String	نعم	MSISDN الطرف المتصل
`gmsc`	String	نعم	العنوان العالمي لمركز البوابة 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)

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

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

جسم الطلب:

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

المعلمات:

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

الاستجابة (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`	String	نعم	IMSI المشترك
`vectors`	Integer	نعم	عدد متجهات المصادقة التي يجب توليدها

الاستجابة (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

تسليم رسالة نصية قصيرة متوقفة إلى مشترك.

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

جسم الطلب:

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

المعلمات:

الحقل	النوع	مطلوب	الوصف
`imsi`	String	نعم	IMSI المشترك الوجهة
`destination_service_centre`	String	نعم	GT لمركز الخدمة الوجهة
`originating_service_center`	String	نعم	GT لمركز الخدمة المنشئ
`smsPDU`	String	نعم	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

إعادة توجيه رسالة نصية قصيرة (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`	String	نعم	IMSI المشترك
`vlr`	String	نعم	العنوان العالمي لـ 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`	String	نعم	MSISDN المشترك
`gmsc`	String	نعم	GT لمركز البوابة MSC
`msc_number`	String	نعم	رقم MSC للمشترك
`imsi`	String	نعم	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"
  }'

المصادقة

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

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

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

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

تستخدم جميع الاستجابات تنسيق 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 ثوانٍ:

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

استكشاف الأخطاء وإصلاح المهلات:

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

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

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

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

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

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

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

# HELP map_requests_total إجمالي طلبات MAP
# 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 إجمالي طلبات CAP
# TYPE cap_requests_total counter
cap_requests_total{operation="initialDP"} 87
cap_requests_total{operation="requestReportBCSMEvent"} 91

# HELP map_request_duration_milliseconds مدة طلبات/استجابات MAP بالمللي ثانية
# 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 عدد طلبات MAP المعلقة
# TYPE map_pending_requests gauge
map_pending_requests 3

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

المقياس	النوع	التسميات	الوصف
`map_requests_total`	Counter	`operation`	إجمالي عدد طلبات MAP حسب نوع العملية
`cap_requests_total`	Counter	`operation`	إجمالي عدد طلبات CAP حسب نوع العملية
`map_request_duration_milliseconds`	Histogram	`operation`	مدة الطلب بالمللي ثانية
`map_pending_requests`	Gauge	-	عدد معاملات 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

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

تدفق طلب API

ملخص

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

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

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

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

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

نظرة عامة​

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

تكوين خادم HTTP​

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

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

Swagger UI​

الوصول إلى Swagger UI​

Swagger JSON​

نقاط نهاية API​

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

SendRoutingInfo (SRI)​

SendRoutingInfoForSM (SRI-for-SM)​

SendAuthenticationInfo​

MT-ForwardSM​

ForwardSM​

UpdateLocation​

ProvideRoamingNumber (PRN)​

المصادقة​

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

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

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

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

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

سلوك المهلة​

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

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

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

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

طلبات مثال​

مثال بايثون​

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

مثال Bash/cURL​

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

تدفق طلب API​

ملخص​

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

نظرة عامة

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

تكوين خادم HTTP

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

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

Swagger UI

الوصول إلى Swagger UI

Swagger JSON

نقاط نهاية API

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

SendRoutingInfo (SRI)

SendRoutingInfoForSM (SRI-for-SM)

SendAuthenticationInfo

MT-ForwardSM

ForwardSM

UpdateLocation

ProvideRoamingNumber (PRN)

المصادقة

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

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

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

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

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

سلوك المهلة

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

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

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

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

طلبات مثال

مثال بايثون

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

مثال Bash/cURL

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

تدفق طلب API

ملخص