إنشاء خُطافات الويب وإدارتها

خطاف الويب هو آلية تسمح للتطبيق بتقديم تطبيقات أخرى بمعلومات مستندة إلى الحدث. بصفتك مسؤول بوابة ArcGIS Enterprise يمكنك إنشاء خطافات ويب وإدارتها وتهيئتها. يمكنك تهيئة خطافات الويب الخاصة بك بحيث تخطرك تلقائيا عند وقوع أحداث مرتبطة بعناصر بوابتك ومجموعاتها ومستخدميها. بمجرد تشغيل خطاف النت ينشأ طلب HTTP إلى عنوان URL الخاص بالحمولة لتقديم معلومات عن الحدث.

المصطلحات الأساسية

فيما يلي المصطلحات الأساسية لخطاف الويب:

• الحدث المُشغِّل —العملية التي تضبطها لتشغيل خطاف الويب الخاص بك. على سبيل المثال، يمكنك تكوين خطاف الويب الخاص بك لتشغيله عند تحديث مجموعة بعينها في مؤسستك أو عند مشاركة عنصر ما. يمكن أن يكون في خطاف النت أكثر من حدث مشغل واحد.
• الحمولة—هي بيانات حدث التشغيل المنقولة بواسطة خطاف الويب الخاص بك بعد وقوع حدث معين. تكون المعلومات في تنسيق JSON. راجع قسمالحمولات أدناه لمزيد من المعلومات.
• عنوان URL الخاص بالحمولة—هو المكان الذي سيتم منه إرسال الحمولة. يمكن إنشاء عنوان URL الخاص بالحمولة باستخدام خدمة مثل Microsoft Power Automate، أو Zapier، أو IFTTT. يمكنك أيضًا إنشاء نقطة نهاية خدمة الويب المخصصة الخاصة بك باستخدام نظام أساسي من اختيارك.

مثال على حالة استخدام

سوف تتيح خطافات الويب تكاملا لسير العمل عبر الأنظمة، وهناك العديد من الطرق للاستفادة من خطافات الويب في مؤسستك.

مراقبة النشاط في ArcGIS Enterprise

يمكن استخدام خطاف الويب لمراقبة النشاط في ArcGIS Enterprise. على سبيل المثال، يمكنك الاشتراك في كل الأحداث المرتبطة بعنصر معين. يتم تشغيل خطاف الويب عند تحديث خصائص العنصر وعندما يوصِّل طلب HTTPS الحمولة التي تحتوي على بيانات تصف الحدث. أنت من يحدد متى يتم توصيل هذه الحمولة ويمكنك العمل بناء على ذلك فور استلام المعلومات.

أحداث مشغلات مدعومة

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

العناصر

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

يدرج الجدول التالي أحداث المشغلات لعناصر البوابة المدعومة التي تشتمل على خرائط الويب وتطبيقات الويب والطبقات والحزم ومستندات PDF وما شابه:

حَدَث المُشغِّل	مثال عنوان URI
كل أحداث المشغلات لكل العناصر	/items
تمت إضافة عنصر العضو إلى البوابة	/items/add
تم حذف أي عنصر	/items/delete
تم تحديث أي عنصر	/items/update
يتم نقل أي عنصر أو تغيير ملكيته	/items/move
تم نشر أي عنصر	/items/publish
تمت مشاركة أي عنصر	/items/share
تم إلغاء مشاركة أي عنصر	/items/unshare
أُعيد تعيين ملكية أي عنصر	/items/reassign
كل أحداث المشغلات لعنصر مخصوص	/items/<itemID>
تم حذف عنصر محدد	/items/<itemID>/delete
تم تحديث خصائص عنصر محدد	/items/<itemID>/update
تم تغيير ملكية عنصر محدد أو نقل العنصر	/items/<itemID>/move
تم نشر عنصر محدد	/items/<itemID>/publish
تمت مشاركة عنصر محدد	/items/<itemID>/share
تم إلغاء مشاركة عنصر محدد	/items/<itemID>/unshare
أُعيد تعيين ملكية عنصر محدد	/items/<itemID>/reassign

المجموعات

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

يدرج الجدول التالي أحداث المشغل المرتبطة بالمجموعات:

حَدَث المُشغِّل	مثال عنوان URI
كل أحداث المشغلات لكل المجموعات	/groups
تمت إضافة مجموعة	/groups/add
تم تحديث أي مجموعة	/groups/update
تم حذف أي مجموعة	/groups/delete
تم تمكين الحماية ضد الحذف لأي مجموعة	/groups/protect
تم تعطيل الحماية ضد الحذف لأي مجموعة	/groups/unprotect
تمت دعوة مستخدم إلى أي مجموعة	/groups/invite
تمت إضافة مستخدم إلى أي مجموعة	/groups/addUsers
تمت إزالة مستخدم إلى أي مجموعة	/groups/removeUsers
تم تحديث دور مستخدم في أي مجموعة	/groups/updateUsers
أُعيد تعيين ملكية أي مجموعة	/groups/reassign
كل أحداث المشغلات لمجموعة محددة	/groups/<groupID>
تم تحديث مجموعة معينة	/groups/<groupID>/update
تم حذف مجموعة معينة	/groups/<groupID>/delete
تم تمكين الحماية ضد الحذف لمجموعة معينة	/groups/<groupID>/protect
تم تعطيل الحماية ضد الحذف لمجموعة معينة	/groups/<groupID>/unprotect
تمت دعوة مستخدم إلى مجموعة معينة	/groups/<groupID>/invite
تمت إضافة مستخدم إلى مجموعة معينة	/groups/<groupID>/addUsers
تمت إزالة مستخدم من مجموعة معينة	/groups/<groupID>/removeUsers
تم تحديث دور مستخدم في مجموعة معينة	/groups/<groupID>/updateUsers
أُعيد تعيين ملكية مجموعة معينة	/groups/<groupID>/reassign

المستخدمين

يتم تشغيل حدث التحديث في أي وقت يقع فيه تغيير لملف المستخدم التعريفي. ومع ذلك فإن التغييرات التي حدثت لدور المستخدم أو نمطه أو رخصته لا تُعتبر تحديثًا لملف المستخدم التعريفي.

يدرج الجدول التالي أحداث المشغل المرتبطة بالمستخدمين:

حَدَث المُشغِّل	مثال عنوان URI
جميع أحداث المشغل لكل المستخدمين في البوابة	/users
تمت إضافة مستخدم إلى المؤسسة	/users/add
تم تسجيل دخول أي مستخدم إلى البوابة	/users/signin
تم تسجيل خروج أي مستخدم إلى البوابة	/users/signout
تم حذف أي مستخدم	/users/delete
تم تحديث ملف تعريف أي مستخدم	/users/update
تم تعطيل حساب أي مستخدم	/users/disable
تم تمكين حساب أي مستخدم	/users/enable
تم تعيين دور جديد لأي مستخدم	/users/updateUserRole
تم تعيين نوع مستخدم جديد لأي مستخدم	/users/updateUserLicenseType
كل أحداث المشغلات لمستخدم مخصوص	/users/<username>
تم تسجيل دخول مستخدم محدد إلى البوابة	/users/<username>/signIn
تم تسجيل خروج مستخدم محدد من البوابة الإلكترونية	/users/<username>/signOut
تم حذف مستخدم معين	/users/<username>/delete
تم تحديث ملف تعريف مستخدم معين	/users/<username>/update
تم تعطيل حساب مستخدم معين	/users/<username>/disable
تم تمكين حساب مستخدم معين	/users/<username>/enable
تم تعيين دور جديد لمستخدم معين	/users/<username>/updateUserRole
تم تعيين نوع مستخدم جديد لمستخدم معين	/users/<username>/updateUserLicenseType

الأدوار

يتم تشغيل حدث تحديث في أي وقت يقع فيه تغيير لأدوار المؤسسة.

يدرج الجدول التالي أحداث المشغل المرتبطة بأدوار المستخدم:

حَدَث المُشغِّل	مثال عنوان URI
جميع أحداث المشغل لكل الأدوار في البوابة	/roles
تم إنشاء دور جديد.	/roles/add
تم تحديث دور موجود	/roles/updated
تم حذف دور موجود	/roles/delete

حمولات

بمجرد تشغيل خطاف الويب، يتم توصيل الحمولة إلى عنوان URL تنسيق الحمولة المخصوص في تنسيق JSON. يتبع كل حدث مخطط JSON مشابهًا مع معلومات متصلة بالحادث.

