إعداد الإشعارات باستخدام الردود التلقائية على الويب

أنت الآن بصدد الاطّلاع على مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. info

ما هو Webhook؟

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

لإعداد الإشعارات باستخدام خطافات الويب، أكمِل الخطوات التالية باستخدام واجهة مستخدم Edge Management أو Management and Monetization API:

  1. أضِف خطافات ويب تحدّد معالجات معاودة الاتصال لأحداث الإشعارات باستخدام واجهة المستخدم أو واجهة برمجة التطبيقات.
  2. إعداد معالج رد الاتصال
  3. اضبط الإشعار لخطة أسعار متغيرة باستخدام واجهة المستخدم أو واجهة برمجة التطبيقات.

إدارة الويب هوك

أضِف وأدِر خطافات الويب التي تحدّد معالجات معاودة الاتصال لأحداث الإشعارات باستخدام واجهة المستخدم أو واجهة برمجة التطبيقات.

إدارة الويب هوك باستخدام واجهة المستخدم

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

استكشاف صفحة Webhooks

انتقِل إلى صفحة Webhooks، كما هو موضّح أدناه.

Edge

للوصول إلى صفحة Webhooks باستخدام واجهة مستخدم Edge، اتّبِع الخطوات التالية:

  1. سجِّل الدخول إلى apigee.com/edge.
  2. انقر على نشر > تحقيق الربح > خطافات الويب في شريط التنقّل الأيمن.

تظهر صفحة Webhooks.

كما هو موضّح في الشكل، تتيح لك صفحة Webhooks إجراء ما يلي:

Classic Edge (Private Cloud)

للوصول إلى صفحة Webhooks باستخدام واجهة مستخدم Classic Edge، اتّبِع الخطوات التالية:

  1. سجِّل الدخول إلى http://ms-ip:9000، حيث ms-ip هو عنوان IP أو اسم نظام أسماء النطاقات لعقدة خادم الإدارة.

  2. اختَر المشرف > خطّافات الويب.

تظهر صفحة "خطافات الويب".

تتيح لك صفحة Webhooks إجراء ما يلي:

إضافة ويب هوك باستخدام واجهة المستخدم

لإضافة خطاف ويب باستخدام واجهة المستخدم، اتّبِع الخطوات التالية:

  1. انتقِل إلى صفحة "إجراءات الويب هوك".
  2. انقر على + Webhook.
  3. أدخِل المعلومات التالية (جميع الحقول مطلوبة).
    الحقل الوصف
    الاسم اسم الويب هوك.
    عنوان URL عنوان URL لمعالج ردّ الاتصال الذي سيتم استدعاؤه عند تفعيل إشعار برصد حدث. اطّلِع على إعداد معالج رد الاتصال.
  4. انقر على حفظ.

تتم إضافة Webhook إلى القائمة وتفعيله تلقائيًا.

تعديل ويب هوك باستخدام واجهة المستخدم

لتعديل ويب هوك باستخدام واجهة المستخدم، اتّبِع الخطوات التالية:

  1. انتقِل إلى صفحة "إجراءات الويب هوك".
  2. ضَع مؤشر الماوس فوق Webhook الذي تريد تعديله وانقر على في قائمة الإجراءات.
  3. عدِّل حقول الويب هوك حسب الحاجة.
  4. انقر على تعديل الويب هوك.

تفعيل أو إيقاف خطاف ويب باستخدام واجهة المستخدم

لتفعيل أو إيقاف Webhook باستخدام واجهة المستخدم، اتّبِع الخطوات التالية:

  1. انتقِل إلى صفحة "إجراءات الويب هوك".
  2. ضَع مؤشر الماوس فوق Webhook وبدِّل مفتاح الحالة لتفعيله أو إيقافه.

حذف ويب هوك باستخدام واجهة المستخدم

لحذف ويب هوك باستخدام واجهة المستخدم، اتّبِع الخطوات التالية:

  1. انتقِل إلى صفحة "إجراءات الويب هوك".
  2. ضَع المؤشر فوق webhook الذي تريد حذفه وانقر على .

سيتم حذف رابط الويب وإزالته من القائمة.

إدارة خطافات الويب باستخدام واجهة برمجة التطبيقات

يمكنك إضافة خطافات الويب وإدارتها باستخدام واجهة برمجة التطبيقات كما هو موضّح في الأقسام التالية.

عرض جميع خطافات الويب باستخدام واجهة برمجة التطبيقات

يمكنك عرض جميع خطافات الويب من خلال إرسال طلب استرداد بيانات باستخدام GET إلى /mint/organizations/{org_name}/webhooks. على سبيل المثال:

curl -X GET "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks" \
  -H "Content-Type: application/json " \
  -u email:password

