#دمج طلبات HTTP في سير العمل

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

#نظرة عامة

يُعد مكون طلب HTTP مكونًا أساسيًا للدمج في سير العمل، حيث يتيح لك استدعاء واجهات برمجة تطبيقات (APIs) تابعة لجهات خارجية، أو واجهات خدمات داخلية، أو خدمات ويب أخرى أثناء تنفيذ سير العمل لاسترداد البيانات أو تشغيل عمليات خارجية.

#حالات الاستخدام النموذجية

#استرداد البيانات

• استعلامات بيانات الجهات الخارجية: استرداد البيانات في الوقت الفعلي من واجهات برمجة تطبيقات الطقس، واجهات برمجة تطبيقات أسعار الصرف، وما إلى ذلك.
• تحليل العناوين: استدعاء واجهات برمجة تطبيقات خدمات الخرائط لتحليل العناوين وتحديد المواقع الجغرافية.
• مزامنة بيانات المؤسسة: استرداد بيانات العملاء والطلبات من أنظمة إدارة علاقات العملاء (CRM) وأنظمة تخطيط موارد المؤسسات (ERP).

#تشغيل العمليات التجارية

• إرسال الإشعارات: استدعاء خدمات الرسائل النصية القصيرة والبريد الإلكتروني وWeCom لإرسال الإشعارات.
• طلبات الدفع: بدء عمليات الدفع أو استرداد الأموال مع بوابات الدفع.
• معالجة الطلبات: إرسال بوالص الشحن والاستعلام عن حالة الشحن مع أنظمة الشحن.

#دمج الأنظمة

• استدعاء الخدمات المصغرة: استدعاء واجهات برمجة تطبيقات الخدمات الأخرى في بنى الخدمات المصغرة.
• الإبلاغ عن البيانات: الإبلاغ عن بيانات الأعمال إلى منصات تحليل البيانات وأنظمة المراقبة.
• خدمات الجهات الخارجية: دمج خدمات الذكاء الاصطناعي، والتعرف الضوئي على الحروف (OCR)، وتوليف الكلام، وما إلى ذلك.

#التشغيل الآلي

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

#الميزات

#دعم HTTP الكامل

• يدعم جميع طرق HTTP: GET، POST، PUT، PATCH، DELETE.
• رؤوس الطلبات المخصصة (Headers).
• تنسيقات بيانات متعددة: JSON، بيانات النموذج، XML، وما إلى ذلك.
• أنواع متعددة من المعلمات: معلمات URL، معلمات المسار، نص الطلب.

#معالجة البيانات المرنة

• مراجع المتغيرات: إنشاء الطلبات ديناميكيًا باستخدام متغيرات سير العمل.
• تحليل الاستجابة: تحليل استجابات JSON تلقائيًا واستخراج البيانات المطلوبة.
• تحويل البيانات: تحويل تنسيقات بيانات الطلب والاستجابة.
• معالجة الأخطاء: تكوين استراتيجيات إعادة المحاولة، وإعدادات المهلة، ومنطق معالجة الأخطاء.

#المصادقة الأمنية

• المصادقة الأساسية (Basic Auth): مصادقة HTTP الأساسية.
• رمز الحامل (Bearer Token): مصادقة الرمز المميز.
• مفتاح API: مصادقة مفتاح API مخصص.
• رؤوس مخصصة (Custom Headers): دعم أي طريقة مصادقة.

#خطوات الاستخدام

#1. التحقق من تمكين الإضافة

يُعد مكون طلب HTTP ميزة مدمجة في إضافة سير العمل. تأكد من تمكين إضافة سير العمل.

#2. إضافة مكون طلب HTTP إلى سير العمل

1. أنشئ أو عدّل سير عمل.
2. أضف مكون طلب HTTP في الموضع المطلوب.

3. قم بتكوين معلمات الطلب.

#3. تكوين معلمات الطلب

#التكوين الأساسي

• عنوان URL للطلب: عنوان API المستهدف، يدعم استخدام المتغيرات.

  https://api.example.com/users/{{$context.userId}}

• طريقة الطلب: اختر GET، POST، PUT، DELETE، وما إلى ذلك.

• رؤوس الطلب: تكوين رؤوس HTTP.

  {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{$context.apiKey}}"
  }

• معلمات الطلب:

  • معلمات الاستعلام (Query Parameters): معلمات استعلام URL.
  • معلمات النص الأساسي (Body Parameters): بيانات نص الطلب (POST/PUT).

#التكوين المتقدم

• المهلة: تعيين مهلة الطلب (الافتراضي 30 ثانية).
• إعادة المحاولة عند الفشل: تكوين عدد مرات إعادة المحاولة والفاصل الزمني لإعادة المحاولة.
• تجاهل الفشل: متابعة سير العمل حتى إذا فشل الطلب.
• إعدادات الوكيل: تكوين وكيل HTTP (إذا لزم الأمر).

#4. استخدام بيانات الاستجابة

بعد تنفيذ مكون طلب HTTP، يمكن استخدام بيانات الاستجابة في المكونات اللاحقة:

• {{$node.data.status}}: رمز حالة HTTP.
• {{$node.data.headers}}: رؤوس الاستجابة.
• {{$node.data.data}}: بيانات نص الاستجابة.
• {{$node.data.error}}: رسالة الخطأ (إذا فشل الطلب).

#سيناريوهات الأمثلة

#مثال 1: الحصول على معلومات الطقس

// التكوين
URL: https://api.weather.com/v1/current
Method: GET
Query Parameters:
  city: {{$context.city}}
  key: your-api-key

