سمات ونقاط توصيل مخطط خدمة الويب

تقوم عملية خدمة ويب REST الواردة (IWS) باستدعاء كائن واحد مستند إلى مخطط، إما كائن عمل أو خدمة أعمال أو سكريبت خدمة. يحتوي الكائن على مخطط واحد يعمل افتراضيًا كمخطط الطلب والاستجابة. يوفر المنتج إمكانية تحديد مخطط صريح لعملية خدمة ويب تمثل طريقة عرض للمخطط الداخلي الأساسي لمستهلك واجهة خارجي. لاحظ أن مخطط العملية هو عرض مقيد للمخطط الداخلي ولذلك لا يتم إدخال تغييرات هيكلية.

في حين أن تحديد مخطط العملية اختياري، فإن له المزايا التالية:

  • تحديد الاستخدام الخاص بعنصر ما إذا كان جزءًا من مخطط الطلب أو مخطط الاستجابة أو كليهما.

  • تعيين اسم عنصر خارجي لعنصر داخلي. مفيد لتجنب استنساخ الخدمات الداخلية لهذا الغرض فقط.

  • إدارة ورؤية أفضل لمراجع عملية GET.

  • دعم هياكل نمط HATEOAS خارج المخطط الداخلي. يسمح ذلك بالمعالجة الداخلية السلسة.

  • إدخال نص تعليمات للعناصر الفردية.

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

المحتويات

تعريف مخطط العملية

العناصر المتخصصة

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

تعريف مخطط العملية

تحدد السمات التالية مخطط عملية الواجهة الخارجية الذي يقوم بإنشاء مخطط الاستجابة والطلب للعملية.

رمز الاختصار القيم الصالحة الوصف الأمثلة
usage= "REQ"

للإشارة إلى أنه يجب تضمين العنصر في مخطط الطلب فقط.

عند التحديد لمجموعة أو عنصر قائمة، يتم تطبيق القيمة على الحاوية بأكملها. يمكن أن يتجاوز العنصر المحدد في الحاوية القيمة الافتراضية للحاوية.

 
<customerName usage="REQ" />
"RESP"

للإشارة إلى أنه يجب تضمين العنصر في مخطط الاستجابة فقط.

عند التحديد لمجموعة أو عنصر قائمة، يتم تطبيق القيمة على الحاوية بأكملها. يمكن أن يتجاوز العنصر المحدد في الحاوية القيمة الافتراضية للحاوية.

 
<customerId usage="RESP" />
"BOTH"

للإشارة إلى أنه يجب تضمين العنصر في كل من تعريفات مخطط الاستجابة والطلب. وهذه القيمة هي القيمة الافتراضية

عند التحديد لمجموعة أو عنصر قائمة، يتم تطبيق القيمة على الحاوية بأكملها. يمكن أن يتجاوز العنصر المحدد في الحاوية القيمة الافتراضية للحاوية.

 
<customerName usage="BOTH" />
"EXCL"

للإشارة إلى أنه يجب عدم تضمين العنصر في تعريفات مخطط الاستجابة أو الطلب.

عند التحديد لمجموعة أو عنصر قائمة، يتم تطبيق القيمة على الحاوية بأكملها. يمكن أن يتجاوز العنصر المحدد في الحاوية القيمة الافتراضية للحاوية.

 
<httpMethod usage="EXCL" />
mapTo= "اسم العنصر الداخلي"

ربط عنصر خدمة ويب بعنصر داخلي. افتراضيًا، يتم افتراض أن اسم العنصر الداخلي هو نفس اسم عنصر خدمة الويب. استخدم هذه السمة لتخصيص اسم عنصر واجهة خارجي في مخطط العملية وربطه بعنصر داخلي مطابق.

لاحظ أن هذا التعبير ليس تعبير XPath ولكنه مرجع لاسم عنصر صالح يطابق هيكل المخطط الداخلي الموسع.

