السابق

التالي

مشغل خطاف الويب

مكتمل

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

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

تعرض لقطة الشاشة التالية مثالاً للتفاعل بين المشترك والناشر.

يتم توضيح مسؤوليات الأطراف في الجدول التالي.

الناشر (موصل OpenAPI مخصص)	المشترك (Power Automate/التطبيقات المنطقية)
توفير نقطة نهاية تسجيل الاشتراك.	استدعاء نقطة نهاية تسجيل الاشتراك عند إنشاء مشغل أو تحديثه في أحد التدفقات.
تحديد عقد الإخطار، أي الكائن الذي سيتم تمريره مع كل إخطار. يجب تضمين عنوان HTTP للموقع في الرد 201 في الوقت الذي يتم فيه إنشاء خطاف الويب.	توفير URL لنقطة النهاية التي تم إنشاؤها تلقائيًا والتي ستقبل رسائل الإخطار.
الاحتفاظ بتسجيل المشتركين ونقاط نهاية الإخطار الخاصة بهم.	تلقي معلومات الموقع التي ستستخدم لإلغاء تسجيل خطاف الويب وتخزينها.
إصدار طلب "نشر" لكل نقطة نهاية مسجلة وتمرير البيانات ذات الصلة في نص الرسالة.	تلقي إخطارات والتحقق من صحتها مقابل المخطط الذي حدده الموصل المخصص، ثم تشغيل الأتمتة.
إلغاء تسجيل/إزالة نقاط النهاية استجابة لرسالة "حذف".	إصدار رسالة "حذف" لإعادة تسجيل خطاف الويب عند حذف خطوة المشغل.

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

متطلبات API

لتوفير دعم خطاف الويب المطلوب من قبل الموصلات المخصصة، يجب أن يوفر تنفيذ API المعلمات التالية:

• نقطة نهاية تقبل رسالة التسجيل وترجع معلومات الموقع

• تعريف لنص الرسالة الذي يتم إرساله مع رسائل الإخطار

• نقطة نهاية لقبول رسالة "حذف" لإزالة تسجيل خطاف الويب

عادةً، يحتفظ تنفيذ API بقائمة داخلية للمشتركين النشطين، حيث يتم تعريف كل مشترك بواسطة عنوان URL فريد. لإرجاع عنوان URL هذا إلى المشترك، يجب إنشاء خطاف الويب الناجح لإرجاع رد HTTP 201 وتضمين رأس HTTP للموقع. سيستخدم المشترك قيمة هذا الموقع لاحقاً لحذف تسجيل خطاف الويب.

إنشاء مشغل خطاف الويب

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

• رسالة "نشر" التي تصف تسجيل خطاف الويب

• تعريف المحتوي لردود خطاف الويب

• رسالة "حذف" التي تصف عملية إنهاء حدث خطاف الويب

رسالة التسجيل

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

إصدار مواصفات OpenAPI التي يستخدمها Microsoft Power Platform لا يفرِّق بين الإجراءات والمشغلات. يستخدم تعريف الموصل المخصص الملحق المخصص لـ x-ms-trigger لإعلان أحد المشغلات.

paths:
  /webhooks:
    post:
      operationId: OrderCreated
      x-ms-trigger: single

ويشير وجود الملحق x-ms-trigger إلى أن الطريقة هي مشغل وليست إجراء. عند إنشاء مشغل باستخدام المعالج، تتم إضافة هذا الملحق تلقائيًا. ومع ذلك، فعند إنشاء موصل مخصص من تعريفات OpenAPI الخارجية، تقوم عملية الاستيراد دائماً بإنشاء إجراءات. في هذا السيناريو، تحتاج إلى إعادة إنشاء المشغلات باستخدام المعالج ثم إزالة تعريفات الإجراء المطابقة.

القيم المحتملة لملحق x-ms-trigger تكون مفردة أو في مجموعة للتمييز بين استجابتي الكائن والمصفوفة. يتم تضمين كائن مفرد عندما يقوم خطاف الويب برفع إخطار لكل تغيير. يعد هذا الأسلوب هو الأكثر شيوعًا مع خطافات الويب. عند دمج عدة تغييرات في إخطار واحد، يتم إرسال مصفوفة من الكائنات. ويستخدم هذا الأسلوب عادة في مشغلات الاستقصاء وستتم مناقشته لاحقًا في الوحدة النمطية.

الاستجابة لخطاف الويب

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

ملاحظة

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

خاصية محتوى إخطار x-ms المخصصة هي ملحق آخر يستخدم في OpenAPI لتحديد مخطط رد خطاف الويب.

paths:
  /webhooks:
    x-ms-notification-content:
      description: Order
      schema:
        type: object
        properties:
          id: {type: integer, format: int32, description: id}
          order_key: {type: string, description: order_key}
          status: {type: string, description: status}
          currency: {type: string, description: currency}
          date_created: {type: string, description: date_created}
          total: {type: number, description: total, format: decimal}

تلميح

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

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

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

حذف الرسالة

بالنسبة لـ Power Automate أو "التطبيقات المنطقية" لحذف خطاف الويب، يجب أن تتضمن API عنوان HTTP للموقع كرد في الوقت الذي يتم فيه إنشاء خطاف الويب.

هام

يجب تحديد مسار طلب خطاف الويب للحذف كإجراء داخلي. سيقوم هذا الاجراء بإرسال طلب "حذف" إلى عنوان URL المحدّد في عنوان الموقع.

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

يقدم تنفيذ خطافات الويب آلية مرنة لتوفير دعم المشغل في موصل مخصص. ومع ذلك، لا تدعم كل API تكاملات خطاف الويب. يقدم تنفيذ الاستقصاء طريقة بديلة لإنشاء المشغلات في الموصلات المخصصة.

متابعة