في ما يلي مثال على الرد الذي تم إرجاعه:

{
  "totalRecords": 2,
  "webhooks": [
    {
      "created": 1460162656342,
      "enabled": false,
      "id": "21844a37-d26d-476c-93ed-38f3a4b24691",
      "name": "webhook1",
      "postUrl": "http://mycompany.com/callbackhandler1",
      "updated": 1460162656342,
      "updatedBy": "joe@example.com"
    },
        {
      "created": 1460138724352,
      "createdBy": "joe@example.com",
      "enabled": true,
      "id": "a39ca777-1861-49cf-a397-c9e92ab3c09f",
      "name": "webhook2",
      "postUrl": "http://mycompany.com/callbackhandler2",
      "updated": 1460138724352,
      "updatedBy": "joe@example.com"
    }

  ]
}

عرض ويب هوك باستخدام واجهة برمجة التطبيقات

يمكنك عرض إشعار webhook واحد من خلال إرسال طلب استرداد بيانات باستخدام GET إلى /mint/organizations/{org_name}/webhooks/{webhook_id}.

على سبيل المثال:

curl -X GET "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/21844a37-d26d-476c-93ed-38f3a4b24691" \
  -H "Content-Type: application/json " \
  -u email:password

في ما يلي مثال على الردّ:

{
   "created": 1460162656342,
   "enabled": false,
   "id": "21844a37-d26d-476c-93ed-38f3a4b24691",
   "name": "webhook1",
   "postUrl": "http://mycompany.com/callbackhandler1",
   "updated": 1460162656342,
   "updatedBy": "joe@example.com"
 }

إضافة ويب هوك باستخدام واجهة برمجة التطبيقات

أضِف ويب هوك عن طريق إرسال طلب POST إلى /mint/organizations/{org_name}/webhooks. يجب تمرير اسم خطاف الويب وعنوان URL لمعالج ردّ الاتصال الذي سيتم استدعاؤه عند تفعيل إشعار برصد حدث.

على سبيل المثال، ينشئ ما يلي ويب هوك باسم webhook3 ويُعيّن callbackhandler3 إلى الويب هوك:

curl -X POST "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks"
  -H "Content-Type: application/json "
  -d '{
    "name": "webhook3",
    "postURL": "http://mycompany.com/callbackhandler3"
    }' \
    -u email:password

في ما يلي مثال على الردّ:

{
  "created": 1460385534555,
  "createdBy": "joe@example.com",
  "enabled": false,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler3",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

تعديل ويب هوك باستخدام واجهة برمجة التطبيقات

عدِّل الويب هوك عن طريق إرسال طلب PUT إلى /mint/organizations/{org_name}/webhooks/{webhook_id}. مرِّر التعديلات في نص الطلب.

على سبيل المثال، يؤدي ما يلي إلى تعديل معالج رد الاتصال المرتبط بـ webhook1:

curl -X PUT "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/0a07eb1f-f485-4539-8beb-01be449699b3" \
  -H "Content-Type: application/json " \
  -d '{
    "postURL": "http://mycompany.com/callbackhandler4"
  }' \
  -u email:password

في ما يلي مثال على الردّ:

{
  "created": 1460385534555,
  "enabled": false,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler4",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

تفعيل أو إيقاف الويب هوك باستخدام واجهة برمجة التطبيقات

يمكنك تفعيل ويب هوك أو إيقافه عن طريق إرسال طلب POST إلى /mint/organizations/{org_name}/webhooks/{webhook_id}، كما فعلت عند تعديل ويب هوك، وضبط السمة "مفعّل" في نص الطلب على "صحيح" أو "خطأ"، على التوالي. في حال إيقاف Webhook، لن يتم تشغيله عند حدوث حدث.

على سبيل المثال، يتيح ما يلي webhook3:

curl -X POST "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/0a07eb1f-f485-4539-8beb-01be449699b3" \
  -H "Content-Type: application/json " \
  -d '{
    "enabled": "true"
  }' \
  -u email:password

في ما يلي مثال على الردّ:

{
  "created": 1460385534555,
  "enabled": true,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler4",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

حذف ويب هوك باستخدام واجهة برمجة التطبيقات

يمكنك حذف ويب هوك من خلال إرسال طلب DELETE إلى /mint/organizations/{org_name}/webhooks/{webhook_id}.

لتحديد ما إذا كان سيتم فرض حذف خطاف الويب في حال توفّر عمليات قيد التقدم، اضبط مَعلمة طلب البحث forceDelete على true أو false. تكون مَعلمة طلب البحث forceDelete مفعَّلة (true) تلقائيًا.

على سبيل المثال، يؤدي ما يلي إلى حذف webhook3:

curl -X DELETE "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/21844a37-d26d-476c-93ed-38f3a4b24691" \
  -H "Content-Type: application/json " \
  -u email:password

إعداد معالج رد الاتصال

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

{
        "orgName": "{org_id}",
        "developerEmail": "{dev_email}",
        "developerFirstName": "{first_name}",
        "developerLastName": "{last_name}",
        "companyName": "{company_name}",
        "applicationName": "{app_name}",
        "packageName": "{api_package_name}",
        "packageId": "{api_package_id}",
        "ratePlanId": "{rateplan_id}",
        "ratePlanName": "{rateplan_name}",
        "ratePlanType": "{rateplan_type}",
        "developerRatePlanQuotaTarget": {quota_target},
        "quotaPercentUsed": {percentage_quota_used},
        "ratePlanStartDate": {rateplan_startdate}, 
        "ratePlanEndDate": {rateplan_enddate},
        "nextBillingCycleStartDate": {next_billing_cycle_startdate},
        "products": ["{api_product_name}","{api_product_name}"],
        "developerCustomAttributes": [],
        "triggerTime": {trigger_time},
        "triggerReason": "{trigger_reason}",
        "developerQuotaResetDate": "{devquota_resetdate}"
}

إعداد الإشعارات لخطة أسعار متغيرة

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

إعداد إشعارات لخطة أسعار متغيرة باستخدام واجهة المستخدم

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

الوصول إلى مربّع حوار "الإشعارات" لخطة ذات سعر متغيّر

يمكنك الوصول إلى مربّع الحوار "الإشعارات" الخاص بخطة الأسعار المتغيرة، كما هو موضّح أدناه.

Edge

للوصول إلى مربّع حوار الإشعارات باستخدام واجهة مستخدم Edge، اتّبِع الخطوات التالية:

  1. أنشئ خطة معدّل إشعارات قابلة للتعديل وانشرها، كما هو موضّح في تحديد تفاصيل خطة معدّل الإشعارات القابلة للتعديل.
  2. يمكنك الوصول إلى صفحة "خطط الأسعار" من خلال النقر على نشر > تحقيق الربح > خطط الأسعار في شريط التنقّل الأيمن.
  3. ضَع مؤشر الماوس فوق خطة معدّل الإشعارات القابلة للتعديل المنشورة لعرض الإجراءات.
  4. انقر على +إرسال إشعار.

    يظهر مربّع الحوار "الإشعارات".

    ملاحظة: يجب نشر خطة الأسعار لكي يظهر الإجراء "إرسال إشعار".

Classic Edge (Private Cloud)

للوصول إلى صفحة "الإشعارات"، اتّبِع الخطوات التالية:

  1. أنشئ خطة معدّل إشعارات قابلة للتعديل، كما هو موضّح في تحديد تفاصيل خطة الإشعارات القابلة للتعديل.
  2. انقر على نشر > الحِزم لعرض خطط الأسعار.
  3. انقر على +إرسال إشعار في عمود "الإجراءات" لخطة الأسعار.

    يظهر مربّع الحوار "الإشعارات".

إضافة إشعارات لخطة أسعار متغيرة باستخدام واجهة المستخدم

لإضافة إشعارات لخطة أسعار قابلة للتعديل في واجهة المستخدم، اتّبِع الخطوات التالية:

  1. افتح مربّع حوار الإشعارات.
  2. اضبط شرط الإشعار ضمن فواصل الإشعارات من خلال تحديد نسبة مئوية من عدد المعاملات المستهدَف الذي تريد أن يتم تشغيل الإشعار عنده. على وجه التحديد:
    • لضبط نسبة مئوية دقيقة، أدخِل النسبة المئوية في الحقل عند/من % واترك الحقل إلى % فارغًا.
    • لضبط نطاق النسبة المئوية، أدخِل النسبة المئوية للبدء والانتهاء في الحقلَين عند/من % وإلى % على التوالي، وأدخِل قيمة الزيادة في الحقل الخطوة %. يتم تلقائيًا إرسال الإشعارات بزيادات تبلغ %10 ضمن النطاق المحدّد.

    يتم تعديل الحقل Notify At ليعكس كل نسبة مئوية من العدد المستهدَف للمعاملات التي ستؤدي إلى تشغيل حدث.

  3. لضبط شروط إضافية للإشعارات، انقر على +إضافة وكرِّر الخطوة 4.
  4. اضبط إجراء الإشعار ضمن Webhooks من خلال اختيار Webhook واحد أو أكثر لإدارة معالجة عمليات معاودة الاتصال عند تشغيل الإشعارات.
  5. انقر على إنشاء إشعار.

تعديل الإشعارات لخطة أسعار متغيرة باستخدام واجهة المستخدم

لتعديل الإشعارات الخاصة بخطة أسعار متغيرة في واجهة المستخدم، اتّبِع الخطوات التالية:

  1. افتح مربّع حوار الإشعارات.
  2. انقر على +إرسال إشعار في عمود "الإجراءات" لخطة الأسعار.
  3. انقر على تعديل.
  4. عدِّل القيم حسب الحاجة.
  5. انقر على حفظ الإشعار.

حذف إشعارات خطة السعر المتغيّر باستخدام واجهة المستخدم

لحذف شرط إشعار وإجراء:

  1. افتح مربّع حوار الإشعارات.
  2. انقر على +إرسال إشعار في عمود "الإجراءات" لخطة الأسعار.
  3. انقر على حذف الإشعار.

إعداد إشعارات بشأن خطة أسعار متغيرة باستخدام واجهة برمجة التطبيقات

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

لإعداد شرط الإشعار (notificationCondition)، استخدِم قيم السمات التالية. لمزيد من المعلومات، يُرجى الاطّلاع على خصائص الإعداد لشروط الإشعارات.

السمة القيمة
RATEPLAN معرّف خطة معدّل الإشعارات القابلة للتعديل.
PUBLISHED TRUE للإشارة إلى أنّه يجب نشر خطة معدّل الإشعارات القابلة للتعديل.
UsageTarget النسبة المئوية لعدد المعاملات المستهدَف التي تريد أن يتم تشغيل إشعار عندها.

تتيح لك هذه السمة إرسال إشعارات إلى المطوّرين عندما يقتربون من عدد المعاملات المستهدَف أو عندما يبلغونه، وذلك في إطار خطة بطاقة معدّل الإشعارات القابلة للتعديل التي اشتروها. على سبيل المثال، إذا اشترى مطوِّر خطة معدّل إشعارات قابلة للتعديل وتم ضبط العدد المستهدف للمعاملات التي يجريها المطوِّر على 1,000، يمكنك إرسال إشعار إليه عند وصوله إلى 800 معاملة (80% من العدد المستهدف للمعاملات) أو 1,000 معاملة (100%) أو 1,500 معاملة (150%).

  • لضبط نسبة مئوية دقيقة، أدخِل %= n. على سبيل المثال، سيرسل %= 80 إشعارات عندما تصل نسبة عدد المعاملات المستهدَف إلى %80.
  • لضبط نطاق النسبة المئوية، أدخِل النسبة المئوية للبداية والنهاية، والقيمة التي سيتم زيادتها بها على النحو التالي: %= start to end by n. على سبيل المثال، ستؤدي القيمة %= 80 to 100 by 10 إلى إرسال إشعارات عندما تصل النسبة المئوية لعدد المعاملات المستهدَف إلى %80 و%90 و%100.

لإعداد إجراء الإشعار، ضَع علامة في المربّع actions وعيِّن القيم التالية. لمزيد من المعلومات، يُرجى الاطّلاع على خصائص الإعدادات لإجراءات الإشعارات.

السمة القيمة
actionAttribute WEBHOOK لتشغيل ويب هوك.
value معرّف خطاف الويب الذي حدّدته في القسم السابق، إنشاء خطافات ويب باستخدام واجهة برمجة التطبيقات

يوضّح ما يلي مثالاً على كيفية إنشاء شرط إشعار يؤدي إلى تشغيل خطاف ويب عندما تصل نسبة عدد المعاملات المستهدَفة إلى %80 و%90 و%100 و%110 و%120.

{
    "notificationCondition": [
      {
        "attribute": "RATEPLAN",
        "value": "123456"
      },
      {
        "attribute": "PUBLISHED",
        "value": "TRUE"
      },
      {
        "attribute": "UsageTarget",
        "value": "%= 80 to 120 by 10"
      }
    } 
    ],
   "actions": [{
          "actionAttribute": "WEBHOOK",
          "value": "b0d77596-142e-4606-ae2d-f55c3c6bfebe",
        }]
  }

للحصول على معلومات حول عرض وتعديل وحذف شرط وإجراء إشعار، يُرجى الاطّلاع على ما يلي:

رموز استجابة الويب هوك

يلخّص ما يلي رموز استجابة Webhook وكيفية تفسيرها من قِبل النظام.

رمز الاستجابة الوصف
2xx تم الإجراء بنجاح
5xx

تعذّر تنفيذ الطلب. سيعيد النظام محاولة تنفيذ الطلب ثلاث مرات كحد أقصى على فترات زمنية مدتها 5 دقائق.

ملاحظة: تبلغ مهلة القراءة ومهلة الاتصال لطلبات Webhook 3 ثوانٍ لكل منهما، ما قد يؤدي إلى تعذُّر إرسال الطلبات.
Other response تعذّر تنفيذ الطلب. ولن يعيد النظام محاولة تنفيذ الطلب.