يجب أن يكون مالك العنصر هو نفس مالك مخطط خدمة الويب. إذا تم تمديد المخطط الأساسي للعملية (باستخدام امتداد منطقة البيانات الديناميكية) فيمكن للمالك الموسع الإشارة فقط إلى عناصره في امتداد مخطط خدمة الويب الخاص به للعملية.

عنصر المخطط الداخلي:

<toDoPriority .../>

عنصر مخطط العملية:

<priority mapTo="toDoPriority"/>
role= "FKGP"

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

العنصر نفسه غير موجود في المخطط الداخلي. يقوم بتجميع عناصر قيمة المفتاح الخارجي معًا مع عنصر _​link المقابل الذي يوفر في وقت التشغيل عنوان URL لنقطة النهاية لعملية GET الخاصة بهذا الكيان. قد يستخدم مستهلكو خدمة الويب الرابط للحصول على بيانات الكيان.

عنصر المخطط الداخلي:

<user .../>

مجموعة مخطط العملية:

<user role="FKGP">
   <user>
   <_link getOperation="mo:'USER';pk1:user;"/>
</user>
"COLL"

إنشاء هيكل مجموعة يمثل مجموعة من الكيانات توافق قائمة الخدمة الداخلية.

العنصر نفسه غير موجود في المخطط الداخلي. يتم تجميع القائمة الداخلية المرتبطة بعنصر _​data مع عنصر _​link المقابل الذي يوفر في وقت التشغيل عنوان URL لنقطة النهاية لعملية GET الخاصة بالتحصيل. قد يستخدم مستهلكو خدمة الويب الرابط للحصول على مجموعة أكثر تفصيلاً من المعلومات لكل كيان في القائمة.

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

عنصر المخطط الداخلي:

<alerts type="list">
     <alert/>
     <startDate />
     <endDate />
     <version />
   </_data> </alerts>

مجموعة مخطط العملية:

<alerts role="COLL">
   <_link getOperation="... "/>
   <_data mapTo="alerts">
        <version usage="EXCL"/>
   </_data>
</alerts>
getOperation=

"التعبير"

مكونات التعبير:

  • mo:’<maintenance object>’;

  • pk1:<xpath نسبي لعنصر في المخطط الداخلي>؛

  • pk2:...;

  • pk3:...;

  • pk4:...;

  • pk5:...;

المعلمات pk2-5 مطلوبة لمطابقة تعريف المفتاح الأساسي لكائن الصيانة.

صالح فقط لعناصر _​self و_​link. يتم استخدام السمة للإشارة إلى عملية GET الافتراضية لأحد الكيانات كما هو محدد بواسطة كائن الصيانة أو كائن العمل الخاص به.

يحدد التطبيق عملية GET المطلوب استخدامها كما يلي:

  • إذا كان كائن عمل الكيان يشير إلى عملية باستخدام خيار عملية GET، يتم استخدامها.

  • إذا كان كائن صيانة الكيان يشير إلى عملية باستخدام خيار عملية GET، يتم استخدامها.

  • في حالة العثور على عملية GET تشير إلى كائن الصيانة، يتم استخدامها.

في حالة تعذر تحديد عملية GET للكيان، يتم إرجاع نص قياسي يشير إلى أن الرابط غير متاح بدلاً من ذلك.
 
<_link getOperation="mo:'TO DO ENTRY';pk1:toDoEntryId;"/>

"التعبير"

مكونات التعبير:

  • iws:'<اسم خدمة الويب الواردة>'؛

  • operation:’<operation name>’;

  • parms:[<المرجع الخارجي كما هو محدد في سجل عملية GET>:<xpath نسبي لاسم العنصر في مخطط قاعدة البيانات الداخلي الذي يحتوي على القيمة>؛ <اسم مرجع خارجي آخر>:<مسار xpath نسبي آخر>؛...]؛