مفتاح	النوع	الوصف
webhookName	سلسلة	اسم خطاف الويب الذي وصَّلَ الحمولة.
webhookId	سلسلة	معرّف خطاف الويب الذي وصَّلَ الحمولة.
portalURL	سلسلة	عنوان URL البوابة الذي تم تسجيل خطاف الويب لها.
when	timestamp	الوقت الذي تم فيه توصيل الحمولة.
username	سلسلة	المستخدم الذي شغَّل الحدث.
userId	سلسلة	معرّف المستخدم الذي شغَّل الحدث.
when	timestamp	الوقت الذي وقع فيه الحدث.
operation	سلسلة	العملية التي أدَّاها المستخدم. يمكن أن يكون هذا ما يلي: add addUsers delete disable enable invite move protect publish removeUsers share unprotect unshare update updateUsers
source	سلسلة	نمط المستخدم الذي تمت تأدية العملية عليه. ويمكن أن يكون item، أو group، أو user.
id	سلسلة	معرّف عنصر المصدر الذي تمت تأدية العملية عليه.
properties	كائن	الخصائص الإضافية المرتبطة بالحدث. يمكن أن يكون هذا ما يلي: sharedToGroups—كيف تتم مشاركة عنصر (معرِّف المجموعة، أو المؤسسة، أو الجميع) unsharedFromGroups—كيفية إلغاء مشاركة عنصر (مُعرِّف المجموعة، أو المؤسسة، أو الجميع) removeUserNames—إزالة أسماء المستخدمين الخاصة بالمستخدمين من مجموعة updateUserNames—أسماء المستخدمين الخاصة بالمستخدمين الذين تم تحديث أدوار مجموعتهم. invitedUserNames—أسماء المستخدمين الخاصة بالمستخدمين المدعوين للانضمام إلى مجموعة. addedUserNames—أسماء المستخدمين الخاصة بالمستخدمين الذين تمت إضافتهم إلى مجموعة userRoleUpdatedTo—الدور الجديد الذي تم تعيينه إلى المستخدم reassignedTo—المستخدم الجديد الذي أعيد تعيين عنصر أو مجموعة له userLicenseTypeUpdatedTo—نوع المستخدم الجديد الذي تم تعيينه إلى المستخدم name—اسم الدور الذي تم إنشاؤه أو تحديثه أو حذفه

عنوان URL الخاص بالحمولة

يجب تقديم عنوان URL الخاص بالحمولة بواسطة المستخدم عند إنشاء خطاف الويب؛ ويعرِّف هذا مكان توصيل الحمولة. حيث يتم توصيل الحمولة عبر طلب HTTPS POST، ينبغي تهيئة مستلم خطاف الويب بحيث يتواصل عبر HTTPS وبحيث يمكن الوصول إليه عبر البوابة الإلكترونية. يمكنك استخدام خدمات ويب متعددة مثل Microsoft Power Automate، وZapier، وIFFT، لتكوين عمليات سير عمل مخصصة مع حمولتك. على سبيل المثال، يمكنك إنشاء سير عمل بحيث أنه عندما يستقبل Microsoft Power Automate حمولة فإنه يوزع الحمولة وينسقها ثم يرسلها إلى اسم مستعار لبريد إلكتروني. أو يمكنك بناء خدمة الويب الخاصة بك وتخصيصها لاستقبال الحمولات. وبالنسبة إلى المؤسسات التي تقيد الوصول إلى الإنترنت، فإن من المستحسن بناء خدمة ويب مخصصة لتلقي الحمولات. راجع عينات Enterprise SDK لدينا لمحرك Java servlet الجاهز للاستخدام.

مثال على الحمولة

فيما يلي عينة حمولة تشرح أن مجموعة بعينها قد تم تحديثها:

{
   "info": {
      "webhookName": "Group monitoring",
      "webhookId": "72fed926aeb74c9ca8a22aacddc6725a",
      "portalURL": "https://orgURL/portal/",
      "when": 1543192196521
   },
   "events": [{
      "username": "administrator",
      "userId": "173dd04b69134bdf99c5000aad0b6298",
      "when": 1543192196521,
      "operation": "update",
      "source": "group",
      "id": "173dd04b69134bdf99c5000aad0b6298",
      "properties": {}
   }]
}

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

يمكن إدارة خطافات الويب فقط عبر دليل بوابة ArcGIS (مشاركة API). استخدم الخطوات التالية لإنشاء خطاف ويب:

1. استعرض دليل بوابة ArcGIS.
   https://machine.domain.com/webadaptor/sharing/rest
