انتقل إلى المحتوى الرئيسي

مرجع واجهة برمجة تطبيقات OmniHSS

← العودة إلى دليل العمليات

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

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

عنوان URL الأساسي​

https://[hostname]:8443/api

تنسيق الطلب​

  • Content-Type: application/json
  • Protocol: HTTPS فقط
  • Port: 8443 (قابل للتكوين)

مهم: ت��وقع جميع نقاط نهاية واجهة برمجة التطبيقات "حمولات" JSON "مسطحة" بدون كائنات تغليف.

التنسيق الصحيح:

{
  "name": "value",
  "field": "value"
}

التنسيق غير الصحيح (لا تستخدمه):

{
  "subscriber": {
    "name": "value",
    "field": "value"
  }
}

مثال:

# ✓ صحيح
curl -X POST https://hss.example.com:8443/api/ims/profile \
  -H "Content-Type: application/json" \
  -d '{"name": "default", "ifc_template": "..."}'

# ✗ غير صحيح
curl -X POST https://hss.example.com:8443/api/ims/profile \
  -H "Content-Type: application/json" \
  -d '{"ims_profile": {"name": "default", "ifc_template": "..."}}'

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

جميع الاستجابات هي JSON بالهيكل التالي:

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

{
  "status": "success",
  "response": { ... }
}

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

{
  "status": "error",
  "response": {
    "invalid_fields": {
      "field_name": "error message"
    }
  }
}

رموز حالة HTTP​

الرمزالمعنىحالة الاستخدام
200OKGET, PUT, DELETE ناجح
201تم الإنشاءPOST ناجح
400طلب غير صحيحبيانات إدخال غير صالحة
404غير موجودالمورد غير موجود
422كيان غير قابل للمعالجةخطأ في التحقق
500خطأ في الخادم الداخليخطأ من جانب الخادم

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

إدارة المشتركين​

قائمة المشتركين​

استرجاع جميع المشتركين أو تصفية حسب المعايير.

نقطة النهاية: GET /api/subscriber

معلمات الاستعلام:

المعلمةالنوعالوصف
enabledbooleanتصفية حسب حالة التمكين
ims_enabledbooleanتصفية حسب حالة تم��ين IMS

مثال على الطلب:

curl -k https://hss.example.com:8443/api/subscriber

مثال على الاستجابة:

{
  "data": [
    {
      "id": 1,
      "imsi": "001001123456789",
      "enabled": true,
      "ims_enabled": true,
      "sim_id": 1,
      "key_set_id": 1,
      "epc_profile_id": 1,
      "ims_profile_id": 1,
      "roaming_profile_id": 1,
      "custom_attributes": {},
      "inserted_at": "2025-10-15T10:30:00Z",
      "updated_at": "2025-10-15T10:30:00Z"
    }
  ]
}

الحصول على مشترك بواسطة ID​

استرجاع مشترك محدد بواسطة ID من قاعدة البيانات.

نقطة النهاية: GET /api/subscriber/:id

معلمات المسار:

المعلمةالنوعالوصف
idintegerID مشترك قاعدة البيانات

مثال على الطلب:

curl -k https://hss.example.com:8443/api/subscriber/1

الحصول على مشترك بواسطة IMSI​

استرجاع مشترك بواسطة IMSI الخاص به.

نقطة النهاية: GET /api/subscriber/imsi/:imsi

معلمات المسار:

المعلمةالنوعالوصفالتنسيق
imsistringهوية المشترك الدولي للهاتف المحمول14-15 رقم

مثال على الطلب:

curl -k https://hss.example.com:8443/api/subscriber/imsi/001001123456789

حالة الاستخدام: استكشاف مشكلة مشترك محدد بواسطة IMSI الخاص به.

الحصول على مشترك بواسطة MSISDN​

استرجاع مشترك بواسطة رقم هاتفه.

نقطة النهاية: GET /api/subscriber/msisdn/:msisdn

معلمات المسار:

المعلمةالنوعالوصفالتنسيق
msisdnstringرقم ISDN لمحطة الهاتف المحمول1-15 رقم (E.164)

مثال على الطلب:

curl -k https://hss.example.com:8443/api/subscriber/msisdn/14155551234

حالة الاستخدام: البحث عن معلومات المشترك عندما يكون لديك رقم هاتفه فقط.

إنشاء مشترك​

توفير مشترك جديد.

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

جسم الطلب:

{
  "subscriber": {
    "imsi": "001001123456789",
    "enabled": true,
    "ims_enabled": true,
    "sim_id": 1,
    "key_set_id": 1,
    "epc_profile_id": 1,
    "ims_profile_id": 1,
    "roaming_profile_id": 1,
    "custom_attributes": {
      "note": "مشترك تجريبي"
    }
  }
}

الحقول المطلوبة:

  • imsi - يجب أن يكون 14-15 رقم، فريد
  • key_set_id - يجب أن يشير إلى مجموعة المفاتيح الموجودة
  • epc_profile_id - يجب أن يشير إلى ملف EPC الموجود

الحقول الاختيارية:

  • enabled - الافتراضي: true
  • ims_enabled - الافتراضي: true
  • sim_id - مرجع إلى بطاقة SIM
  • ims_profile_id - مرجع إلى ملف IMS (مطلوب لخدمات IMS)
  • roaming_profile_id - مرجع إلى ملف التجوال (مطلوب للتحكم في التجوال)
  • msisdns - مصفوفة من معرفات MSISDN (أرقام الهواتف)
  • static_ips - مصفوفة من معرفات IP الثابت لتعيينات APN
  • custom_attributes - أزواج مفتاح-قيمة مخصصة

انظر أيضًا:

