واجهة Sh (استرجاع بيانات المشتركين)

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

توفر واجهة Sh الوصول إلى بيانات ملف تعريف المشتركين من HSS/Repository عبر Diameter.

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

الوثائق الأساسية

• 📋 README الرئيسي - نظرة عامة وبدء سريع
• 🔧 دليل التكوين - تكوين نظير Diameter
• 🔧 دليل العمليات - اختبار واجهة Sh في لوحة التحكم

تكامل معالجة المكالمات

• 🔀 تكوين خطة الاتصال - استخدام بيانات Sh في متغيرات خطة الاتصال
• ⚙️ الخدمات التكميلية - تكوين MMTel لإعادة توجيه المكالمات
• 📡 خريطة SS7 - بيانات HLR مقابل أولوية بيانات Sh

الواجهات ذات الصلة

• 💳 الشحن عبر الإنترنت - واجهة Ro (تستخدم أيضًا Diameter)
• 🔢 ترجمة الأرقام - تطبيع الأرقام قبل البحث في Sh

المراقبة

• 📊 مرجع القياسات - قياسات واجهة Sh والمراقبة

---

واجهة Sh (استرجاع بيانات المشتركين)

تُستخدم واجهة Sh لاسترجاع بيانات ملف تعريف المشتركين من HSS/Repository قبل معالجة المكالمات. تتضمن هذه البيانات هويات المشتركين والخدمات وتكوين MMTel.

ما هي واجهة Sh؟

واجهة Sh هي واجهة Diameter موحدة وفقًا لمعايير 3GPP بين TAS و HSS/Repository (Repo). توفر الوصول في الوقت الحقيقي إلى:

• هويات مشتركي IMS (IMPI/IMPU)
• إعدادات إعادة توجيه المكالمات (MMTel-Config)
• تفويض خدمة المشترك
• تعيين S-CSCF

متى تحدث عمليات البحث في Sh

تحدث عمليات البحث في Sh على:

• مكالمات MT: البحث عن الطرف المتصل (المشترك الوجهة)
• مكالمات MO: البحث عن الطرف المتصل (المشترك المصدر)
• المكالما�� الطارئة: البحث عن الطرف المتصل (للموقع/الهوية)

في كل حالة، يقوم TAS بإصدار UDR واحدة بالضبط لكل ساق مكالمة. تستخدم كل من MO و MT نفس شكل Multi-Data-Reference UDR — فقط تسميات القياس تختلف.

Multi-Data-Reference UDR (Notif-Eff)

وفقًا لمعيار 3GPP TS 29.328 §6.1.1.1، عندما يدعم كل من AS و HSS ميزة Notif-Eff (المتفاوض عليها عبر AVP Supported-Features)، يمكن أن يحمل UDR واحد عدة AVPs Data-Reference ويستجيب HSS بـ UDA واحدة حيث يكون User-Data-Sh مستند <Sh-Data> واحد يدمج الأشجار المرجعية كأشقاء. يعتمد TAS على هذا — كل عملية بحث في Sh تسترجع مجموعة كاملة من المراجع التي يعرف النظام كيفية استهلاكها في رحلة ذهاب وإياب واحدة.

المراجع المطلوبة (TS 29.328 الجدول 7.6.1)

Ref	العنصر	يستخدمه TAS لملء
0	RepositoryData (مع Service-Indication = "MMTEL-Services")	call_forward_all_destination, call_forward_not_reachable_destination, no_reply_timer
10	IMSPublicIdentity	ims_public_identity, msisdn
11	IMSUserState	ims_user_state (قيمة تعداد خام من TS 29.328 §7.6.3)
12	SCSCFName	scscf_address, scscf_domain
13	InitialFilterCriteria	(الجسم المعاد إلى TAS ولكن لم يتم عرضه حاليًا كمتغير خطة اتصال)
14	LocationInformation	location_rat_type, location_mme_name, location_vplmn_id, location_age_seconds
15	UserState	user_state (قيمة تعداد خام من TS 29.328 §7.6.7)
17	MSISDN	(تم التحقق منها ضد IMPU)
32	IMSI	imsi
33	IMSPrivateUserIdentity	ims_private_identity, ims_domain (تم تحليله من اللاحقة)

