استكشاف خيارات تكوين الموصل المخصص
نواصل في هذه الوحدة شرح أساسيات الموصلات المخصصة بإلقاء نظرة متعمقة على بعض خيارات التكوين المتوفرة.
تسمية الموصل والمعلومات العامة
من أول القرارات التي ستتخذها هو اسم الموصل. يجب أن يكون الاسم فريداً ويوضح للمستهلك ما الموصل. وأنت مقيد بـ 30 حرفاً لهذا الاسم، ويمكنك ذِكر مزيد من التفاصيل في حقل الوصف. يمكن أيضاً للحقل لون خلفية الأيقونة مساعدتك في تحديد الموصل بشكل مرئي. تعتبر هذه الحقول مهمة لأنها تظهر توقيت تحديد المستخدم للموصل الذي سيتم استخدامه، وتساعد هذه الإشارات المرئية المستخدم على العمل بكفاءة أكبر. إذا كنت تخطط لإرسال الموصل للحصول على الشهادة، فتأكد من مراجعة المتطلبات الأكثر صرامة في الإرشادات الخاصة بإرسال الموصل إلى وثائق Microsoft.
تسمية المشغّل والإجراء
بعد تقييد مستخدم على الموصل الخاص بك، سيقوم باختيار إجراء أو مشغّل للاستخدام من الموصل. تساعدك حقول معرف العملية والملخص والوصف على وصف كل إجراء ومشغّل. يُستخدم معرف العملية داخلياً، ويجب أن يكون فريداً، ولا يمكن أن يحتوي على مسافات. سيساعد استخدام حالة camel، مثل GetInvoice، على تسهيل قدرتك على قراءة المعرف إذا كنت تنظر إلى علامات التعريف. قد يكون نقص المساحات في الأسماء صعباً على المنشئين الذين يستخدمون قارئات الشاشة، لكن استخدام حالة camel من شأنه أن يساعد على إمكانية الوصول بشكل أكبر إلى تعريفاتك.
يعد حقل الملخص هاماً لأنه يظهر في قائمة الإجراءات والمشغّلات عندما تقوم بتحديد الخيار المراد استخدامه. نوصي بأن تقوم بتوفير ما يكفي من الوصف بحيث يمكنك الإخبار بما يفعله الإجراء أو المشغّل. على سبيل المثال، يمكن أن يكون وصف إجراء GetInvoice هو الحصول على فاتورة معينة حسب المعرف. سيعثر المنشئون بشكل متكرر على الإجراء عن طريق البحث، لذا فإن الأسماء الوصفية يمكن أن تساعدهم في العثور على الإجراء الصحيح بسرعة.
تظهر الصورة التالية في المكان الذي تُستخدم فيه عناصر الملخص والوصف عند تحديد إجراء أو مشغّل.
بعد تحديد إجراء أو مشغّل، ستكون قادراً على رؤية كل من عناصر الملخص والوصف على كل بطاقة إجراء في المصمم.
في الصور السابقة، لاحظ أن أنماط التسمية غير متناسقة، حيث تحتوي بعض الأسماء على مسافات في الملخص والبعض لا يحتوي. يمكنك إصلاح هذا الخطأ عن طريق تحديث الحقول في المدخل أو، في حالة كان لديك واجهة برمجة التطبيقات (API)، يمكنك أن تطلب من المطور تحديث ما توفره في تعريف OpenAPI الذي تقوم باستيراده. ولكن اعلم أنك إذا قمت بإجراء تغييرات على المدخل يدوياً ثم قمت باستيراد تعريف OpenAPI مرة أخرى، فستتم الكتابة فوق التغييرات التي أجريتها.
رؤية الإجراء
يمكنك ضبط خيار الرؤية لإجراء معين للتحكم في كيفية ظهور الإجراء في تجربة المنشئ.
بلا - يعد هذا هو الخيار الافتراضي. سيظهر الإجراء بشكل عادي.
متقدمة - سيتوفر الإجراء ولكن دون ترتيب الأولوية.
داخلية - سيتم إخفاء الإجراء.
هامة - سيتم ترتيب الأولوية للإجراء وسيظهر أولاً.
على سبيل المثال، إذا قمت باستيراد تعريف OpenAPI باستخدام 10 إجراءات، ولا تريد أن يرى/يستخدم المستخدمون إجراءين منهما في البداية، فيمكنك تحديد خيار داخلية لإخفائهما. هذه الطريقة مفيدة لمعالجة العمليات المستخدمة لدعم بيانات تعريف الموصل الديناميكي. كما يمكنها أيضاً أن تتيح لك إخفاء الإجراءات في البداية ثم جعلها مرئية لاحقاً عند طلب المستخدمين لها. يؤدي إخفاء الإجراءات إلى الاحتفاظ بالقائمة المرئية للمستخدمين بأقل قدر ممكن.
يتم عرض الإجراءات التي تم تحديدها كـ هامة أولاً. يجب على المستخدم تحديد الموصل لإظهار أي إجراءات تم تحديدها كـ بلا أو متقدمة. يفضل استخدام هذا الأسلوب عندما يكون لديك إجراءات عديدة ولا يتم استخدام العديد منها بشكل متكرر.
الطلب
يحدّد الطلب ما المعلمات/البيانات التي سيتم تمريرها إلى العملية عند استدعاء الإجراء للعملية على واجهة برمجة التطبيقات (API). عند استيراد تعريف OpenAPI، فسيقوم بتكوين استعلام الطلب، والرؤوس، وإعدادات النص الأساسي. يمكنك أيضاً الاستيراد يدوياً عن طريق الاستيراد من النموذج.
تظهر الصورة التالية مثالاً لما تبدو عليه الشاشة عندما تنظر إلى التعريف.
هذا التكوين هام لأنه يترجم إلى ما يراه المستخدم عند استخدامه للإجراء.
من خلال تحرير كل معلمة من المعلمات، أو من خلال توفير مطور API لمزيد من التفاصيل، يمكنك تحسين تجربة المستخدم عند استخدام الإجراء. سيؤدي تحديد علامة الحذف (...) في كل معلمة إلى إظهار شاشة التحرير التالية.
الحقول والخيارات التي يجب مراجعتها وتغييرها هي:
الاسم - لا تقم بالتغيير؛ يجب أن يطابق هذا الحقل ما تتوقعه واجهة API.
ملخص - جعل هذا الحقل سهل الاستخدام، على سبيل المثال، إلى تاريخ ستكون إلى تاريخ.
الوصف - يحتوي هذا الحقل على جملة تصف المعلمة. سيستخدم كنص نائب للحقل.
القيمة الافتراضية - هذا الحقل عبارة عن قيمة افتراضية اختيارية، ولكن يجب توفيره إذا قمت بتعيين الرؤية إلى داخلية مع جعل المعلمة مطلوبة.
مطلوب - تأكد من تعيين هذا الخيار إذا كانت واجهة برمجة التطبيقات (API) تتطلب قيمة. يؤدي هذا الخيار إلى تمكين علامة نجمية حمراء مرئية بجوار الحقل.
الرؤية - تعمل هذه المعلمة كخيار الرؤية على الإجراء الذي تمت مناقشته سابقاً. إذا كانت لديك معلمات غير مستخدمة بكثرة، فحدّد الخيار متقدمة.
النوع والتنسيق - تأكد من ملاءمة هذه الحقول لأن المعلمة التي تستورد من النماذج تضع افتراضات ليست صحيحة دائماً.
نوع القائمة المنسدلة - استخدم هذه المعلمة لتكوين قائمة ثابتة أو ديناميكية من القيم للمساعدة على جعل تحديد المستخدم أسهل مع زيادة إمكانية التنبؤ.
تعرض الصورة التالية مثالاً لما ستبدو عليه الشاشة بعد إصلاح معلمة من تاريخ.
الاستجابة
تحدّد الاستجابة ما تتوقع إرجاعه من واجهة برمجة التطبيقات (API). على عكس الطلب، الذي له تعريف واحد فقط، يمكنك الحصول على استجابات مختلفة بناءً على حالة HTTP. على سبيل المثال، إذا قام استدعاء API الخاص بك بإنشاء خطأ، فسيحتوي النص الأساسي على تفاصيل الخطأ بدلاً مما ستقوم واجهة برمجة التطبيقات (API) بإرجاعه. كما يمكن أن يكون لديك أيضاً استجابة افتراضية، وهي استجابة التقاط الكل إذا لم تكن متوفرة لحالة HTTP محددة.
سيؤدي تحديد إحدى الاستجابات إلى كشف التفاصيل، كما يمكنك تحرير هذه العناصر للحصول على استهلاك أسهل، كما هو الحال للعملية التي تتضمن طلباً.
تتوافق العناصر الموجودة في الاستجابة مع ما يظهر في لوحة المحتوى الديناميكي.
بشكل مشابه للطلب، تأكد من أنك قمت بتضمين وأوصاف وأسماء جيدة لأن من شأنها أن تساعد في تسهيل استخدام القيم.
التحقق من الصحة
لاحظ ظهور قسم تحقق من الصحة يشبه الصورة التالية في أسفل الشاشة.
تأكد من عدم ظهور أخطاء بهذه الشاشة، ثم خذ الوقت الكافي لحل المشكلات المدرجة.
الإعدادات الأخرى
هناك أيضًا إعدادات أخرى مثل المشغلات والمراجع والسياسات التي لم يتم تناولها بتعمق في هذه الوحدة.
يمكن تكوين المشغّلات إذا كانت واجهة برمجة التطبيقات (API) تدعم أياً من أحداث التحقق أو الإخطار على الويب. عند تحديد المشغّلات، تتيح لك استخدام الموصل لديك كمشغّل لتدفق Power Automate.
تحدّد المراجع المعلمات القابلة لإعادة الاستخدام ويتم إنشاؤها عادة عندما تقوم باستيراد التعريف ويحدّد المعلمة القابلة لإعادة الاستخدام. يمكن أيضاً صناعة المراجع يدوياً باستخدام محرر swagger المضمن.
يمكن استخدام النُهج لتغيير سلوكيات الإجراءات والمشغّلات. يتم إنشاء النُهج باستخدام أحد قوالب النُهج المنشأة مسبقاً.
تتم تغطية هذه المواضيع المتقدمة بالتفصيل لاحقاً في مسار التعليم هذا.