مثال على الطلب:

curl -k -X POST https://hss.example.com:8443/api/subscriber \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "imsi": "001001123456789",
      "key_set_id": 1,
      "epc_profile_id": 1
    }
  }'

تدفق التوفير:

تحديث المشترك​

تعديل مشترك موجود.

نقطة النهاية: PUT /api/subscriber/:id

معلمات المسار:

المعلمةالنوعالوصف
idintegerID مشترك قاعدة البيانات

جسم الطلب:

{
  "subscriber": {
    "enabled": false,
    "ims_enabled": false,
    "epc_profile_id": 2,
    "custom_attributes": {
      "note": "معطل مؤقتًا"
    }
  }
}

الحقول القابلة للتحديث:

غير القابلة للتحديث:

  • imsi - لا يمكن تغيير IMSI (احذف وأعد الإنشاء بدلاً من ذلك)

انظر أيضًا:

مثال على الطلب:

curl -k -X PUT https://hss.example.com:8443/api/subscriber/1 \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "enabled": false
    }
  }'

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

  • تعطيل المشترك مؤقتًا: {"enabled": false}
  • تعطيل خدمات الصوت فقط: {"ims_enabled": false}
  • تغيير ملف الخدمة: {"epc_profile_id": 2} (انظر ملفات EPC)
  • تحديث سياسة التجوال: {"roaming_profile_id": 3} (انظر إدارة التجوال)

حذف المشترك​

إزالة مشترك من النظام.

نقطة النهاية: DELETE /api/subscriber/:id

معلمات المسار:

المعلمةالنوعالوصف
idintegerID مشترك قاعدة البيانات

مثال على الطلب:

curl -k -X DELETE https://hss.example.com:8443/api/subscriber/1

تحذير: هذا يحذف المشترك بشكل دائم وجميع بيانات الحالة المرتبطة (جلسات PDN، المكالمات، إلخ). يمكن إعادة استخدام IMSI بعد الحذف.

ملاحظة: حذف مشترك لا يحذف:

  • مجموعة المفاتيح - يمكن إعادة استخدامها لمشتركين آخرين
  • SIM - يمكن إعادة تعيينها لمشترك جديد
  • الملفات الشخصية - موارد مشتركة تستخدم من قبل عدة مشتركين
  • MSISDNs - يجب حذفها بشكل منفصل إذا رغبت في ذلك

إلغاء طلب الموقع (فصل قسري)​

إرسال طلب إلغاء الموقع (CLR) لفصل مشترك من MME المسجل حاليًا.

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

جسم الطلب:

{
  "imsi": "001001123456789"
}

المعلمات:

المعلمةالنوعمطلوبالوصف
imsistringنعمIMSI للمشترك الذي سيتم فصله (14-15 رقم)

مثال على الطلب:

curl -k -X POST https://hss.example.com:8443/api/subscriber/cancel_location \
  -H "Content-Type: application/json" \
  -d '{"imsi": "001001123456789"}'

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

{
  "data": {
    "message": "تم إرسال طلب إلغاء الموقع بنجاح",
    "imsi": "001001123456789",
    "destination_host": "mme01.operator.com",
    "destination_realm": "epc.operator.com"
  }
}

استجابة الخطأ (404 غير موجود):

{
  "error": "المشترك غير موجود أو غير مسجل حاليًا في أي MME"
}

السلوك:

  • يرسل CLR S6a إلى MME حيث المشترك مسجل حاليًا (subscriber_state.last_seen_mme)
  • يستخدم Cancellation-Type: subscription_withdrawal (يفصل بالكامل)
  • يحدد CLR-Flags: {s6a_indicator: 1, reattach_required: 1} (يجب على UE إعادة المصادقة)
  • يرجع 404 إذا لم يسجل المشترك أبدًا أو إذا كانت last_seen_mme فارغة
  • يؤثر على جميع MSISDNs المرتبطة بـ IMSI (نفس الجهاز/بطاقة SIM)

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

  • منع الاحتيال: فصل المشترك المشبوه على الفور
  • إنهاء الاشتراك: فرض تسجيل الخروج عند تعطيل الحساب
  • استكشاف الأخطاء: مسح تسجيل MME القديم لأغراض التصحيح
  • الهجرة: فرض إعادة المصادقة لتطبيق إعدادات الملف الشخصي الجديدة
  • الأمان: فصل المشترك المخترق على الفور

اعتبارات متعددة IMSI:

عند استخدام CLR مع سيناريوهات متعددة MSISDN:

  1. عدة MSISDNs، IMSI واحد:

    // المشترك لديه IMSI 001001123456789 مع MSISDNs ["+1234567890", "+9876543210"]
    POST /api/subscriber/cancel_location
    {"imsi": "001001123456789"}

    // النتيجة: تم إرسال CLR واحد، كلا MSISDNs تأثرت (نفس الجهاز)

  2. IMSI مختلفة (أجهزة مختلفة):

    // مشتركين اثنين بنفس MSISDN ولكن IMSIs مختلفة (سيناريو نقل الرقم)
    // المشترك A: IMSI 001001111111111، MSISDN "+1234567890"
    // المشترك B: IMSI 001001222222222، MSISDN "+1234567890"

    POST /api/subscriber/cancel_location
    {"imsi": "001001111111111"}

    // النتيجة: تم فصل المشترك A فقط، المشترك B لم يتأثر

ملاحظات مهمة:

  • مبني على IMSI: يتم دائمًا إرسال CLR لكل IMSI، وليس لكل MSISDN
  • غير متزامن: يتم إرسال CLR بشكل غير متزامن؛ تعني استجابة النجاح أنه تم إرسال CLR، وليس أنه تمت معالجته من قبل MME
  • لا تحقق من حالة MME: يتم إرسال CLR حتى لو كان MME غير متاح (سلوك قياسي لـ HSS)
  • آمن: من الآمن استدعاء عدة مرات لنفس IMSI