تظهر جميع الحقول ذات السلسلة الواحدة كمتغيرات سلسلة خام في خطة الاتصال — لا يقوم TAS بتفسير قيمها. انظر إلى جدول متغيرات خطة الاتصال المعينة من بيانات Sh أدناه للحصول على القائمة الكاملة.

مثال على جسم UDA (منظف)

تبدو استجابة مدمجة ناجحة في تتبع مباشر على النحو التالي — تظهر الأشجار المرجعية تحت غلاف <Sh-Data> واحد بالترتيب الذي تم طلب المراجع:

[debug] تم استرجاع بيانات المتصل لـ +614xxxxxxxx
        (Data-Ref [0, 10, 11, 12, 13, 14, 15, 17, 32, 33],
         SI="MMTEL-Services"): 4453 بايت

<?xml version="1.0" encoding="UTF-8"?>
<Sh-Data>
  <RepositoryData></RepositoryData>
  <PublicIdentifiers>
    <IMSPublicIdentity>sip:+614xxxxxxxx@ims.mnc001.mcc999.3gppnetwork.org</IMSPublicIdentity>
    <IMSPublicIdentity>tel:+614xxxxxxxx</IMSPublicIdentity>
  </PublicIdentifiers>
  <ShIMSData>
    <IMSUserState>1</IMSUserState>
  </ShIMSData>
  <ShIMSData>
    <SCSCFName>sip:scscf01.ims.mnc001.mcc999.3gppnetwork.org:5060</SCSCFName>
  </ShIMSData>
  <IMSSubscription>
    <PrivateID>9999990000xxxxx@ims.mnc001.mcc999.3gppnetwork.org</PrivateID>
    <ServiceProfile>
      ... إدخالات InitialFilterCriteria ...
    </ServiceProfile>
  </IMSSubscription>
  <ShIMSData>
    <LocationInformation>
      <RAT-Type>eutran</RAT-Type>
      <MMEName>mme01.epc.mnc001.mcc999.3gppnetwork.org</MMEName>
      <VPLMNId>999001</VPLMNId>
      <AgeOfLocationInformation>NNNN</AgeOfLocationInformation>
    </LocationInformation>
  </ShIMSData>
  <IMSPrivateUserIdentity>9999990000xxxxx@ims.mnc001.mcc999.3gppnetwork.org</IMSPrivateUserIdentity>
</Sh-Data>

كيف تستهلك المحللات الجسم المدمج

لا يقوم TAS بالتجول في شجرة XML. كل محلل مرجعي مستقل و معتمد على العلامات: يبحث في الجسم المدمج عن اسم عنصر محدد (مثل <SCSCFName>, <IMSPublicIdentity>, <CallForwardUnconditional>, <CallForwardNoReplyTimer>, كتلة not-reachable cp:rule) ويسحب فقط القيمة التي تهمه. يتم تجاهل الأشجار الفرعية التي لا يتعرف عليها المحلل بصمت.

نتيجة كل محلل هي خريطة بيانات مشتركة جزئية؛ يتم دمج الجزئيات بترتيب على خريطة القيم الافتراضية. هذا يجعل عملية البحث قوية أمام تنفيذات HSS غير المتجانسة والاستجابات الجزئية — انظر قسم الانحدار السلس أدناه.

البيانات المسترجعة من واجهة Sh

يصدر TAS UDR واحدة متعددة المراجع لكل ساق مكالمة (انظر Multi-Data-Reference UDR (Notif-Eff) أعلاه لشكل الطلب والاستجابة المدمجة). تقع الحقول التي يستخرجها TAS من جسم <Sh-Data> المدمج في ثلاث مجموعات:

1. هويات IMS:

• IMPI (الهوية الخاصة): تم تحليلها من عنصر <IMSPrivateUserIdentity>. التنسيق: {IMSI}@{IMS-domain}. يقوم TAS بالتقسيم على @ لاستعادة IMSI ومجال IMS بشكل مستقل.
• IMPU (الهوية العامة): تم تحليلها من عنصر <IMSPublicIdentity>. التنسيق: sip:+{MSISDN}@{IMS-domain}. يتم إزالة + من MSISDN وتظهر كمتغير خطة الاتصال msisdn.

2. تعيين S-CSCF:

• اسم خادم S-CSCF والنطاق حيث يتم تسجيل المشترك حاليًا، تم تحليله من عنصر <SCSCFName> (Data-Reference 12). يستخدمه MT خطة الاتصال لتوجيه INVITE مباشرة إلى S-CSCF المسجل بدلاً من الانتشار في مجال IMS.
• ملاحظة: اسم العنصر XML القياسي في TS 29.328 الملحق D هو SCSCFName (بدون شرطة). الشكل الذي يحتوي على الشرطة "S-CSCF" يظهر فقط في نص المواصفات.

3. خدمات MMTel (تكوين الهاتف المتعدد الوسائط):

• تم إرجاعها داخل <RepositoryData> مع مفتاح Service-Indication = "MMTEL-Services".
• قواعد إعادة توجيه المكالمات الخاصة بالمشترك:
  • إعادة توجيه المكالمات الكل (CFA): إعادة توجيه غير مشروط إلى رقم آخر
  • إعادة توجيه المكالمات عند الانشغال (CFB): إعادة توجيه عند انشغال المشترك
  • إعادة توجيه المكالمات بدون رد (CFNRy): إعادة توجيه بعد انتهاء المهلة (قيمة المؤقت المستخرجة من <CallForwardNoReplyTimer>)
  • إعادة توجيه المكالمات غير القابلة للوصول (CFNRc): إعادة توجيه عند عدم اتصال المشترك (تم استخراجها من not-reachable <cp:rule> داخل مستند خدمات MMTel)

ما هو MMTel-Config؟

MMTel-Config هو تكوين خدمة الهاتف المتعدد الوسائط للمشترك المخزنة كبيانات شفافة (مستودع) في HSS، مع مفتاح Service-Indication = "MMTEL-Services". يتم اس��رجاعه كجزء من نفس UDR متعددة المراجع مثل بحث الهوية (Data-Reference 0 بالإضافة إلى AVP إشارة الخدمة). يتبع المستند مخطط OMA / 3GPP simservs XCAP وعادة ما يحتوي على كتلة complete-communication-diversion مع إدخال أو أكثر من cp:rule (busy, noanswer, unregistered, notreachable)، قيمة <NoReplyTimer> اختيارية، وخدمات فرعية أخرى لـ MMTel مثل حظر الاتصالات وعرض الهوية.

خدمات MMTel الشائعة التي يتعرف عليها TAS:

• CDIV (تحويل الاتصالات): قواعد إعادة توجيه المكالمات — الكتلة الوحيدة التي يتم تحليلها من النهاية إلى النهاية في متغيرات خطة الاتصال. قاعدة notreachable تملأ call_forward_not_reachable_destination و <NoReplyTimer> تملأ no_reply_timer.
• OIP (عرض الهوية الأصلية): قواعد عرض هوية المتصل (تم إرجاعها في الجسم ولكن لم يتم استهلاكها حاليًا).
• TIP (عرض الهوية النهائية): قواعد رقم الطرف المتصل (تم إرجاعها في الجسم ولكن لم يتم استهلاكها حاليًا).

متغيرات خطة الاتصال المعينة من بيانات Sh

بعد عملية بحث ناجحة في Sh، يتم ملء هذه المتغيرات:

