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

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

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

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

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

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

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

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

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

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

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

العناصر

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

يدرج الجدول التالي أحداث المشغلات لعناصر البوابة المدعومة التي تشتمل على خرائط الويب وتطبيقات الويب والطبقات والحزم ومستندات 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/singOut
تم حذف أي مستخدم	/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 — كيف تتم مشاركة عنصر (groupID، Organization، or Everyone) 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://machineURL/portal/",
      "when": 1543192196521
   },
   "events": [{
      "username": "administrator",
      "userId": "173dd04b69134bdf99c5000aad0b6298",
      "when": 1543192196521,
      "operation": "update",
      "source": "group",
      "id": "173dd04b69134bdf99c5000aad0b6298",
      "properties": {}
   }]
}

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

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

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

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

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

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

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

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

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

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

https://webadaptorhost.domain.com/webadaptorname/sharing/rest/<org Id>/webhoooks/<webhookID>.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

يتم تشغيل هذه الأحداث فقط عندما يقوم المستخدم بتسجيل الدخول أو الخروج عبر OAuth. لذلك، فإن مصادقة Windows المتكاملة (IWA) وSAML غير مدعومة. ومع ذلك، فإن الأمن المدمج للبوابة وPKI يدعمان أحداث تسجيل الدخول وتسجيل الخروج.

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

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

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