وثائق ذات صلة:

إدارة MSISDN​

يمكن تعيين MSISDNs (أرقام الهواتف) للمشتركين لتمكين خدمات الصوت. انظر وثائق متعددة MSISDN للحصول على تفاصيل حول تعيين أرقام متعددة لمشترك واحد.

قائمة MSISDNs​

استرجاع جميع أرقام الهواتف.

نقطة النهاية: GET /api/msisdn

مثال على الطلب:

curl -k https://hss.example.com:8443/api/msisdn

الحصول على MSISDN​

استرجاع رقم هاتف محدد.

نقطة النهاية: GET /api/msisdn/:id

مثال على الطلب:

curl -k https://hss.example.com:8443/api/msisdn/1

إنشاء MSISDN​

إنشاء رقم هاتف جديد.

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

جسم الطلب:

{
  "msisdn": {
    "msisdn": "14155551234"
  }
}

التحقق:

  • يجب أن يكون 1-15 رقم
  • يجب أن يكون فريدًا
  • يجب أن يتبع تنسيق E.164 (التنسيق الدولي بدون علامة +)

مثال على الطلب:

curl -k -X POST https://hss.example.com:8443/api/msisdn \
  -H "Content-Type: application/json" \
  -d '{
    "msisdn": {
      "msisdn": "14155551234"
    }
  }'

تعيين MSISDN لمشترك​

لتعيين رقم هاتف لمشترك، تحتاج إلى إنشاء سجل ارتباط. يتم ذلك عادةً من خلال نقطة نهاية تحديث المشترك أو عبر التلاعب المباشر بقاعدة البيانات.

نمط متعدد MSISDN:

انظ�� ميزات متعددة MSISDN و IMSI للاستخدام التفصيلي.

حذف MSISDN​

إزالة رقم هاتف.

نقطة النهاية: DELETE /api/msisdn/:id

مثال على الطلب:

curl -k -X DELETE https://hss.example.com:8443/api/msisdn/1

إدارة SIM​

تخزن سجلات بطاقة SIM معلومات بطاقة SIM الفعلية بما في ذلك ICCID، تفاصيل البائع، رموز PIN/PUK، ومفاتيح OTA. يمكن ربط سجلات SIM اختيارياً بـ المشتركين.

انظر أيضًا:

قائمة SIMs​

استرجاع جميع بطاقات SIM.

نقطة النهاية: GET /api/sim

مثال على الطلب:

curl -k https://hss.example.com:8443/api/sim

الحصول على SIM​

استرجاع بطاقة SIM محددة.

نقطة النهاية: GET /api/sim/:id

مثال على الطلب:

curl -k https://hss.example.com:8443/api/sim/1

إنشاء SIM​

إنشاء سجل بطاقة SIM جديدة.

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

جسم الطلب:

{
  "sim": {
    "iccid": "8991101200003204510",
    "sim_vendor": "Gemalto",
    "batch_name": "2025-Q1-Batch-01",
    "is_esim": false,
    "pin1": "1234",
    "pin2": "5678",
    "puk1": "12345678",
    "puk2": "87654321",
    "adm1": "admin-code-1",
    "kic": "0123456789ABCDEF0123456789ABCDEF",
    "kid": "FEDCBA9876543210FEDCBA9876543210"
  }
}

الحقول المطلوبة:

  • iccid - 19-20 رقم، فريد

الحقول الاختيارية ولكن المهمة:

  • sim_vendor - اسم الشركة المصنعة
  • batch_name - للتتبع
  • is_esim - علامة بوليانية لـ eSIM
  • pin1, pin2 - رموز PIN للمستخدم النهائي
  • puk1, puk2 - رموز فتح PIN
  • adm1-adm10 - رموز إدارية
  • kic, kid - مفاتيح أمان OTA (سلسلة سداسية)

مثال على الطلب:

curl -k -X POST https://hss.example.com:8443/api/sim \
  -H "Content-Type: application/json" \
  -d '{
    "sim": {
      "iccid": "8991101200003204510",
      "sim_vendor": "Gemalto"
    }
  }'

تحديث SIM​

تعديل بيانات بطاقة SIM.

نقطة النهاية: PUT /api/sim/:id

مثال على الطلب:

curl -k -X PUT https://hss.example.com:8443/api/sim/1 \
  -H "Content-Type: application/json" \
  -d '{
    "sim": {
      "batch_name": "اسم الدفعة المحدثة"
    }
  }'

حذف SIM​

إزالة سجل بطاقة SIM.

نقطة النهاية: DELETE /api/sim/:id

تحذير: تأكد من عدم وجود مشتركين يشيرون إلى هذه SIM قبل الحذف.

إدارة مجموعة المفاتيح​

تحتوي مجموعات المفاتيح على المواد التشفيرية (Ki، OPC/OP، AMF، SQN) المستخدمة لمصادقة المشتركين عبر خوارزمية Milenage. يجب أن تشير كل مشترك إلى مجموعة مفاتيح.

انظر أيضًا:

قائمة مجموعات المفاتيح​

استرجاع جميع مجموعات المفاتيح التشفيرية.

نقطة النهاية: GET /api/key_set

مثال على الطلب:

curl -k https://hss.example.com:8443/api/key_set

الحصول على مجموعة المفاتيح​

استرجاع مجموعة مفاتيح محددة.

نقطة النهاية: GET /api/key_set/:id

مثال على الطلب:

curl -k https://hss.example.com:8443/api/key_set/1

مثال على الاستجابة:

{
  "data": {
    "id": 1,
    "ki": "0123456789ABCDEF0123456789ABCDEF",
    "opc": "FEDCBA9876543210FEDCBA9876543210",
    "op": null,
    "amf": "8000",
    "sqn": 0,
    "authentication_algorithm": "milenage",
    "ota_counter": 0
  }
}

إنشاء مجموعة مفاتيح​

إنشاء مجموعة مفاتيح تشفيرية جديدة.

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

جسم الطلب:

{
  "key_set": {
    "ki": "0123456789ABCDEF0123456789ABCDEF",
    "opc": "FEDCBA9876543210FEDCBA9876543210",
    "amf": "8000",
    "sqn": 0,
    "authentication_algorithm": "milenage"
  }
}

الحقول المطلوبة:

  • ki - مفتاح 128 بت (32 حرف سداسي)
  • إما opc أو op (يمكن اشتقاق OPC من OP)
  • authentication_algorithm - حاليًا فقط "milenage"

الحقول الاختيارية:

  • amf - الافتراضي: "8000"
  • sqn - الافتراضي: 0
  • ota_counter - الافتراضي: 0

تنسيق المفتاح:

  • جميع المفاتيح هي سلاسل سداسية
  • Ki، OPC، OP: 32 حرف سداسي (128 بت)
  • AMF: 4 أحرف سداسية (16 بت)

مثال على الطلب:

curl -k -X POST https://hss.example.com:8443/api/key_set \
  -H "Content-Type: application/json" \
  -d '{
    "key_set": {
      "ki": "0123456789ABCDEF0123456789ABCDEF",
      "opc": "FEDCBA9876543210FEDCBA9876543210",
      "authentication_algorithm": "milenage"
    }
  }'

تحذير أمني: تحتوي مجموعات المفاتيح على مواد تشفير حساسة للغاية. احمِ الوصول إلى واجهة برمجة التطبيقات وفقًا لذلك.

تحديث مجموعة المفاتيح​

تعديل مجموعة مفاتيح موجودة.

نقطة النهاية: PUT /api/key_set/:id

تحذير: تغيير المفاتيح لمشترك نشط سيؤدي إلى فشل المصادقة. قم بتحديث المفاتيح فقط خلال نوافذ الصيانة أو للمشتركين الجدد.

التأثير: تؤثر التحديثات على جميع المشتركين الذين يستخدمون مجموعة المفاتيح هذه على الفور. سيفشل المشتركون النشطون في المصادقة في محاولة الاتصال التالية.

حذف مجموعة المفاتيح​

إز��لة مجموعة مفاتيح.

نقطة النهاية: DELETE /api/key_set/:id

تحذير: تأكد من عدم وجود مشتركين يشيرون إلى مجموعة المفاتيح هذه قبل الحذف. استعلام المشتركين أولاً للتحقق من المراجع.

إدارة الملف الشخصي​

ملفات EPC​

تحدد ملفات EPC (النواة المتطورة) معلمات خدمة البيانات للمشتركين. يتم الإشارة إلى هذه الملفات عند إنشاء المشتركين.

قائمة ملفات EPC​

نقطة النهاية: GET /api/epc/profile

الحصول على ملف EPC​

نقطة النهاية: GET /api/epc/profile/:id

إنشاء ملف EPC​

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

جسم الطلب:

{
  "apn_profiles": [],
  "name": "خطة بيانات قياسية",
  "network_access_mode": "packet_only",
  "tracking_area_update_interval_seconds": 600,
  "ue_ambr_dl_kbps": 100000,
  "ue_ambr_ul_kbps": 50000
}

الحقول:

الحقلالوصفالوحداتالقيم النموذجية
nameاسم المل�� الشخصينصمعرف فريد
ue_ambr_dl_kbpsحد عرض النطاق الترددي للتنزيلKbps10000-1000000
ue_ambr_ul_kbpsحد عرض النطاق الترددي للرفعKbps5000-500000
network_access_modeنوع الوصولسلسلة"packet_only" أو "packet_and_circuit"
tracking_area_update_interval_secondsمؤقت TAUثواني600 (نموذجي)
apn_profilesقائمة معرفات ملفات APNمصفوفة[] أو [1, 2, 3]

مثال على الطلب:

curl -k -X POST https://hss.example.com:8443/api/epc/profile \
  -H "Content-Type: application/json" \
  -d '{
    "apn_profiles": [],
    "name": "Premium 100Mbps",
    "network_access_mode": "packet_only",
    "tracking_area_update_interval_seconds": 600,
    "ue_ambr_dl_kbps": 100000,
    "ue_ambr_ul_kbps": 50000
  }'

انظر أيضًا:

تحديث ملف EPC​

نقطة النهاية: PUT /api/epc/profile/:id

ملاحظة: تؤثر التغييرات على ملفات EPC على جميع المشتركين الذين يستخدمون هذا الملف. قد تحتاج الجلسات النشطة إلى إعادة إنشائها.

حذف ملف EPC​

نقطة النهاية: DELETE /api/epc/profile/:id

تحذير: تأكد من عدم وجود مشتركين يشيرون إلى هذا الملف قبل الحذف.

ملفات IMS​

تحدد ملفات IMS (نظام الوسائط المتعددة IP) معلمات خدمة الصوت ومعايير التصفية الأولية (IFC) للمشتركين. يتم الإشارة إلى هذه الملفات عند إنشاء المشتركين مع تمكين خدمات IMS.

قائمة ملفات IMS​

نقطة النهاية: GET /api/ims/profile

إنشاء ملف IMS​

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

