استخدام المخطط الديناميكي
عندما تقوم بتكوين إجراء عَلى موصل مخصص، يمكنك أيضاً تكوين معلمات. يتم تكوين هذه المعلمات عن طريق استيراد إما تعريف OpenAPI أو عينة طلب. بصرف النظر عن الأسلوب المستخدم، فقائمة المعلمات ثابتة. عند استخدام هذا الإجراء، سيتم تقديم قائمة ثابتة للمنشئ بالمعلمات كما هي معرفة بواسطة الموصل. بالنسبة إلَى العديد مِن السيناريوهات، هذا الأسلوب مناسب لأن قائمة المعلمات ثابتة ولا تتغيّر. في بعض الحالات، تكون المعلمات التي يجب أن يتم تقديمها للإدخال متغيّرة.
أكثر حالات الاستخدام شيوعاً هي:
تختلف قائمة المعلمات استناداً إلَى نوع معيّن، مثل فئة أو نوع فاتورة.
يمكن أن تحدّد حالة السجل المعلمات التي يمكن تغييرها. على سبيل المثال، يمكن أن يتضمن أمر تم شحنه معلمات متاحة مختلفة عن أمر لم يتم شحنه.
يمكن أن يتم اقتطاع قائمة المعلمات بسبب الأمان.
عملية شائعة لتنفيذ الإجراءات فِي بضعة أنواع مختلفة مِن البيانات. على سبيل المثال، قد تنفذ API إجراء إنشاء الذي ينطبق عَلى الحسابات أو جهات الاتصال أو الأوامر أو الفواتير. سيتم تعريف معلمات الإدخال مِن خلال نوع الكائن الذي يحدده المنشئ.
تدعم الموصلات المخصصة هذه السيناريوهات بالسماح لك بتكوين ملحقات OpenAPI للمخطط الديناميكي. عند تكوين ملحقات OpenAPI للمخطط الديناميكي، سيستدعي وقت تشغيل الموصل عملية لاسترداد المخطط الذي يعرّف المعلمات التي يجب أن تكون ظاهرة لهذا الإجراء. يمكن أن تشمل بيانات المخطط خيارات أخرى، مثل اسم العرض ووصف المعلمة.
في مثال Contoso Invoicing API، بعد أن تم استيراد تعريف OpenAPI، كان الإجراء يشبه الصورة التالية عندما تم استخدامه فِي تدفق Power Automate.
تعرض الصورة السابقة المعلمات غير المناسبة لإضافة فاتورة أمر شراء مقابل فاتورة لغير أمر شراء. بالإضافة إلَى ذلك، ليست جميع حقول الفاتورة إدخالاً سارياً لإنشاء فاتورة. على سبيل المثال، createDate حقل يتم تعيينه بواسطة API ومن المفترض ألا يكون جزءاً مِن إدخال المستخدم. بعد تنفيذ القيم الديناميكية لرقم تعريف نوع الفاتورة والمخطط الديناميكي للمعلمات الأخرى، سيبدو الإجراء كالصورة التالية.
عندما يغيّر المنشئ نوع الفاتورة مِن أمر شراء إلَى غير أمر شراء، يتم إخفاء معلمة أمر الشراء أو عرضها كما يلزم.
يدعم وقت تشغيل الموصل المخصص ملحقَين مختلفَين يمكن استخداهاما لتكوين المخطط الديناميكي. يحقق الاثنان الهدف نفسه، حيث يكون الملحق x-ms-dynamic-schema هو الإصدار 1 وx-ms-dynamic-properties هو الإصدار 2. إذا كنت تحتاج إلَى دعم عمليات التدفق الأقدم باستخدام إجرائك، يمكنك تكوين كلا الإصدارَين عَلى الموصل المخصص. إذا كنت تدعم عمليات التدفق الجديدة فقط، يمكنك تكوين الملحق x-ms-dynamic-properties فقط.
دعم API
حتى تتمكن مِن تكوين المخطط الديناميكي، يجب أن توفر API الأساسية الدعم مِن خلال تعريف العملية التي تعرض المخطط. في حالة عدم وجود إجراء مناسب بالفعل فِي API، وليس لديك إمكانية تعديل API أو طلب التغييرات، قد لا تتمكن مِن تنفيذ المخطط الديناميكي.
يمكن أن تحتاج العملية التي تعرض المخطط معلمة واحدة أو أكثر يتم تمريرها مِن وقت تشغيل الموصل المخصص. هذه المعلمات يمكن أن تكون ثابتة أو يمكن أن تمثل بيانات أخرى يتم جمعها فِي بطاقة الإجراء. هذه البيانات يمكن استخدامها مِن جانب API لتصفية قائمة المعلمات التي يتم عرضها كجزء مِن المخطط. في المثال السابق، يتم تمرير نوع الفاتورة كمعلمة إلَى العملية للحصول عَلى المخطط الديناميكي.
يجب أن تكون الاستجابة مِن العملية المستخدمة للمخطط الديناميكي مخطط JSON صالحاً. يعرض المثال التالي ما تعرضه Contoso API GetInvoiceSchema.
يُرجى ملاحظة النقاط الرئيسية التالية حول المحتوى:
يجب توفير النوع ويجب استخدامه لتحديد نوع بيانات المعلمة.
يتم استخدام الملخص والوصف فِي مصمم Power Automate لتحديد المعلمات للمنشئ.
يمكن توفير خاصية ملحق x-ms-visibility للإشارة إلَى المكان الذي تعتقد أنه يجب دائماً عرض هذه المعلمة فيه (القيمة "هام") أو إذا كان إجراء المستخدم مطلوباً للكشف عنه إلَى المنشئ، مثل تحديد الارتباط المتقدم عَلى بطاقة التدفق (القيمة "متقدم"). وبما أن هذه المعلومات يتم استردادها ديناميكياً، يمكن أن تختلف اعتماداً عَلى معلومات السياق المتاحة.
توفر المصفوفة المطلوبة قائمة بالمعلمات المطلوبة.
تكوين ملحق المخطط الديناميكي
لتكوين الملحقين x-ms-dynamic-schema أو x-ms-dynamic-properties يجب تحرير تعريف OpenAPI للموصل المخصص بشكل مباشر. في الوقت الحالي، لا يتوفر دعم لمصمم الموصل المخصص مِن أجل تحرير هذه القيم.
تعرض الصورة التالية كيف بدا تكوين معلمة AddInvoice بعد استيراد تعريف OpenAPI الذي وفرته API.
يوضح المثال السابق أن AddInvoice تتلقى كائن CreateInvoiceRequest كإدخال. يتم تعريف الخصائص مِن خلال الإشارة #/التعريفات/الفاتورة، وهي تعريف مشترك لكل خصائص الفاتورة.
لتنفيذ الاستدعاء لملحق المخطط الديناميكي، يمكنك استبدال الخصائص بالملحق المكون.
بدلاً مِن استخدام قائمة خصائص مضمنة فِي التعليمة البرمجية، سيتم استدعاء العملية GetInvoiceSchema للحصول عَلى القائمة استناداً إلَى المعلمة typeId.
من خلال تنفيذ المخطط الديناميكي عَلى الموصل المخصص، يمكنك أن توضح للمنشئ المعلمات التي يجب استخدامها للإجراء.