يصف هذا المستند حل واجهة برمجة التطبيقات/Webhook لدمج أحداث طلب سحب Bitbucket في نظام Workcube باستخدام Workcube WEX (امتداد Workcube). يسهل هذا التكامل تتبع عمليات عملك ويثري إدارة المشروع عن طريق نقل حركة طلب السحب تلقائيًا في عمليات التطوير الخاصة بك إلى Workcube.

نظرة عامة

تم تصميم مكون WEX هذا للاستماع إلى أحداث طلب السحب من Bitbucket وحفظ البيانات ذات الصلة في قاعدة بيانات Workcube. بهذه الطريقة، يصبح الوصول إلى المعلومات ذات الصلة تلقائيًا في Workcube لكل طلب سحب مفتوح أو محدث أو مغلق على Bitbucket.

الغرض: معالجة بيانات طلب السحب الواردة من Bitbucket وربطها بمعرفات المهام ذات الصلة في Workcube أو الاحتفاظ بها كسجل عام.
التكنولوجيا: امتداد Workcube تم تطويره باستخدام ColdFusion (CFML). مكون (WEX).
كيف يعمل: يتم تشغيله عبر Webhook المحدد في إعدادات مستودع Bitbucket. عندما يأتي حدث طلب السحب من Bitbucket، يتم إرسال طلب HTTP POST إلى مكون WEX هذا وتتم معالجة حمولة JSON الواردة.

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

توجد أدناه نقطة نهاية Workcube WEX التي يجب أن تستخدمها في إعدادات Bitbucket Webhook. مثل:

URL:/WEX/bitbucket.cfc?method=ap (يعتمد عنوان URL هذا على جذر تثبيت Workcube ولا يتضمن اسم الخادم. على سبيل المثال: https:yourworkcube.com/WEX/bitbucket.cfc?method=ap)
الطريقة:POST
نوع المحتوى (نوع المحتوى): application/json

المتطلبات

يجب تثبيت وحدة WEX (امتداد Workcube) وتنشيطها في نظام Workcube الخاص بك.
مكون WEX المذكور في هذا المستند ( WEX/bitbucket.cfc ) والمكونات التابعة (على سبيل المثال. WEX.bitbucket.components.data) يجب نشرها على خادم Workcube الخاص بك.
يجب تكوين نقطة النهاية هذه بشكل صحيح ضمن إعدادات "Webhooks" في مستودع Bitbucket الخاص بك. على وجه التحديد، تأكد من تحديد أحداث "طلب السحب".

منطق التشغيل

يقوم مكون WEX بمعالجة حمولة طلب السحب من Bitbucket بالخطوات التالية:

عند تشغيل حدث طلب السحب (إنشاء، تحديث، دمج، وما إلى ذلك)، يرسل Bitbucket طلب HTTP POST إلى نقطة نهاية WEX المحددة. يحتوي نص هذا الطلب على معلومات طلب السحب بتنسيق JSON.
ap تستقبل الدالة بيانات JSON الواردة (وسيطة البيانات ).
تتحقق مما إذا كان مفتاح طلب السحب موجودًا في البيانات. إذا كانت متاحة، فإنها تستدعي وظيفة طلب السحب، وهي وظيفة معالجة محددة لطلب السحب.
تقوم وظيفة طلب السحب بتحليل المعلومات التالية من بيانات JSON الواردة وتخصيصها للمتغيرات ذات الصلة:
- العنوان: عنوان طلب السحب.
- الوصف: تنسيق HTML من طلب السحب. الوصف.
- معرف المهمة: يتم البحث عن معرف مهمة Workcube من عنوان طلب السحب أو الوصف بتنسيق أرقام تبدأ بالعلامة # (على سبيل المثال، #12345). إذا تم العثور عليه، فسيتم مطابقة هذا المعرف.
- عنوان URL المعروض: عنوان URL المستخدم لعرض طلب السحب على Bitbucket.
- معلومات المؤلف: الاسم والتفاصيل الأخرى للمستخدم الذي أنشأ طلب السحب.
- تاريخ الإنشاء: إنشاء طلب السحب
- معرف Bitbucket PR: المعرف الفريد الذي يعينه Bitbucket لطلب السحب هذا.
- فرع الوجهة: اسم الفرع المستهدف الذي سيتم دمج طلب السحب فيه.
- الفرع المصدر: اسم الفرع المصدر الذي يأتي فيه. من.
- الحالة: الحالة الحالية لطلب السحب (على سبيل المثال: مفتوح، مدمج، مرفوض).
- المشاركون: معلومات حول المراجعين أو المشاركين الآخرين في طلب السحب.
هذه البيانات المحللة، يتم حفظها في قاعدة بيانات Workcube عن طريق استدعاء الدالة insert في المكون WEX.bitbucket.components.data. هذه هي خطوة تخزين البيانات الأساسية للتكامل.
إذا نجحت العملية، فسيتم إرجاع استجابة JSON ناجحة مع نتيجة(1). في حالة وجود أي خطأ، result(0, ""، cfcatch) ترجع استجابة JSON تحتوي على معلومات خطأ.
وظيفة النتيجة مسؤولة عن إرجاع جميع نتائج المعالجة بتنسيق JSON القياسي.

