خدمات ويب REST الواردة

تعرض المواضيع التالية مزيدًا من المعلومات حول دعم المنتج لخدمات REST باستخدام خدمة الويب الواردة. لاحظ أن سجلات خدمة الويب الواردة لخدمة REST مميزة بإصدار محرك REST 1.0 أو 2.0. الإصدار 2.0 هو الإصدار المستخدم للخدمات الجديدة. تم تقديم الإصدار 1.0 للتوافق مع الإصدارات السابقة. يختلف أداء النظام استنادًا إلى إصدار خدمة REST. وتبرز الأقسام أدناه الحالات التي يحدث فيها ذلك.

معلمات وطريقة HTTP

عند تحديد العمليات لخدمات ويب REST الواردة، يدعم المنتج طرق HTTP المكونة من طرق Get وPatch وPost وPut وDelete. يمكنك ملاحظة أن دعم المنتج لطرق HTTP المتعددة هذه يعتبر وسيلة للإبلاغ عن غرض خدمة الويب للعالم الخارجي. ومع ذلك، يعتمد الأداء الفعلي لخدمة ويب REST على أداء الكائن المستند إلى المخطط الأساسي (كائن العمل وخدمة الأعمال وسكريبت الخدمة). على سبيل المثال، قد يمكنك تكوين طريقة HTTP وهي "Put" للعملية التي تشير إلى سكريبت الخدمة الذي لا يقوم إلا باسترجاع سجل. لا يتيح هذا المنتج اكتشاف هذا النوع من التفاوت. يجب أن يقوم مستخدمو التكوين بمراعاة الطريقة الصحيحة بشكل دقيق للاستخدام على أساس منطق هذه الخدمة.

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

ملاحظة: يتطلب استخدام نوع المعاملة "تغيير" أن يتم إدخال كل القيم. بينما يتيح نوع المعاملة "تحديث" لخدمات الويب إمكانية إدخال فقط المفتاح الأساسي والقيم المطلوب تحديثها. وسوف تسترد كل العناصر الأخرى نفس قيمها الموجودة.

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

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

للحصول على أمثلة على معلمات الاستعلام والمسار في عناوين URL للنموذج، ارجع إلى قسم عناوين URL أدناه.

تكوين عنوان URL

عند إنشاء عنوان URL لنقطة النهاية لخدمة REST، توجد ثلاثة أجزاء رئيسية تشكل عنوان URL بالكامل.

الجزء الأول هو الذي يخص البيئة. سيختلف ذلك مع عملية التنفيذ بالمواقع عند المقارنة مع عملية التنفيذ بالشبكة السحابية. سيحتوي كل منهما على مضيف ومنفذ ثم مكونات إضافية تحدد البيئة.
الجزء الثاني هو مسار بتعليمات برمجية مضمنة يتم تعيينه بواسطة المنتج، أي "/rest/apis".

يتم تحديد الجزأين من عنوان URL في متغير الاستبدال F1_REST_BASE_URL. يتم تحديد ذلك عند بدء البيئة الخاصة بك. لمزيد من المعلومات، الرجاء الرجوع إلى دليل إدارة الملقم (Server Administration Guide).

يتم إنشاء الجزء المتبقي من عنوان URL بشكل ديناميكي على أساس التكوين لكل خدمة ويب واردة والعمليات التابعة لها. المكونات هي "/ownerURIComponent/resourceCategoryURIComponent/iwsURIComponent/operationURIComponent"

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

في كل الحالات، يجب أن يبدأ مكون معرف الموارد الموحد بشرطة مائلة ("/").

فيما يلي بعض الأمثلة على الجزء الديناميكي لعنوان URL لخدمة REST. يوضح المثال الأخير استخدام معلمة الاستعلام.


اسم خدمة الويب الواردة مكون معرف الموارد الموحد	المالك مكون معرف الموارد الموحد	فئة المورد مكون معرف الموارد الموحد	طريقة HTTP للعملية مكون معرف الموارد الموحد	مكون عنوان URL الديناميكي	أمثلة عن وقت التشغيل
c1rateCalculation /rateCalculation	C1 /العميل	C1-RATES /التعرفات	طريقة Post /	../customer/rates/rateCalculation/	../customer/rates/rateCalculation/
w1WorkActivity /workActivity	W1 /الأصل	W1-WORK /العمل	طريقة Get /{activityId}	../asset/work/workActivity/{activityId}	../asset/work/workActivity/5798165498
w1WorkActivity /workActivity	W1 /الأصل	W1-WORK /العمل	طريقة Patch /scheduleWindow/{externalSystem}/{activityId}/{windowStartDateTime}	../asset/work/workActivity/scheduleWindow/{externalSystem}/{activityId}/{windowStartDateTime}	../asset/work/workActivity/scheduleWindow/MY-COMPANY/5798165498/20190101
CM-AccountActivityHistory /accountActivityHistory	التعديل من قِبل العميل /التعديل من قِبل العميل	CM-ACCT-INFO /accountInformation	طريقة Get /{accountId}	../cm/accountInformation/accountActivityHistory/{accountId}	../cm/accountInformation/accountActivityHistory/123456789?activityId=5468976