المتغير	المصدر	قيمة المثال	الوصف
ims_private_identity	IMPI	9999990000xxxxx@ims.mnc001.mcc999.3gppnetwork.org	الهوية الخاصة للمستخدم للمصادقة
ims_public_identity	IMPU	sip:+614xxxxxxxx@ims.mnc001.mcc999.3gppnetwork.org	الهوية العامة للمستخدم للتوجيه
msisdn	IMPU (تم تحليله)	614xxxxxxxx	رقم المشترك (مع إزالة +)
imsi	IMPI (تم تحليله)	9999990000xxxxx	IMSI من الهوية الخاصة
ims_domain	IMPI/IMPU	ims.mnc001.mcc999.3gppnetwork.org	مجال IMS
scscf_address	SCSCFName	sip:scscf01.ims.mnc001.mcc999.3gppnetwork.org:5060 أو "none"	عنوان خادم S-CSCF (مسجل)
scscf_domain	SCSCFName (تم تحليله)	scscf01.ims.mnc001.mcc999.3gppnetwork.org أو "none"	مضيف S-CSCF (مسجل)
call_forward_all_destination	MMTel CDIV	رقمي أو "none"	رقم وجهة CFA
call_forward_not_reachable_destination	MMTel CDIV	رقمي أو القيمة الافتر��ضية للتكوين	وجهة CFNRc (البريد الصوتي)
no_reply_timer	MMTel CDIV	ثوانٍ، أو القيمة الافتراضية للتكوين	المهلة قبل تفعيل CFNRy
ims_user_state	IMSUserState (Data-Ref 11)	"0"/"1"/"2"/"3" أو "none"	حالة تسجيل IMS. 1 = مسجل، 0 = غير مسجل، 2 = انتظار المصادقة، 3 = مسجل_خدمات_غير_مسجلة (TS 29.328 §7.6.3). سلسلة خام، لا يقوم TAS بتفسيرها.
user_state	UserState (Data-Ref 15)	سلسلة خام أو "none"	حالة المستخدم CS/PS (TS 29.328 §7.6.7). سلسلة خام، لا يقوم TAS بتفسيرها.
location_rat_type	LocationInformation/RAT-Type	"eutran", "utran", "geran", "wlan", ... أو "none"	تقنية الوصول اللاسلكي لأحدث تسجيل معروف.
location_mme_name	LocationInformation/MMEName	اسم MME FQDN أو "none"	مضيف MME الذي يخدم المشترك.
location_vplmn_id	LocationInformation/VPLMNId	سلسلة رقمية MCCMNC أو "none"	معرف PLMN الذي تمت زيارته (مفيد لاكتشاف التجوال في خطة الاتصال).
location_age_seconds	LocationInformation/AgeOfLocationInformation	��لسلة رقمية أو "none"	الثواني منذ آخر مرة تم الإبلاغ عن معلومات الموقع إلى HSS.

الأولوية: بيانات Sh مقابل القيم الافتراضية للتكوين

يستخدم TAS هذا ترتيب الأولوية لبيانات إعادة توجيه المكالمات:

1. MMTel-Config من Sh — أعلى أولوية، إعدادات خاصة بالمشترك.
2. بيانات HLR من SS7 MAP — تتجاوز Sh لمكالمات MT إذا كان التجوال أو إعادة توجيه المكالمات نشطة في الشبكة التي تمت زيارتها. انظر SS7 MAP.
3. القيم الافتراضية للتكوين — أدنى أولوية، تُستخدم عندما لا يوفر كل من Sh أو HLR قيمة (أو عندما كانت الشجرة المقابلة مفقودة من استجابة Sh — انظر الانحدار السلس أدناه). يتم تكوين القيم الافتراضية في runtime.exs تحت config :tas — call_forward_not_reachable_destination و default_no_reply_timer.

ماذا يحدث عندما تفشل عملية البحث في Sh

سيناريوهات فشل الطلب بالكامل:

1. المشترك غير مُعَد في HSS:

   • يعيد HSS Experimental-Result-Code 5001 (DIAMETER_ERROR_USER_UNKNOWN)
   • يعتبر TAS ساق المكالمة غير قابلة للحل
   • يتم تعيين المتغير hangup_case إلى "UNALLOCATED_NUMBER"
   • يتم رفض المكالمة مع استجابة SIP المناسبة

2. HSS غير قابل للوصول / انتهاء المهلة:

   • تنتهي مهلة طلب Sh (الافتراضي: 5000 مللي ثانية، انظر request_timeout في Diameter في runtime.exs)
   • يتم تسجيل الخطأ وتسجيل القياس
   • تفشل ساق المكالمة بنفس الطريقة كما في الحالة (1)

3. HSS لا يدعم UDRs متعددة المراجع:

   • إما أن يعيد HSS خطأ أو يسقط الطلب بصمت (يعتمد على HSS)
   • من جانب TAS، يبدو أن هذا مثل الحالة (1) أو (2) — تفشل عملية البحث بالكامل ويتم رفض ساق المكالمة
   • يجب على HSS تنفيذ ميزة Notif-Eff لكي يعمل TAS. انظر TS 29.328 §6.1.1.1 لتعريف الميزة.

الانحدار السلس لكل شجرة فرعية

عندما ينجح UDR نفسه (Result-Code: 2001) ولكن الأشجار الفرعية الفردية من جسم <Sh-Data> المدمج مفقودة، لا يفشل TAS المكالمة. كل محلل مرجعي مستقل ويعود إلى قيمة افتراضية محددة عندما تكون علامته مفقودة. يجب على المشغلين القلق فقط بشأن فشل الطلب بالكامل (أعلاه)؛ الانحدار الجزئي للبيانات تلقائي وقابل للرصد في سجلات التصحيح.