جسم الطلب:

{
  "name": "VoLTE القياسية",
  "ifc_template": "<IMS-XML-Template-Here>"
}

الحقول المطلوبة:

  • name - اسم الملف الشخصي (يجب أن يكون فريدًا)
  • ifc_template - قالب IFC (معايير التصفية الأولية) XML مع متغيرات قالب Liquid

متغيرات قالب IFC:

يدعم قالب IFC المتغيرات التالية التي يتم استبدالها ديناميكيًا:

المتغيرالوصفقيمة المثال
{{ imsi }}IMSI للمشترك001001123456789
{{ msisdns }}مصفوفة من MSISDNs (للحلقات)["14155551234", "14155555678"]
{{ mcc }}رمز الدولة المحمول001
{{ mnc }}رمز الشبكة المحمولة001

كيف يعمل تقديم القالب:

يتم تخزين قالب IFC كقالب Liquid (مشابه لـ Jinja2) ويتم تقديمه ديناميكيًا أثناء عمليات IMS:

  1. التخزين: عند إنشاء ملف IMS، يتم تخزين القالب كما هو مع المتغيرات مثل {{ imsi }} و{% for msisdn in msisdns %}
  2. التحقق: تتحقق واجهة برمجة التطبيقات من صحة القالب من خلال تقديمه مع بيانات اختبار لضمان صحة بناء XML
  3. تقديم وقت التشغيل: عندما يقوم مشترك بإجراء تسجيل IMS (MAA/SAA)، يقوم HSS:
    • باسترجاع ملف IMS الخاص بالمشترك
    • تقديم القالب مع بيانات المشترك الفعلية:
      • {{ imsi }} → IMSI للمشترك
      • {{ msisdns }} → أرقام هواتف المشترك
      • {{ mcc }} → رمز الدولة المحمول المكون
      • {{ mnc }} → رمز الشبكة المحمولة المكون
    • إرجاع XML المقدم إلى S-CSCF عبر Cx/Diameter

بناء جملة القالب:

<!-- استبدال المتغيرات البسيطة -->
{{ imsi }}

<!-- حلقات عبر المصفوفات -->
{% for msisdn in msisdns %}
  <MSISDN>{{ msisdn }}</MSISDN>
{% endfor %}

<!-- دمج المتغيرات -->
{{ imsi }}@ims.mnc{{ mnc }}.mcc{{ mcc }}.3gppnetwork.org

مثال على قالب IFC:

<?xml version="1.0" encoding="UTF-8"?>
<IMSSubscription>
<PrivateID>{{ imsi }}@ims.mnc{{ mnc }}.mcc{{ mcc }}.3gppnetwork.org</PrivateID>
<ServiceProfile>
{% for msisdn in msisdns %}
<PublicIdentity>
<Identity>sip:{{ msisdn }}@ims.mnc{{ mnc }}.mcc{{ mcc }}.3gppnetwork.org</Identity>
<Extension>
<IdentityType>0</IdentityType>
</Extension>
</PublicIdentity>
<PublicIdentity>
<Identity>tel:{{ msisdn }}</Identity>
<Extension>
<IdentityType>0</IdentityType>
</Extension>
</PublicIdentity>
{% endfor %}
<InitialFilterCriteria>
<Priority>10</Priority>
<TriggerPoint>
<ConditionTypeCNF>0</ConditionTypeCNF>
<SPT>
<ConditionNegated>0</ConditionNegated>
<Group>0</Group>
<Method>REGISTER</Method>
</SPT>
</TriggerPoint>
<ApplicationServer>
<ServerName>sip:as.ims.mnc{{ mnc }}.mcc{{ mcc }}.3gppnetwork.org</ServerName>
<DefaultHandling>0</DefaultHandling>
</ApplicationServer>
</InitialFilterCriteria>
</ServiceProfile>
</IMSSubscription>

مثال على الطلب (curl):

curl -k -X POST https://hss.example.com:8443/api/ims/profile \
  -H "Content-Type: application/json" \
  -d '{
    "name": "default",
    "ifc_template": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><IMSSubscription><ServiceProfile>...</ServiceProfile></IMSSubscription>"
  }'

مثال على الطلب (Python):

import requests

response = requests.post(
    "https://hss.example.com:8443/api/ims/profile",
    json={
        "name": "default",
        "ifc_template": ifc_template_string
    },
    verify=False  # للشهادات الموقعة ذاتيًا
)

استجابة النجاح (201 تم الإنشاء):

{
  "status": "success",
  "response": {
    "id": 1,
    "name": "default",
    "ifc_template": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>..."
  }
}

التحقق:

  • تتحقق واجهة برمجة التطبيقات من أن قالب IFC هو XML صالح
  • يتم تقديم متغيرات القالب مع بيانات اختبار للتحقق من بناء الجملة
  • يجب أن يكون حقل name فريدًا وغير فارغ

انظر أيضًا:

ملفات APN​

تتكون ملفات APN (اسم نقطة الوصول) من ثلاثة مكونات تعمل معًا:

  1. معرف APN - يحدد اسم APN وإصدار IP
  2. ملف QoS APN - يحدد معلمات جودة الخدمة
  3. ملف APN - يجمع بين المعرف وQoS، مرتبط بـ ملفات EPC

انظر وثائق PCRF لتكوين السياسة التفصيلية، وإدارة QoS، وإعادة المصادقة التلقائية. انظر أيضًا وثائق الملفات الشخصية لأمثلة تكوين APN.

قائمة معرفات APN​

نقطة النهاية: GET /api/apn/identifier

إنشاء معرف APN​

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

جسم الطلب:

{
  "apn": "internet",
  "ip_version": "ipv4v6"
}