2. قم بتسجيل الدخول بصفتك مسؤولًا.

   يمكن إنشاء خطافات الويب فقط وإدارتها بواسطة مسؤول.

   تظهر صفحة المستخدم المسؤول.

3. انقر على الارتباط التشعبي معرف المؤسسة أو قدم طلبا للنموذج أدناه، للذهاب إلى صفحة الموارد الذاتية بالبوابة.
   https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>
4. مرر لأسفل الصفحة، إلى Webhooks، أسفل موارد الطفل.
   https://machine.domain/com/webadaptor/sharing/rest/portals/<orgID>/webhooks
5. أسفل العملية المدعومة، حدد Create Webhook.
6. حدد معلمات خطاف الويب الخاص بك.

   انظر وثائق خطاف الويب REST API للحصول على تفاصيل عن تلك المعلمات.

   خطاف الويب الخاص بك الآن مدرج تحت خطافات الويب: https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/webhooks

إدارة خطافات الويب

يمكنك إدارة خطافات الويب الخاصة بك عبر دليل بوابة ArcGIS عبر التقدم بطلب للنموذج التالي:

https://machine.domain.com/webadaptor/sharing/rest/<orgID>/webhooks/<webhookID>.

العمليات المدعومة لإدارة خطافات الويب الخاصة بك هي كما يلي:

• Update Webhook—تحديث معلمات خطاف الويب الخاصة بك. يمكنك تحديث الاسم أو عنوان URL الحمولة أو أحداث المشغل لخطاف الويب المحدد.
• Delete Webhook—إزالة خطاف الويب من بوابتك الإلكترونية.
• Deactivate Webhook و Activate Webhook—إلغاء تنشيط خطاف الويب الخاص بك، الذي يوقف توصيل الحمولات عند تشغيل خطاف الويب. عند إلغاء تنشيط خطاف الويب، تصبح عملية تنشيط خطاف الويب متاحة لاستئناف توصيل الحمولات.

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

انظر Webhooks API لتجد أمثلة على تلك العمليات.

قم بتهيئة المعلمات المتقدمة

هناك العديد من المعلمات المتقدمة التي يمكن استخدامها لتخصيص خطافات الويب الخاصة بك أكثر. سوف تنطبق تلك المعلمات على جميع خطافات الويب التي تمت تهيئتها في بوابتك ويمكن الوصول إليها من خلال https://machine.domain.com/webadaptor/sharing/rest/portals/<orgID>/webhooks/settings.

تتيح العملية Update لك تحديث المعلمات التالية:

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

راجع وثائق API خطافات الويب لمزيد من المعلومات عن كيفية تهيئة المعلمات المتقدمة.

الاسئلة المتداولة حول خطافات الويب

فيما يلي الأسئلة الشائعة المتعلقة باستخدام خطافات الويب.

يتم نشر ArcGIS Enterprise في بيئة غير متصلة خلف جدار الحماية الخاص بمؤسستي. هل لا يزال بإمكاني تكوين خطافات الويب؟

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

ما الذي يشكل تحديثًا لعنصر أو مستخدم أو مجموعة؟

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

أستخدم مصادقة Windows المتكاملة في بوابة ArcGIS Enterprise الخاصة بي. هل لا يزال بإمكاني الاشتراك في عمليتي تسجيل دخول المستخدم وتسجيل خروجه من البوابة الإلكترونية (user/<username>/signIn)؟

بداية من الإصدار 10.9، يمكنك استخدام حدث /signin المُشغل لالتقاط أحداث تسجيل الدخول لمصادقة البوابة الإلكترونية ومصادقة طبقة الويب وتسجيلات الدخول المؤسسية.

ماذا يحدث إذا تعطل عنوان URL الخاص بحمولة البيانات أو أصبح غير متاح؟ هل هناك طريقة لاسترداد حمولة لم يتم تسليمها؟

إذا كانت البوابة تحاول تسليم حمولة إلى عنوان URL غير قابل للوصول أو غير مستجيب أو وحدة استقبال خطاف الويب، فستحدد المعلمات المتقدمة التي عينتها كيف تحاول البوابة إجراء عملية تسليم أخرى ومت يتم ذلك. إذا فشلت هذه المحاولات الإضافية أيضًا في تسليم الحمولة، فسيتم اعتبار ذلك بمثابة فشل واحد تجاه deactivationPolicy الذي عينته عند إنشاء خطاف الويب. يُلغى تنشيط خطاف الويب بمجرد تحقيق هذه السياسة.

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