الشجرة المفقودة	النتيجة
<SCSCFName> (Data-Ref 12)	يتم تعيين scscf_address و scscf_domain إلى "none"
<IMSPrivateUserIdentity> (Data-Ref 33)	يتم تعيين ims_private_identity و imsi و ims_domain إلى "none"
<CallForwardUnconditional> داخل MMTel RepositoryData	يتم تعيين call_forward_all_destination إلى "none"
كتلة not-reachable/<cp:rule> داخل MMTel RepositoryData	تتراجع call_forward_not_reachable_destination إلى Tas.Config.call_forward_not_reachable_destination()
<CallForwardNoReplyTimer> داخل MMTel RepositoryData	تتراجع no_reply_timer إلى Tas.Config.default_no_reply_timer()
<RepositoryData></RepositoryData> فارغ	تتراجع جميع الحقول المستمدة من MMTel إلى القيم الافتراضية للتكوين
<IMSUserState> و <LocationInformation> و <InitialFilterCriteria> فارغة/مفقودة	حاليًا لا تأثير جانبي في خطة الاتصال (تم تحليلها ولكن لم يتم توصيلها بعد)

المتطلب الوحيد هو أن تحتوي الاستجابة على عنصر <IMSPublicIdentity>. إذا كانت تلك العلامة مفقودة، فإن عملية البحث تعيد {:error, :sh_parse_failed} وتُعتبر ساق المكالمة غير قابلة للحل (نفس سلوك التدفق كما في الحالة 1 أعلاه). كل حقل آخر هو "اسأل بحرية، خذ ما يمكنك الحصول عليه".

هذا يجعل TAS مقاومًا لنشر HSS غير المتجانسة: HSS التي تنفذ Notif-Eff ولكنها تملأ فقط IMSPublicIdentity و MSISDN و SCSCFName (على سبيل المثال) ستظل تنتج مكالمة تعمل؛ فقط تتراجع خطة الاتصال إلى القيم الافتراضية للتكوين للمتغيرات المستمدة من MMTel.

مراقبة واجهة Sh

المقاييس الرئيسية:

# معدل نجاح البحث في Sh
rate(subscriber_data_lookups_total{result="success"}[5m]) /
rate(subscriber_data_lookups_total[5m]) * 100

# زمن است��ابة البحث في Sh (P95)
histogram_quantile(0.95,
  rate(subscriber_data_duration_milliseconds_bucket[5m]))

# معدل الأخطاء في Sh
rate(subscriber_data_lookups_total{result="error"}[5m])

عتبات التنبيه:

• زمن الاستجابة P95 > 100 مللي ثانية: استجابات HSS بطيئة
• معدل الأخطاء > 5%: مشاكل في الاتصال بـ HSS
• معدل الأخطاء > 20%: فشل حرج في HSS

استكشاف الأخطاء:

1. تحقق من حالة نظير Diameter في واجهة الويب (/diameter)
2. اختبار البحث في Sh في واجهة الويب (/sh_test) مع مشترك معروف
3. مراجعة السجلات بحثًا عن أخطاء "بيانات المشترك"
4. تحقق من أن HSS/Repository قابلة للوصول من TAS
5. تحقق من قياس subscriber_data_lookups_total بحثًا عن أنماط

اختبار واجهة Sh

استخدم أداة اختبار Sh في واجهة الويب (/sh_test):

1. انتقل إلى /sh_test في لوحة التحكم
2. أدخل MSISDN المشترك (مثل +614xxxxxxxx)
3. انقر على "استعلام Sh"
4. راجع البيانات المعادة:
   • هويات IMPI/IMPU
   • تعيين S-CSCF
   • خدمات MMTel
   • تكوين إع��دة توجيه المكالمات

سيناريوهات الاختبار الشائعة:

• تحقق من أن المشتركين الذين تم إعدادهم حديثًا موجودون في HSS
• تحقق من إعدادات إعادة توجيه المكالمات لمشترك معين
• تحقق من تعيين S-CSCF بعد تسجيل IMS
• اختبار الاتصال بـ HSS وأوقات الاستجابة