قيم إصدار IP:

  • "ipv4" - IPv4 فقط
  • "ipv6" - IPv6 فقط
  • "ipv4v6" - IPv4v6 (دعم مزدوج)
  • "ipv4_or_ipv6" - IPv4 أو IPv6 (اختيار الشبكة)

قائمة ملفات QoS APN​

نقطة النهاية: GET /api/apn/qos_profile

إنشاء ملف QoS APN​

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

جسم الطلب:

{
  "name": "أفضل جهد للإنترنت",
  "allocation_retention_priority": 8,
  "apn_ambr_dl_kbps": 50000,
  "apn_ambr_ul_kbps": 25000,
  "pre_emption_capability": false,
  "pre_emption_vulnerability": true,
  "qci": 9
}

قائمة ملفات APN​

نقطة النهاية: GET /api/apn/profile

إنشاء ملف APN​

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

جسم الطلب:

{
  "apn_identifier_id": 1,
  "apn_qos_profile_id": 1,
  "name": "APN الإنترنت"
}

الحقول المطلوبة:

  • apn_identifier_id - يجب أن يشير إلى معرف APN الموجود
  • apn_qos_profile_id - يجب أن يشير إلى ملف QoS APN الموجود

انظر أيضًا:

إدارة IP الثابت​

يمكن تعيين عناوين IP الثابتة إلى APNs محددة لمشتركين فرديين. وهذا يسمح للمشتركين بتلقي عنوان IPv4 و/أو IPv6 محدد مسبقًا عند الاتصال بـ APN معين، بدلاً من تلقي عنوان ديناميكي من مجموعة DHCP.

العمارة:

تدفق البيانات عند اتصال المشترك:

إجابة تحديث الموقع - رسم بيانات تكوين APN:

يوضح هذا الرسم البياني بالضبط من أين تأتي كل حقل في AVP تكوين APN في S6a Update Location Answer في قاعدة البيانات:

الملاحظات الرئيسية:

  1. معرف السياق: فهرس تسلسلي (0، 1، 2...) لكل APN في الملف
  2. اختيار الخدمة: يأتي مباشرة من apn_identifier.apn (مثل "internet"، "ims")
  3. نوع PDN: مشفر من apn_identifier.ip_version (ipv4=0، ipv6=1، ipv4v6=2، ipv4_or_ipv6=3)
  4. معلمات QoS: جميعها من جدول apn_qos_profile
  5. عرض النطاق الترددي AMBR: يتم ضرب القيم في 1000 (تحويل Kbps إلى bps)
  6. عنوان IP المقدم: يتم تضمينه فقط إذا كانت IP الثابتة موجودة لهذا المشترك + مجموعة APN
    • عملية البحث: subscriber.static_ips → تصفية حسب apn_profile_id → استخراج IPs
    • يتم التحقق من توافق إصدار IP مقابل apn_identifier.ip_version
  7. VPLMN-Dynamic-Address-Allowed: محدد مسبقًا إلى 0 (غير مسموح) - يجبر استخدام IP الثابت إذا تم توفيره

هرمية العلاقة:

المفاهيم الرئيسية:

  • تعيين لكل APN: يتم ربط كل IP ثابت بـ ملف APN محدد
  • IP واحد لكل APN لكل مشتر��: يمكن أن يكون للمشترك IP ثابت واحد فقط مخصص لكل APN
  • دعم IPv4 وIPv6: يمكن أن تكون IPs الثابتة إما IPv4 فقط، أو IPv6 فقط، أو مزدوجة
  • فريدة عالميًا: يجب أن تكون كل عنوان IP فريدة عالميًا عبر جميع سجلات IP الثابتة في النظام
    • لا يمكن تعيين نفس عنوان IPv4 أو IPv6 لمشتركين متعددين (حتى على APNs مختلفة)
    • يمنع ذلك تعارضات التوجيه وغموض عنوان IP
    • يتم فرض ذلك بواسطة فهارس فريدة في قاعدة البيانات على حقول ipv4_static_ip وipv6_static_ip
  • علاقة متعددة إلى متعددة: يتم ربط المشتركين وIP الثابتة عبر جدول الانضمام

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

  • عناوين IP ثابتة لأجهزة IoT
  • استضافة الخوادم على الأجهزة المحمولة (تتطلب IP ثابت للاتصالات الواردة)
  • التطبيقات القديمة التي تتطلب عناوين IP محددة
  • توجيه السياسات الشبكية بناءً على عنوان IP المصدر
  • الامتثال التنظيمي الذي يتطلب تتبع عنوان IP

قائمة IPs الثابتة​

استرجاع جميع تعيينات IP الثابتة.

نقطة النهاية: GET /api/epc/static_ip

مثال على الطلب:

curl -k https://hss.example.com:8443/api/epc/static_ip

مثال على الاستجابة:

{
  "data": [
    {
      "id": 1,
      "apn_profile_id": 5,
      "ipv4_static_ip": "100.64.1.1",
      "ipv6_static_ip": "2606:4700:4700::1111",
      "apn_profile": {
        "id": 5,
        "name": "APN الإنترنت",
        "apn_identifier": {
          "apn": "internet",
          "ip_version": "ipv4v6"
        }
      },
      "inserted_at": "2025-11-15T10:30:00Z",
      "updated_at": "2025-11-15T10:30:00Z"
    }
  ]
}

الحصول على IP ثابت​

استرجاع تعيين IP ثابت محدد.

نقطة النهاية: GET /api/epc/static_ip/:id

معلمات المسار:

المعلمةالنوعالوصف
idintegerID IP الثابت في قاعدة البيانات

مثال على الطلب:

curl -k https://hss.example.com:8443/api/epc/static_ip/1

إنشاء IP ثابت​

إنشاء تعيين IP ثابت جديد لـ APN.

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

جسم الطلب:

{
  "static_ip": {
    "apn_profile_id": 5,
    "ipv4_static_ip": "100.64.1.1",
    "ipv6_static_ip": "2606:4700:4700::1111"
  }
}

الحقول المطلوبة:

  • apn_profile_id - يجب أن يشير إلى ملف APN الموجود
  • يجب تحديد واحد على الأقل من ipv4_static_ip أو ipv6_static_ip

الحقول الاختيارية:

  • ipv4_static_ip - عنوان IPv4 (تنسيق عشري منقوط)
  • ipv6_static_ip - عنوان IPv6 (تنسيق قياسي)

التحقق من تنسيق IP:

  • IPv4: تنسيق قياسي عشري منقوط (مثل 100.64.1.1)
  • IPv6: تنسيق قياسي مفصول بالعمود (مثل 2606:4700:4700::1111)
  • يجب أن تكون كل من عناوين IPv4 وIPv6 فريدة عالميًا عبر جميع سجلات IP الثابتة
    • يمنع ذلك تعارضات عنوان IP في الشبكة
    • لا يمكن تعيين نفس IP لمشتركين متعددين، حتى على APNs مختلفة
    • هذه قيود على مستوى قاعدة البيانات تفرضها الفهارس الفريدة

خيارات التكوين:

التكوينIPv4IPv6المثال
فقط IPv4✓-{"ipv4_static_ip": "100.64.1.1"}
فقط IPv6-✓{"ipv6_static_ip": "2606:4700:4700::1111"}
دعم مزدوج✓✓كلا الحقلين محددين

أمثلة الطلبات:

IP ثابت IPv4 فقط:

curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": 5,
      "ipv4_static_ip": "100.64.1.1"
    }
  }'

IP ثابت IPv6 فقط:

curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": 6,
      "ipv6_static_ip": "2606:4700:4700::1111"
    }
  }'

IP ثابت مزدوج:

curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": 5,
      "ipv4_static_ip": "100.64.1.1",
      "ipv6_static_ip": "2606:4700:4700::1111"
    }
  }'

استجابة النجاح (201 تم الإنشاء):

{
  "data": {
    "id": 1,
    "apn_profile_id": 5,
    "ipv4_static_ip": "100.64.1.1",
    "ipv6_static_ip": "2606:4700:4700::1111",
    "inserted_at": "2025-11-15T10:30:00Z",
    "updated_at": "2025-11-15T10:30:00Z"
  }
}

انظر أيضًا:

تحديث IP ثابت​

تعديل تعيين IP ثابت موجود.

نقطة النهاية: PUT /api/epc/static_ip/:id

معلمات المسار:

المعلمةالنوعالوصف
idintegerID IP الثابت في قاعدة البيانات

جسم الطلب:

{
  "static_ip": {
    "ipv4_static_ip": "100.64.1.2",
    "ipv6_static_ip": "2606:4700:4700::1112"
  }
}

الحقول القابلة للتحديث:

  • ipv4_static_ip - تغيير عنوان IPv4
  • ipv6_static_ip - تغيير عنوان IPv6
  • apn_profile_id - تغيير تعيين APN

غير القابلة للتحديث:

  • id - المفتاح الأساسي (للقراءة فقط)

تحذير: تغيير عنوان IP لمشترك نشط سيؤثر على اتصال PDN التالي. ستستمر جلسات PDN النشطة في استخدام IP القديم حتى تفصل وتعيد الاتصال.

مثال على الطلب:

curl -k -X PUT https://hss.example.com:8443/api/epc/static_ip/1 \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "ipv4_static_ip": "100.64.1.2"
    }
  }'

حذف IP ثابت​

إزالة تعيين IP ثابت.

نقطة النهاية: DELETE /api/epc/static_ip/:id

معلمات المسار:

المعلمةالنوعالوصف
idintegerID IP الثابت في قاعدة البيانات

مثال على الطلب:

curl -k -X DELETE https://hss.example.com:8443/api/epc/static_ip/1

السلوك:

  • يزيل تعيين IP الثابت
  • لا يؤثر على ملف APN (يبقى APN متاحًا لمشتركين آخرين)
  • سيحصل المشتركين الذين يستخدمون هذا IP الثابت على IP ديناميكي في الاتصال التالي
  • يصبح عنوان IP متاحًا للاستخدام مرة أخرى بعد الحذف

تحذير: إذا كان المشترك يستخدم هذا IP الثابت بنشاط، فإن حذفه سيؤدي إلى حصولهم على IP ديناميكي في اتصال PDN التالي. تأكد من أن المشتركين غير متصلين أو أرسل طلب إلغاء الموقع قبل الحذف.

تعيين IP ثابت لمشترك​

لتعيين IP ثابت لمشترك، تحتاج إلى ربط سجل IP الثابت بـ المشترك أثناء الإنشاء أو التحديث.

نمط التعيين:

  1. إنشاء IP الثابت (انظر إنشاء IP ثابت)
  2. تعيينه للمشترك باستخدام حقل static_ips

إنشاء مشترك مع IP ثابت:

# الخطوة 1: إنشاء IP ثابت لـ APN "الإنترنت"
STATIC_IP_ID=$(curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": 5,
      "ipv4_static_ip": "100.64.1.1",
      "ipv6_static_ip": "2606:4700:4700::1111"
    }
  }' | jq -r '.data.id')