// استخدام الاستجابة
Temperature: {{$node.data.data.temperature}}
Weather: {{$node.data.data.condition}}

#مثال 2: إرسال رسالة WeCom

// التكوين
URL: https://qyapi.weixin.qq.com/cgi-bin/message/send
Method: POST
Headers:
  Content-Type: application/json
Body:
{
  "touser": "{{$context.userId}}",
  "msgtype": "text",
  "agentid": 1000001,
  "text": {
    "content": "Order {{$context.orderId}} has been shipped"
  }
}

#مثال 3: الاستعلام عن حالة الدفع

// التكوين
URL: https://api.payment.com/v1/orders/{{$context.orderId}}/status
Method: GET
Headers:
  Authorization: Bearer {{$context.apiKey}}
  Content-Type: application/json

// المنطق الشرطي
إذا كان {{$node.data.data.status}} يساوي "paid"
  - تحديث حالة الطلب إلى "مدفوع"
  - إرسال إشعار بنجاح الدفع
وإلا إذا كان {{$node.data.data.status}} يساوي "pending"
  - إبقاء حالة الطلب "في انتظار الدفع"
وإلا
  - تسجيل فشل الدفع
  - إخطار المسؤول للتعامل مع الاستثناء

#مثال 4: مزامنة البيانات مع CRM

// التكوين
URL: https://api.crm.com/v1/customers
Method: POST
Headers:
  X-API-Key: {{$context.crmApiKey}}
  Content-Type: application/json
Body:
{
  "name": "{{$context.customerName}}",
  "email": "{{$context.email}}",
  "phone": "{{$context.phone}}",
  "source": "NocoBase",
  "created_at": "{{$context.createdAt}}"
}

#تكوين المصادقة

#المصادقة الأساسية (Basic Authentication)

Headers:
  Authorization: Basic base64(username:password)

#رمز الحامل (Bearer Token)

Headers:
  Authorization: Bearer your-access-token

#مفتاح API

// في الرأس (Header)
Headers:
  X-API-Key: your-api-key

// أو في الاستعلام (Query)
Query Parameters:
  api_key: your-api-key

#OAuth 2.0

يجب الحصول على access_token أولاً، ثم استخدامه كالتالي:

Headers:
  Authorization: Bearer {{$context.accessToken}}

#معالجة الأخطاء وتصحيحها

#الأخطاء الشائعة

1. انتهاء مهلة الاتصال: تحقق من اتصال الشبكة، وزد وقت المهلة.
2. 401 غير مصرح به: تحقق مما إذا كانت معلومات المصادقة صحيحة.
3. 404 غير موجود: تحقق مما إذا كان عنوان URL صحيحًا.
4. 500 خطأ في الخادم: تحقق من حالة خدمة مزود API.

#نصائح لتصحيح الأخطاء

1. استخدام مكونات السجل: أضف مكونات السجل قبل وبعد طلبات HTTP لتسجيل بيانات الطلب والاستجابة.

2. التحقق من سجلات التنفيذ: تحتوي سجلات تنفيذ سير العمل على معلومات مفصلة عن الطلبات والاستجابات.

3. أدوات الاختبار: اختبر واجهة برمجة التطبيقات أولاً باستخدام أدوات مثل Postman أو cURL.

4. معالجة الأخطاء: أضف منطقًا شرطيًا للتعامل مع حالات الاستجابة المختلفة.

إذا كان {{$node.data.status}} >= 200 و {{$node.data.status}} < 300
  - معالجة منطق النجاح
وإلا
  - معالجة منطق الفشل
  - تسجيل الخطأ: {{$node.data.error}}

#نصائح لتحسين الأداء

#1. استخدام المعالجة غير المتزامنة

بالنسبة للطلبات التي لا تتطلب نتائج فورية، فكر في استخدام سير عمل غير متزامن.

#2. تكوين مهلات زمنية معقولة

قم بتعيين مهلات زمنية بناءً على أوقات استجابة API الفعلية لتجنب الانتظار المفرط.

#3. تطبيق استراتيجيات التخزين المؤقت

بالنسبة للبيانات التي لا تتغير كثيرًا (مثل التكوينات والقواميس)، فكر في تخزين الاستجابات مؤقتًا.

#4. المعالجة الدفعية

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

#5. إعادة المحاولة عند الخطأ

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

#أفضل ممارسات الأمان

#1. حماية المعلومات الحساسة

• لا تكشف عن معلومات حساسة في عناوين URL.
• استخدم HTTPS للنقل المشفر.
• استخدم متغيرات البيئة أو إدارة التكوين لتخزين مفاتيح API والبيانات الحساسة.

#2. التحقق من صحة بيانات الاستجابة

// التحقق من حالة الاستجابة
if (![200, 201].includes($node.data.status)) {
  throw new Error('API request failed');
}

// التحقق من تنسيق البيانات
if (!$node.data.data || !$node.data.data.id) {
  throw new Error('Invalid response data');
}

#3. تحديد معدل الطلبات

التزم بحدود معدل واجهة برمجة التطبيقات التابعة لجهات خارجية لتجنب الحظر.

#4. إخفاء هوية السجلات

عند تسجيل السجلات، احرص على إخفاء هوية المعلومات الحساسة (مثل كلمات المرور والمفاتيح).

#مقارنة مع Webhook

يكمل هذان المكونان بعضهما البعض لبناء حل دمج أنظمة متكامل.

#الموارد ذات الصلة

• وثائق إضافة سير العمل
• سير العمل: مكون طلب HTTP
• سير العمل: مشغل Webhook
• مصادقة مفاتيح API
• إضافة وثائق API