مشاركة عبر

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

  • مقالة

ينطبق على: المطور | أساسي | قياسي | بريميوم

يتميز مدخل مطور APIM بمحرر مرئي وعناصر واجهة مستخدم مُضمنة بحيث يمكنك تخصيص مظهر المدخل ونمطه. ومع ذلك، قد تحتاج إلى تخصيص مدخل المطور بشكل أكبر مع وظائف مُخصصّة. على سبيل المثال، قد ترغب في دمج مدخل المطور مع نظام دعم يتضمن إضافة واجهة مُخصصّة. تشرح هذه المقالة طرق إضافة وظائف مخصصة مثل عناصر واجهة المستخدم المخصصة إلى مدخل مطور APIM.

يلخص الجدول التالي خيارين، مع ارتباطات لمزيد من التفاصيل.

الطريقة ‏‏الوصف
عنصر واجهة مستخدم تعليمات HTML البرمجية المخصصة - حل بسيط لناشري واجهة برمجة التطبيقات لإضافة منطق مخصص لحالات الاستخدام الأساسية

- نسخ ولصق تعليمة HTML البرمجية المخصصة في نموذج، ويعرضها مدخل المطور في iframe
إنشاء عنصر واجهة مستخدم مخصص وتحميله - حل المطور لحالات استخدام عنصر واجهة المستخدم الأكثر تقدمًا

- يتطلب التنفيذ المحلي في React أو Vue أو TypeScript عادي

- دعم عنصر واجهة المستخدم والأدوات المقدمة لمساعدة المطورين على إنشاء عنصر واجهة المستخدم وتحميلها إلى مدخل المطور

- يمكن كتابة إنشاء عنصر واجهة المستخدم واختباره ونشره من خلال مصدر مفتوح React Component Toolkit

- يدعم مهام سير العمل للتحكم بالمصادر وتعيين الإصدار وإعادة استخدام التعليمات البرمجية

إشعار

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

استخدام عنصر واجهة مستخدم تعليمات HTML البرمجية المخصصة

يتضمن مدخل المطور المدار عنصر واجهة مستخدم تعليمات HTML البرمجية المخصصة حيث يمكنك إدراج تعليمات HTML البرمجية لتخصيصات المدخل الصغيرة. على سبيل المثال، استخدام HTML المخصص لتضمين فيديو أو لإضافة نموذج. يعرض المدخل عنصر واجهة المستخدم المخصصة في إطار مضمن (iframe).

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

  2. حدد أيقونة "علامة الجمع" الرمادية (+) التي تعرض عند تمرير المؤشر فوق الصفحة.

  3. في نافذة إضافة عنصر واجهة المستخدم، حدد Custom HTML code.

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

  4. تحديد أيقونة "القلم الرصاص" لتخصيص عنصر واجهة المستخدم.

  5. أدخل العرضوالارتفاع(بالبكسل) لأداة.

  6. لتوريث الأنماط من مدخل المطور (مستحسن)، حدد تطبيق تصميم مدخل المطور.

    إشعار

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

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

  7. استبدل النموذج الخاص بالتعليمات البرمجية HTML بالمحتوى المخصص الخاص بك.

  8. عند اكتمال التكوين، أغلق النافذة.

  9. احفظ التغييرات، ثم أعد نشر المدخل.

إشعار

لا تدعم Microsoft تعليمة HTML البرمجية التي تضيفها في عنصر واجهة مستخدم تعليمة HTML البرمجية المخصصة.

إنشاء عنصر واجهة مستخدم مخصص وتحميله

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

المتطلبات الأساسية

إنشاء عنصر واجهة المستخدم