# الخطوة 2: إنشاء مشترك مع IP ثابت معين
curl -k -X POST https://hss.example.com:8443/api/subscriber \
  -H "Content-Type: application/json" \
  -d "{
    \"subscriber\": {
      \"imsi\": \"001001123456789\",
      \"key_set_id\": 1,
      \"epc_profile_id\": 1,
      \"static_ips\": [$STATIC_IP_ID]
    }
  }"

تحديث مشترك موجود مع IP ثابت:

curl -k -X PUT https://hss.example.com:8443/api/subscriber/1 \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "static_ips": [1, 2]
    }
  }'

عدة IPs ثابتة (APNs مختلفة):

يمكن أن يكون للمشترك عدة IPs ثابتة طالما أن كل منها لـ APN مختلفة:

# إنشاء IP ثابت لـ APN "الإنترنت"
INTERNET_IP=$(curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": 5,
      "ipv4_static_ip": "100.64.1.1"
    }
  }' | jq -r '.data.id')

# إنشاء IP ثابت لـ APN "ims"
IMS_IP=$(curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": 6,
      "ipv4_static_ip": "100.64.2.1"
    }
  }' | jq -r '.data.id')

# تعيين كلاهما للمشترك
curl -k -X POST https://hss.example.com:8443/api/subscriber \
  -H "Content-Type: application/json" \
  -d "{
    \"subscriber\": {
      \"imsi\": \"001001123456789\",
      \"key_set_id\": 1,
      \"epc_profile_id\": 1,
      \"static_ips\": [$INTERNET_IP, $IMS_IP]
    }
  }"

قواعد التحقق:

  • ✓ مسموح: عدة IPs ثابتة لـ APNs مختلفة
  • ✗ مرفوض: عدة IPs ثابتة لنفس APN

مثال على الخطأ - APN مكرر:

# هذا سيفشل إذا كانت كلا IPs الثابتة تشير إلى نفس APN
curl -k -X POST https://hss.example.com:8443/api/subscriber \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "imsi": "001001123456789",
      "static_ips": [1, 2]
    }
  }'

# استجابة الخطأ:
{
  "errors": {
    "static_ips": [
      "يجب أن تكون IPs الثابتة لكل APN لكل مشترك فريدة. على سبيل المثال، لا يمكن تعيين IP ثابت 100.64.1.1 للمشتركين على الإنترنت وأيضًا 100.64.1.2 للإنترنت"
    ]
  }
}

انظر أيضًا:

إدارة التجوال​

تتحكم ملفات التجوال في ما إذا كان يمكن للمشتركين الوصول إلى خدمات البيانات وIMS على الشبكات الزائرة. يتم تعيين الملفات إلى المشتركين وتتكون من قواعد تتطابق مع MCC/MNC.

قائمة ملفات التجوال​

نقطة النهاية: GET /api/roaming/profile

إنشاء ملف التجوال​

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

جسم الطلب:

{
  "roaming_profile": {
    "name": "شركات الولايات المتحدة فقط",
    "data_action_if_no_rules_match": "deny",
    "ims_action_if_no_rules_match": "deny",
    "roaming_rules": []
  }
}

قيم الإجراءات:

  • "allow" - السماح
  • "deny" - الرفض

الإجراءات الافتراضية:

  • data_action_if_no_rules_match - الإجراء عند عدم تطابق أي قاعدة تجوال
  • ims_action_if_no_rules_match - الإجراء الافتراضي الخاص بـ IMS

قائمة قواعد التجوال​

نقطة النهاية: GET /api/roaming/rule

إنشاء قاعدة التجوال​

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

جسم الطلب:

{
  "roaming_rule": {
    "name": "السماح لـ AT&T",
    "mcc": "310",
    "mnc": "410",
    "data_action": "allow",
    "ims_action": "allow"
  }
}

الحقول:

  • mcc - رمز الدولة المحمول (3 أرقام)
  • mnc - رمز الشبكة المحمولة (2-3 أرقام)
  • data_action - "allow" أو "deny" خدمات البيانات
  • ims_action - "allow" أو "deny" خدمات IMS/الصوت

انظر أيضًا:

إدارة EIR​

تعمل OmniHSS كمسجل هوية المعدات (EIR) عبر واجهة Diameter S13. تتحكم قواعد EIR في وصول الأجهزة بناءً على أنماط IMEI.

انظر وثائق EIR للتحقق التفصيلي من هوية المعدات، وتدفقات واجهة S13، والتحقق من IMEI.

قائمة قواعد EIR​

نقطة النهاية: GET /api/eir/rule

إنشاء قاعدة EIR​

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

جسم الطلب:

{
  "eir_rule": {
    "name": "حظر iPhone 6",
    "imei_regex": "^35[0-9]{6}0[0-9]{7}$",
    "action": 1
  }
}

الحقول:

  • name - اسم وصفي للقواعد
  • imei_regex - تعبير منتظم لمطابقة أرقام IMEI
  • action - القائمة البيضاء (0)، القائمة السوداء (1)، أو القائمة الرمادية (2)

قيم الإجراءات:

  • 0 - القائمة البيضاء (السماح)
  • 1 - القائمة السوداء (الرفض)
  • 2 - القائمة الرمادية (السماح ولكن تتبع)

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

  • حظر الأجهزة المسروقة (قائمة سوداء لأرقام IMEI محددة)
  • تقييد أنواع الأجهزة (قائمة سوداء حسب نمط TAC)
  • السماح فقط للأجهزة المعتمدة (نمط قائمة بيضاء مع رفض افتراضي)

انظر أيضًا:

وثائق إضافية​

لمزيد من المعلومات، راجع الوثائق التالية:

← العودة إلى دليل العمليات | التالي: لوحة التحكم →

آخر تحديث في