صالح فقط لعناصر _​self و_​link. تُستخدم السمة للإشارة إلى عملية GET محددة بالإضافة إلى المعلومات اللازمة لتكوين معلمات المسار الخاصة بها.

 
<_self getOperation="iws:'F1-ToDoEntry'; operation:'getToDoEntry'; parms:[toDoEntryId:toDoEntryId;]"/>

العناصر المخصصة

يستخدم تعريف مخطط العملية أسماء العناصر المخصصة في نمط الوسائط التشعبية كمعيار لمحرك حالة التطبيق (HATEOAS). يجب تحديد هذه العناصر فقط بواسطة مخطط العملية نظرًا لأنها غير مرتبطة بخدمة العمليات الداخلية أو يجب إدارتها.

تصف القائمة التالية كل عنصر وكيفية استخدامه.

اسم العنصر الوصف الأمثلة
<_​self .../>

قد تتضمن بيانات القياس المنقولة للاستجابة عنصر "_​self" يحتوي على عنوان URL لنقطة النهاية لعملية GET المرتبطة بالكيان الذي تم إرجاعه في الاستجابة.

هذا عنصر اختياري وقد يوجد عنصر واحد فقط في مخطط العملية.

لمزيد من المعلومات، ارجع إلى سمات تعريف المخطط getOperation=.

 
<_self getOperation="mo:'TO DO ENTRY';pk1:toDoEntryId;"/>
<_​link .../>

قد تتضمن بيانات القياس المنقولة للاستجابة مفاتيح خارجية وبالنسبة لتلك الكيانات، تتضمن الاستجابة عنصر "_​link" يحتوي على عنوان URL لنقطة النهاية لعملية GET لهذا الكيان (في حالة وجوده).

لمزيد من المعلومات، ارجع إلى سمة تعريف المخطط role= وgetOperation=.

 
<_link getOperation="mo:'TO DO ENTRY';pk1:toDoEntryId;"/>
<_​data .../>

توفير مرجع قياسي لقائمة كيانات في المخطط الداخلي.

لمزيد من المعلومات، ارجع إلى سمة تعريف المخطط role=”COLL”.

 
<alerts role="COLL">
   <_link getOperation="... "/>
   <_data mapTo="alerts">
   </_data>
</alerts>

سمات الوثائق

توفر السمات التالية وثائق إضافية للعناصر الفردية المضمنة كجزء من مواصفات الواجهة البرمجية للتطبيقات المفتوحة لخدمة الويب.

رمز الاختصار القيم الصالحة الوصف الأمثلة
helpText= "اسم حقل نص التعليمات"

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

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

لاحظ أن هناك عنصرًا داخليًا مرتبطًا باسم حقل من خلال السمات mdField=، إن وجدت، أو من خلال السمة mapField=.

لا توجد قيمة صالحة لعناصر _​self و_​link.

 
<toDoEntryId usage="BOTH" helpText="TD_ENTRY"/>

في هذا المثال، تحدد خدمة الويب الواردة اسم حقل نص التعليمات "TD_​ENTRY" الذي يوفر نص تعليمات لهذا العنصر. يتم تضمين نفس نص التعليمات للعنصر في كل من مخطط الطلب والاستجابة.
helpTextResponse= "اسم حقل نص التعليمات"

ربط عنصر مضمن في كل من مخطط الطلب والاستجابة بسجل نص تعليمات محدد ليتم استخدامه في سياق مخطط الاستجابة.

تتبع نفس قواعد السمة helpText=.

 
<toDoEntryId usage="BOTH" helpText="TD_ENTRY" helpTextResponse="TD_ENTRY_RESP"/>
في هذا المثال، تحدد خدمة الويب الواردة سجلات نص التعليمات التالية:

  • يصف اسم حقل نص التعليمات "TD_​ENTRY" العنصر المرسل في مخطط الطلب.

  • يصف اسم حقل نص التعليمات "TD_​ENTRY_​RESP" العنصر الذي تم ملؤه في مخطط الاستجابة.