الاختبار باستخدام Postman أو أدوات مماثلة

لاختبار واجهة برمجة التطبيقات هذه، يمكنك استخدام عملاء REST مثل Postman، الأرق، أو الضفيرة. يمكنك محاكاة حدث طلب السحب باتباع الخطوات التالية:

الطريقة: حدد POST
عنوان URL: نقطة نهاية Workcube WEX (على سبيل المثال: Enter https://yourworkcube.com/WEX/bitbucket.cfc?method=ap).
الرؤوس:اضبط رأس نوع المحتوى على application/json.
النص: استخدم طلب سحب حقيقي حمولة JSON من Bitbucket. وفيما يلي مثال بسيط. ملاحظة: JSON هذا هو نسخة مبسطة من حمولة Bitbucket الفعلية. للحصول على حمولة مفصلة وكاملة، راجع وثائق Bitbucket أو التقطها عن طريق تشغيل خطاف ويب فعلي.

مثال لحمولة طلب سحب Bitbucket (بسيط)

{

"pullrequest": {

"id": 123,

"title": "ميزة جديدة: مهمة Workcube رقم 9876"،

"description": "يضيف طلب السحب هذا ميزة جديدة. معرف المهمة ذات الصلة: #9876"،

"state": "OPEN"،

"created_on": "2023-10-27T10:00:00.000000+00:00"،

"links": {

"html": {

"href": "https://bitbucket.org/your_repo/pull-requests/123"

},

"مؤلف": {

"display_name": "اسم المطور"

},

"الوجهة": {

"فرع": {

"الاسم": "رئيسي"

},

"مصدر": {

"فرع": {

"الاسم": "الميزة/الميزة الجديدة"

API الردود

ستكون استجابات واجهة برمجة التطبيقات (API) التي يتم إرجاعها نتيجة المكالمة بالتنسيقات التالية:

الاستجابة الناجحة

عند اكتمال العملية بنجاح:

{

"status": 1

إجابة خاطئة

عند حدوث خطأ أثناء العملية:

{

"status": 0،

"message": "سيتم وضع رسالة الخطأ هنا.",

"obj": {

"detail": "خطأ التفاصيل"،

"type": "نوع الخطأ"

ملاحظات الأمان

من المستحسن أن تأخذ في الاعتبار الطرق التالية لتأمين خطافات الويب الخاصة بك نقطة النهاية:

قم بتقييد عنوان URL الخاص بـ Webhook بحيث لا يتمكن سوى Bitbucket من الوصول إليه (على سبيل المثال، قيود IP عبر جدار الحماية).
من خلال تحديد "رمز مميز سري" لخطافات الويب Bitbucket، يمكنك التحقق من أن الطلب الوارد يأتي من Bitbucket. يمكنك تطوير آلية إضافية للتحقق من صحة هذا الرمز في مكون WEX الخاص بك.
تجنب إرسال المعلومات الحساسة مباشرة في معلمات URL.

?

???*

??? ???????*

?????? ?????????? *