تحذير

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

  1. في الواجهة الإدارية لمدخل المطور، حدد إنشاء عناصر واجهة المستخدم>إنشاء عنصر واجهة المستخدم مخصص جديد.

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

  3. حدد Create widget.

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

    npx @azure/api-management-custom-widgets-scaffolder

  5. انتقل إلى المجلد الذي تم إنشاؤه حديثُا يحتوي على سقالة التعليمات البرمجية الخاصة بواجهة المستخدم.

    cd <name-of-widget>

  6. افتح المجلد في محرر التعليمات البرمجية الذي تختاره، مثل VS Code.

  7. لتثبيت التبعيات وبدء المشروع:

    npm install 
npm start

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

    إشعار

    إذا لم تفتح علامة التبويب، فعليك إجراء ما يلي:

    1. تأكد من بدء تشغيل خادم التطوير. لإجراء ذلك، تحقق من المخرجات على وحدة التحكم حيث بدأت الخادم في الخطوة السابقة. يجب أن يعرض المنفذ الذي يعمل عليه الخادم (على سبيل المثال، http://127.0.0.1:3001).
    2. انتقل إلى خدمة API Management في مدخل Microsoft Azure وافتح مدخل المطور الخاص بك باستخدام الواجهة الإدارية.
    3. إلحاق /?MS_APIM_CW_localhost_port=3001 بعنوان URL. غيّر رقم المنفذ إذا كان الخادم يعمل على منفذ مختلف.

  8. نفذ التعليمات البرمجية لعنصر واجهة المستخدم واختبارها محليًا. يوجد رمز عنصر واجهة المستخدم في المجلد src، في المجلدات الفرعية التالية:

    • app - التعليمات البرمجية لمكوّن عنصر واجهة المستخدم الذي يراه ويتفاعل معه زوار مدخل المطور المنشور
    • editor - التعليمات البرمجية لمكوّن عنصر واجهة المستخدم الذي تستخدمه في الواجهة الإدارية لمدخل المطور لتحرير إعدادات عنصر واجهة المستخدم

    يحتوي الملف values.ts على القيم والأنواع الافتراضية لخصائص عنصر واجهة المستخدم المخصصة التي يمكنك تمكينها للتحرير.

    لقطة شاشة لصفحة الخصائص المخصصة في بوابة المطور.

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

نشر عنصر واجهة المستخدم المخصص إلى مدخل المطور

  1. حدد القيم التالية في الملف deploy.js الموجود في جذر المشروع:

    • resourceId - معرّف المورد لخدمة APIM الخاصة بك، بالتنسيق التالي: subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<api-management service-name>

    • managementApiEndpoint - نقطة نهاية Azure Management API (تعتمد على بيئتك، عادة management.azure.com)

    • apiVersion - اختياري، تستخدم لتجاوز إصدار واجهة برمجة تطبيقات الإدارة الافتراضي

  2. شغّل الأمر التالي:

    npm run deploy

    إذا طُلب منك ذلك، سجل دخولك باستخدام حساب Azure الخاص بك.

    إشعار

    عند مطالبتك بتسجيل الدخول، يجب استخدام حساب عضو من مستأجر معرف Microsoft Entra المقترن باشتراك Azure حيث توجد خدمة API Management. يجب ألا يكون الحساب ضيفا أو حسابا متحدا ويجب أن يكون لديه الإذن المناسب للوصول إلى الواجهة الإدارية للمدخل.

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

النشر لمدخل المطور

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

إشعار

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

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

نحن نقدم قوالب للتقنيات التالية التي يمكنك استخدامها لواجهة المستخدم:

  • TypeScript (تنفيذ خالص دون أي إطار عمل)
  • الرد
  • فيو

تستند جميع القوالب إلى لغة برمجة TypeScript.

يحتوي قالب React على خطافات مخصصة معدة في الملف hooks.ts وموفرين تم إنشاؤهم لمشاركة السياق من خلال شجرة المكون مع خطافات useSecrets وuseValues وuseEditorValues مخصصة.

استخدام الحزمة @azure/api-management-custom-widgets-tools

تحتوي حزمة npm هذه على الوظائف التالية لمساعدتك في تطوير عنصر واجهة المستخدم المخصص وتوفر ميزات بما في ذلك الاتصال بين مدخل المطور وأداة واجهة المستخدم الخاصة بك:

الوظيفة ‏‏الوصف
getValues إرجاع كائن JSON يحتوي على قيم تم تعيينها في محرر عنصر واجهة المستخدم بالإضافة إلى القيم الافتراضية
getEditorValues إرجاع كائن JSON يحتوي على قيم معينة فقط في محرر عنصر واجهة المستخدم
buildOnChange يقبل نوع TypeScript ويرجع دالة لتحديث قيم عنصر واجهة المستخدم. يتم التعامل مع الدالة التي تم إرجاعها كمعلمة كائن JSON بقيم مُحدثة ولا يتم إرجاع أي شيء.

يُستخدم داخليًا في محرر عنصر واجهة المستخدم
askForSecrets إرجاع وعد JavaScript، والذي يقوم بعد الحل بإرجاع كائن JSON من البيانات اللازمة للاتصال بالواجهة الخلفية
deployNodeJs نشر عنصر واجهة المستخدم إلى موقع تخزين الكائن الثنائي كبير الحجم
getWidgetData إرجاع جميع البيانات التي تم تمريرها إلى عنصر واجهة المستخدم المخصص من مدخل المطور

يُستخدم داخليًا في القوالب

@azure/api-management-custom-widgets-tools/getValues

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

Import {getValues} from "@azure/api-management-custom-widgets-tools/getValues" 
import {valuesDefault} from "./values" 
const values = getValues(valuesDefault)

يهدف إلى استخدامه في جزء وقت التشغيل (app) من عنصر واجهة المستخدم الخاص بك.

@azure/api-management-custom-widgets-tools/getEditorValues

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

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

@azure/api-management-custom-widgets-tools/buildOnChange

إشعار

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

يقبل نوع TypeScript ويرجع دالة لتحديث قيم عنصر واجهة المستخدم. يتم التعامل مع الدالة التي تم إرجاعها كمعلمة كائن JSON بقيم مُحدثة ولا يتم إرجاع أي شيء.

import {Values} from "./values"
const onChange = buildOnChange<Values>()
onChange({fieldKey: 'newValue'})

@azure/api-management-custom-widgets-tools/askForSecrets

تقوم هذه الدالة بإرجاع وعد JavaScript، والذي يقوم بعد الحل بإرجاع كائن JSON من البيانات اللازمة للاتصال بالواجهة الخلفية token مطلوب للمصادقة. userId مطلوب للاستعلام عن الموارد الخاصة للمستخدم. قد تكون هذه القيم غير معرفة عند عرض المدخل من قبل مستخدم مجهول. Secretsيحتوي الكائن أيضًا على managementApiUrl، وهو عنوان URL للواجهة الخلفية لمدخلك، وapiVersion، وهو apiVersion المُستخدم حاليًا من قبل مدخل المطور.

تنبيه

يمكنك إدارة الرمز المميز واستخدامه بعناية. يمكن لأي شخص يمتلكه الوصول إلى البيانات في خدمة APIM.

@azure/api-management-custom-widgets-tools/deployNodeJs

تنشر هذه الدالة عنصر واجهة المستخدم الخاص بك إلى موقع تخزين الكائن الثنائي كبير الحجم الخاص بك. في جميع القوالب، تم تكوينه مسبقًا في الملف deploy.js.

يقبل ثلاث وسيطات بشكل افتراضي:

  • serviceInformation – معلومات حول خدمة Azure:

    • resourceId - معرّف المورد لخدمة APIM الخاصة بك، بالتنسيق التالي: subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<api-management service-name>

    • managementApiEndpoint - نقطة نهاية Azure Management API (تعتمد على بيئتك، عادة management.azure.com)

  • معرف عنصر واجهة المستخدم الخاص بك - اسم عنصر واجهة المستخدم الخاص بك بتنسيق "PC-friendly" (الأحرف الصغيرة الأبجدية الرقمية اللاتينية والشرطات، Contoso widget يصبح contoso-widget). يمكنك أن تجده في package.json ضمن المفتاح name.

  • fallbackConfigPath - مسار الملف المحلي config.msapim.json، على سبيل المثال، ./static/config.msapim.json

@azure/api-management-custom-widgets-tools/getWidgetData

إشعار

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

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

  • values - جميع القيم التي قمت بتعيينها في المحرر، نفس الكائن الذي يتم إرجاعه بواسطة getEditorData
  • instanceId - معرّف هذا المثيل من عنصر واجهة المستخدم

إضافة خصائص مخصصة أو إزالتها

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

تحذير

لا تخزن القيم السرية أو الحساسة في خصائص مخصصة.

لإضافة خاصية مخصصة:

  1. في الملف src/values.ts، أضف إلى نوع Values اسم الخاصية ونوع البيانات التي ستحفظها.
  2. في نفس الملف، أضف قيمة افتراضية له.
  3. انتقل إلى الملف editor.html أو editor/index (يعتمد الموقع الدقيق على إطار العمل الذي اخترته) وتكرار إدخال موجود أو إضافة إدخال بنفسك.
  4. تأكد من أن حقل الإدخال يبلغ عن القيمة التي تم تغييرها إلى الدالة onChange ، والتي يمكنك الحصول عليها من buildOnChange.

(اختياري) استخدام إطار عمل آخر

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

  • في معظم الحالات، نوصي بالبدء من قالب TypeScript.
  • ثبت التبعيات كما هو الحال في أي مشروع npm آخر.
  • إذا كان إطار العمل الذي تختاره غير متوافق مع أداة بناء Vite، فكوّنه بحيث يقوم بإخراج الملفات المحولة برمجيًا إلى المجلد ./dist. اختياريًا، إعادة تعريف مكان وجود الملفات المحولة برمجيًا عن طريق توفير مسار نسبي كوسيطة رابعة للدالة deployNodeJs.
  • للتطوير المحلي، يجب أن يكون الملف config.msapim.json قابلاً للوصول إلى عنوان URL localhost:<port>/config.msapim.json عند تشغيل الخادم.

إنشاء عناصر واجهة مستخدم مخصصة باستخدام مجموعة أدوات مكون مصدر مفتوح React

يوفر مصدر مفتوح React Component Toolkit مجموعة من البرامج النصية لحزمة npm لمساعدتك في تحويل تطبيق React إلى إطار عمل عنصر واجهة المستخدم المخصص واختباره ونشر عنصر واجهة المستخدم المخصص إلى مدخل المطور. إذا كان لديك حق الوصول إلى خدمة Azure OpenAI، يمكن لوحة الأدوات أيضا إنشاء عنصر واجهة مستخدم من وصف نصي توفره.

حاليا، يمكنك استخدام مجموعة الأدوات بطريقتين لنشر عنصر واجهة مستخدم مخصص:

  • يدويا، عن طريق تثبيت مجموعة الأدوات وتشغيل البرامج النصية لحزمة npm محليا. يمكنك تشغيل البرامج النصية بشكل تسلسلي لإنشاء مكون React واختباره ونشره كعنصر واجهة مستخدم مخصص إلى مدخل المطور.
  • استخدام قالب Azure Developer CLI (azd) للنشر الشامل. ينشر القالب azd مثيل إدارة واجهة برمجة تطبيقات Azure ومثيل Azure OpenAI. بعد توفير الموارد، يساعدك البرنامج النصي التفاعلي على إنشاء عنصر واجهة مستخدم مخصص واختباره ونشره في مدخل المطور من وصف توفره.

إشعار

مجموعة أدوات مكون React وقالب نموذج Azure Developer CLI هما مصدر مفتوح المشاريع. يتم توفير الدعم فقط من خلال مشكلات GitHub في المستودعات المعنية.

المحتوى ذو الصلة

تعرف على المزيد حول مدخل المطور: