مقدمة

مكتمل

تسمح لك الموصلات المخصصة بتنفيذ موصل للخدمَات غير المتوفرة فِي الموصلات التي تم إنشَاؤهَا مسبقًا فِي Microsoft Power Platform. يمكن للمطورين استخدَام تعليمة برمجية مخصصة لتنفيذ تحويل متقدم لإدخَال وإخرَاج إجرَاءَات الموصل.

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

قوالب السيَاسَات

يمكن لتعريفات إجرَاء المُوصِّل تنفيذ تحويل أسَاسي بدون تعليمة برمجية للطلب والاستجَابة للخدمة، من خلال تطبيق قوالب سيَاسة الموصل المخصصة. على سبيل المثَال، يمكن أن تنفذ قوالب السيَاسَات الأنواع التَالية من التحويلات:

• تحويل بيَانات الطلب أو الاستجَابة من كَائن إلى صفيف.

• تحويل بيَانات الطلب أو الاستجَابة من صفيف إلى كَائن.

• تعيين عنوان URL المضيف للطلب.

• تعيين قيم عنوان HTTP للطلب.

• تعيين قيمة الخَاصية فِي الطلب أو الاستجَابة.

• تعيين معلمَات سلسلة استعلام البحث.

يمكنك استخدَام قوالب سيَاسة متعددة معًا لتحويل الطلب والاستجَابة. عندمَا تقوم بإعدَاد قوالب متعددة، ستقوم أيضًا بتحرير الترتيب للتحكم فِي تسلسل تطبيق السيَاسة.

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

تنفيذ التعليمة البرمجية المخصصة

لتنفيذ التعليمَات البرمجية المخصصة، ستحتَاج إلى إنشَاء فئة باسم Script، التي يجب أن ترث الفئة الأسَاسية المجردة ScriptBase. تحدد فئة ScriptBase طريقة مجردة واحدة، وهي ExecuteAsync، التي تحتَاج إلى تنفيذهَا فِي فئة Script لتنفيذ التعليمَات البرمجية المخصصة بنجَاح فِي الموصل. من المتوقع أن يكون أسلوب ExecuteAsync هو التنفيذ الكَامل لأي تحويل واستدعَاء للخدمة الأسَاسية.

يوضح المثَال التَالي فئة تنفذ العناصر المطلوبة:

public class Script : ScriptBase
{
    public override Task<HttpResponseMessage> ExecuteAsync()
    {
        // Your code here
    }
}

يجب أن يوفر أسلوب ExecuteAsync التنفيذ الكَامل لأي تحويل واستدعَاء الخدمة الأسَاسية. في المثَال التَالي، لم يتم استدعَاء الخدمة الأسَاسية، وستكون كل استجَابة عبارة عن كَائن يحتوي عَلى خَاصية ترحيب تم تعيينهَا إلى "Hello World!"

public override async Task<HttpResponseMessage> ExecuteAsync()
{
    // Create a new response
    var response = new HttpResponseMessage();

    // Set the content
    // Initialize a new JObject and call .ToString() to get the serialized JSON
    response.Content = CreateJsonContent(new JObject
    {
        ["greeting"] = "Hello World!",
    }.ToString());

    return response;
}

لاستدعَاء الخدمة الأسَاسية، ستستخدم أسلوب SendAsync فِي كَائن context. لا يقوم أسلوب ExecAsync التَالي بإجرَاء أي تحويلات ولكنه يعيد توجيه الطلب إلى الخدمة الأسَاسية، ثم يعيد الاستجَابة دون تغيير.

public override async Task<HttpResponseMessage> ExecuteAsync()
{
    HttpResponseMessage response = await this.Context.SendAsync(this.Context.Request, this.CancellationToken).ConfigureAwait(continueOnCapturedContext: false);
    return response;
}

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

إنشَاء تعليمة برمجية مخصصة للعمليَات

يمكنك تمكين تعليمة برمجية مخصصة لموصل ثم تحميل ملف cs. أو csx. صَالح يحتوي عَلى التعليمة البرمجية. يمكنك فقط توفير فئة برنامج نصي واحدة للموصل، ويجب أن يتعَامل مع الإجرَاءَات التي تم إعدَادهَا للموصل. للقيَام بذلك، افحص OperationId من كَائن Context لتحديد مَا إذا كنت تريد تحويل التعليمة البرمجية أو إعَادة توجيههَا إلى الخدمة الأسَاسية. يوضح المثَال التَالي هَذه الخطوة فِي العمل.

  if (this.Context.OperationId != "CreateProduct")
  {
     return await this.HandleForwardOperation().ConfigureAwait(false);
  } 

في هَذا المثَال، تتم إعَادة توجيه أي إجرَاء بخلاف CreateProduct بدون تحويل. يضمن هَذا الأسلوب أنه فِي حَالة إعدَاد إجرَاءَات غير متوقعة لتشغيل التعليمَات البرمجية، تتم إعَادة توجيههَا ولا يتم تحويلهَا.

يمكنك أيضًا التحكم فِي العمليَات التي يعمل عليهَا الرمز المخصص عن طريق تعيينه للتشغيل لعمليَات محددة. بشكل افترَاضي، بعد تمكين التعليمَات البرمجية، ستقوم جميع العمليَات بتشغيل التعليمَات البرمجية المخصصة. تُظهر الصورة التَالية أن AddInvoice وGetInvoice فقط تشغلان التعليمَات البرمجية المخصصة.

إذا كنت تبحث عن هَذه القيم فِي موصل تم تصديره، فستجدهَا مخزنة فِي ملف apiProperties.json.

"scriptOperations": [
      "AddInvoice”,
      "GetInvoice”
    ],

تأكد من أن اختيَارك للعمليَات التي تقوم بتشغيل التعليمَات البرمجية المخصصة تطَابق توقعَات الفحوصَات الشرطية الموجودة فِي التعليمَات البرمجية الخَاصة بك. إذا لم تتم مزَامنتهمَا، فمن الشَائع عدم تشغيل التعليمَات البرمجية المخصصة أو مواجهة أخطَاء غير متوقعة. إذا واجه الموصل أخطَاء، فتحقق من تعريف الموصل، وتتوقع التعليمَات البرمجية للبرنامج النصي أن تتم معَالجة العمليَات نفسهَا.

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