تنسيق بيانات القياس المنقولة

تدعم خدمات REST استلام بيانات القياس المنقولة للطلب بتنسيق XML أو JSON، وتُرجع بيانات القياس المنقولة إما بتنسيق XML أو JSON. يعتمد التنسيق الافتراضي الذي تم إرجاعه على قيمة إصدار محرك REST.

تفترض خدمات الإصدار 2.0 أن تنسيق JSON هو التنسيق الافتراضي. يمكن تجاوز التنسيق الافتراضي عن طريق توفير عنوان قبول للتطبيق/XML.
تفترض خدمات الإصدار 1.0 أن تنسيق XML هو التنسيق الافتراضي. يمكن تجاوز التنسيق الافتراضي عن طريق توفير عنوان قبول للتطبيق/JSON.

نقطة التوصيل الأصلية لتنسيق JSON

لا تُقبل خدمات الإصدار 2.0 مع بيانات القياس المنقولة بتنسيق JSON في الطلب أو تُرجع في الاستجابة أي نقطة توصيل أصلية حول بيانات القياس المنقولة. فيما يلي مثال لاستجابة استدعاء REST لخدمة الإصدار 2.0:

{
   "batchJobId": "string",
   "requestSuccessful": "string"
}

تتوقع خدمات الإصدار 1.0 مع بيانات القياس المنقولة بتنسيق JSON وجود نقطة توصيل أصلية في الطلب وإرجاع نقطة توصيل في الاستجابة. فيما يلي مثال لاستجابة استدعاء REST لخدمة الإصدار 1.0:

{
  "F1CnclBatJob": {
    "batchJobId": "string",
    "requestSuccessful": "string"
 }
}

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

نوع البيانات بتنسيق JSON

بتنسيق JSON، تكون السلاسل محاطة بعلامات اقتباس وأرقام، ولا تحتوي البيانات المنطقية على علامات اقتباس. تتبع كل الخدمات الخاصة بمحرك REST الإصدار 2.0 هذا المعيار. كانت الخدمات الأصلية التي من الإصدار 1.0 لمحرك REST تتعامل بشكل غير صحيح مع الأرقام والبيانات المنطقية كسلاسل وتُرجع البيانات بعلامات اقتباس. وتم تصحيح ذلك.

لاستيعاب أي تكامل قد يكون حدث حول أداء خدمات الإصدار 1.0، يوفر النظام إمكانية تحديد خدمات الويب الواردة التي تمثل استثناءات لهذه القاعدة. بالنسبة لأي خدمة ويب واردة محددة كاستثناء، يواصل النظام معاملة الأرقام والبيانات المنطقية كسلاسل في استجابات JSON. لإضافة سجل أو أكثر من سجلات خدمة الويب الواردة إلى قائمة الاستثناءات:

الانتقال إلى تكوين الميزة.
ابحث عن تكوين ميزة موجود بنوع الميزة "رسائل خارجية". وإذا لم يكن موجودًا، فقم بإنشائه.
أضف خيارًا لنوع الخيار استثناءات نوع بيانات خدمة الويب الواردة JSON.
في قيمة الخيار، حدد سجل خدمة الويب الواردة الذي يعد استثناءً. لاحظ أنه يمكن إضافة خيارات متعددة لنوع الخيار. بالإضافة إلى ذلك، تدعم قيمة الخيار قائمة محددة بفواصل.

مخطط واجهة خارجي

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

يدعم مخطط العملية الإمكانات التالية:

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

لمزيد من المعلومات، ارجع إلى سمات ونقاط توصيل مخطط خدمة الويب.

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

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

روابط ديناميكية

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

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

مثال على الصياغة:


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

مثال على عنوان URL لنقطة نهاية وقت التشغيل:


  _link: "http://.../common/toDos/toDoEntries/28937296450934"

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

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

يمكن إدخال معلومات الوثائق التالية لخدمة ويب واردة:

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

ملاحظة: لا تتم ترجمة الأوصاف التفصيلية ونص التعليمات المتعلقة بالعنصر حيث إن الدليل المنشور للواجهات البرمجية للتطبيقات الخاصة بالمنتج الأساسي باللغة الإنجليزية فقط.