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

خطاف الويب هو آلية تسمح للتطبيق بتقديم تطبيقات أخرى بمعلومات مستندة إلى الحدث. بصفتك مسؤول بوابة 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	sharedToGroups—كيف تتم مشاركة عنصر (معرِّف المجموعة، أو المؤسسة، أو الجميع) أمثلة، منسقة لتسهيل القراءة //groupIDs "properties": { "sharedToGroups": [ "ecd6646698b24180904e4888d5eaede3", "2dff15c514ad4f04b291e304e24a524b" ] } //Everyone and groupIDs "properties": { "sharedToGroups": [ "Everyone", "4adc30bb03054812a846fa592de105de", "a4e6e37e2f7d4bb5b64d587c91d39a2c" ] }
تم إلغاء مشاركة عنصر محدد	/items/<itemID>/unshare	unsharedFromGroups—كيفية إلغاء مشاركة عنصر (مُعرِّف المجموعة، أو المؤسسة، أو الجميع) أمثلة، منسقة لتسهيل القراءة //Everyone "properties": { "unsharedFromGroups": ["Everyone"] } //groupID "properties": { "unsharedFromGroups": [ "4adc30bb03054812a846fa592de105de" ] }
أُعيد تعيين ملكية عنصر محدد	/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	invitedUserNames—أسماء المستخدمين الخاصة بالمستخدمين المدعوين للانضمام إلى مجموعة. مثال، منسقة لتسهيل القراءة "properties": { "invitedUserNames": [ "u1TestUser", "u2TestUser" ] }
تمت إضافة مستخدم إلى مجموعة معينة	/groups/<groupID>/addUsers	addedUserNames—أسماء المستخدمين الخاصة بالمستخدمين الذين تمت إضافتهم إلى مجموعة. مثال، منسقة لتسهيل القراءة "properties": { "addedUserNames": [ "u1TestUser", "u2TestUser" ] }
تمت إزالة مستخدم من مجموعة معينة	/groups/<groupID>/removeUsers	removeUserNames—إزالة أسماء المستخدمين الخاصة بالمستخدمين من مجموعة. مثال، منسقة لتسهيل القراءة "properties": { "removedUserNames": [ "u1TestUser", "u2TestUser" ] }
تم تحديث دور مستخدم في مجموعة معينة	/groups/<groupID>/updateUsers	updateUserNames—أسماء المستخدمين الخاصة بالمستخدمين الذين تم تحديث أدوار مجموعتهم. مثال، منسقة لتسهيل القراءة "properties": { "updatedUserNames": [ "u1TestUser", "u2TestUser" ] }
أُعيد تعيين ملكية مجموعة معينة	/groups/<groupID>/reassign
عنصر مُشارك مع مجموعة	/groups/<groupID>/itemShare	sharedItems—itemID ونوع العنصر الخاص بالعنصر الذي تمت مشاركته مع مجموعة. مثال، منسقة لتسهيل القراءة "properties": { "sharedItems": [ { "itemId": "6cd80cb32d4a4b4d858a020e57fba7b1", "itemType": "Map Package" } ] }
تم إلغاء مشاركة عنصر من مجموعة معينة	/groups/<groupID>/itemUnshare	unsharedItems—itemID ونوع العنصر الخاص بالعنصر الذي تم إلغاء مشاركته من مجموعة. مثال، منسقة لتسهيل القراءة "properties": { "unsharedItems": [ { "itemId": "7dd95fadaec84859ab8ed1059e675e0c", "itemType": "Image" } ] }

المستخدمين

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

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

حَدَث المُشغِّل	مثال عنوان 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	userRoleUpdatedTo—الدور الجديد الذي تم تعيينه إلى المستخدم. مثال، منسقة لتسهيل القراءة "properties": { "userRoleUpdatedTo": ["New role"] }
تم تعيين نوع مستخدم جديد لمستخدم معين	/users/<username>/updateUserLicenseType	userLicenseTypeUpdatedTo—نوع المستخدم الجديد الذي تم تعيينه إلى المستخدم. مثال، منسقة لتسهيل القراءة "properties": { "userLicenseTypeUpdatedTo": ["Editor"] }

الأدوار

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

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

حَدَث المُشغِّل	مثال عنوان URI	خصائص
جميع أحداث المشغل لكل الأدوار في البوابة	/roles
تم إنشاء دور جديد.	/roles/add	name—اسم الدور الذي تم إنشاؤه أو تحديثه أو حذفه. مثال، منسقة لتسهيل القراءة "properties": { "name": ["New role"] }
تم تحديث دور موجود	/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 خطافات الويب لمزيد من المعلومات عن كيفية تهيئة المعلمات المتقدمة.