استخدام المكوّنات الإضافية

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

الإصدار 3.0.x من Edge Microgateway

الجمهور

هذا الموضوع مخصّص لمشغّلي Edge Microgateway الذين يريدون استخدام المكوّنات الإضافية الحالية المثبّتة مع البوابة المصغّرة. ويناقش أيضًا بالتفصيل المكوّنين الإضافيين "منع الارتفاع المفاجئ في عدد الزيارات" و"الحصة" (كلاهما مضمّنان مع عملية التثبيت). إذا كنت مطوّرًا تريد تطوير مكوّنات إضافية جديدة ، يُرجى الاطّلاع على مقالة تطوير مكوّنات إضافية مخصّصة.

ما هو المكوّن الإضافي في Edge Microgateway؟

المكوّن الإضافي هو وحدة Node.js تضيف وظائف إلى Edge Microgateway. تتّبع وحدات المكوّنات الإضافية نمطًا ثابتًا ويتم تخزينها في مكان معروف لدى Edge Microgateway، ما يتيح للبوابة المصغّرة اكتشافها وتحميلها تلقائيًا. يتضمّن Edge Microgateway عدة مكوّنات إضافية حالية ، ويمكنك أيضًا إنشاء مكوّنات إضافية مخصّصة، كما هو موضّح في مقالة تطوير مكوّنات إضافية مخصّصة.

المكوّنات الإضافية الحالية المضمّنة مع Edge Microgateway

تتوفّر عدة مكوّنات إضافية حالية مع Edge Microgateway عند التثبيت. وتشمل ما يلي:

المكوّن الإضافي مفعَّل تلقائيًا الوصف
إحصاءات نعم يرسل بيانات الإحصاءات من Edge Microgateway إلى Apigee Edge.
بروتوكول OAuth نعم يضيف عملية التحقّق من رمز OAuth المميّز ومفتاح واجهة برمجة التطبيقات إلى Edge Microgateway. يُرجى الاطّلاع على مقالة إعداد Edge Microgateway وضبطه.
الحصة لا يفرض حصة على الطلبات المُرسَلة إلى Edge Microgateway. يستخدم Apigee Edge لتخزين الحصص وإدارتها يُرجى الاطّلاع على مقالة استخدام المكوّن الإضافي "الحصة".
منع الارتفاع المفاجئ في عدد الزيارات لا يحمي من الارتفاع المفاجئ في عدد الزيارات وهجمات الحرمان من الخدمات. يُرجى الاطّلاع على مقالة استخدام المكوّن الإضافي "منع الارتفاع المفاجئ في عدد الزيارات".
header-uppercase لا نموذج خادم وكيل معلَّق يهدف إلى مساعدة المطوّرين في كتابة مكوّنات إضافية مخصّصة. يُرجى الاطّلاع على المكوّن الإضافي النموذجي في Edge Microgateway.
accumulate-request لا يجمع بيانات الطلب في عنصر واحد قبل تمرير البيانات إلى المعالج التالي في سلسلة المكوّنات الإضافية. مفيد لكتابة مكوّنات إضافية للتحويل تحتاج إلى العمل على عنصر واحد مجمّع لمحتوى الطلب.
accumulate-response لا يجمع بيانات الاستجابة في عنصر واحد قبل تمرير البيانات إلى المعالج التالي في سلسلة المكوّنات الإضافية. مفيد لكتابة مكوّنات إضافية للتحويل تحتاج إلى العمل على عنصر واحد مجمّع لمحتوى الاستجابة.
transform-uppercase لا يحوّل بيانات الطلب أو الاستجابة. يمثّل هذا المكوّن الإضافي أفضل ممارسة لتنفيذ مكوّن إضافي للتحويل. ينفّذ المكوّن الإضافي النموذجي عملية تحويل بسيطة (يحوّل بيانات الطلب أو الاستجابة إلى أحرف كبيرة)، ولكن يمكن تكييفه بسهولة لتنفيذ أنواع أخرى من عمليات التحويل، مثل تحويل XML إلى JSON.
json2xml لا يحوّل بيانات الطلب أو الاستجابة استنادًا إلى عنوانَي accept أو content-type. لمزيد من التفاصيل، يُرجى الرجوع إلى مستندات المكوّن الإضافي على GitHub.
quota-memory لا يفرض حصة على الطلبات المُرسَلة إلى Edge Microgateway. يخزّن الحصص ويديرها في الذاكرة المحلية.
healthcheck لا يعرض معلومات عن عملية Edge Microgateway، مثل استخدام الذاكرة واستخدام وحدة المعالجة المركزية وما إلى ذلك. لاستخدام المكوّن الإضافي، استدعِ عنوان URL /healthcheck على النسخة الافتراضية من Edge Microgateway. يهدف هذا المكوّن الإضافي إلى أن يكون مثالاً يمكنك استخدامه لـ تنفيذ المكوّن الإضافي الخاص بك للتحقّق من الحالة.

أماكن العثور على المكوّنات الإضافية الحالية

تتوفّر المكوّنات الإضافية الحالية المضمّنة مع Edge Microgateway هنا، حيث [prefix] هو دليل البادئة npm. يُرجى الاطّلاع على مكان تثبيت Edge Microgateway إذا لم تتمكّن من العثور على هذا الدليل.

[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins

إضافة المكوّنات الإضافية وضبطها

اتّبِع هذا النمط لإضافة المكوّنات الإضافية وضبطها:

  1. أوقِف Edge Microgateway.
  2. افتح ملف إعداد Edge Microgateway. لمزيد من التفاصيل، يُرجى الاطّلاع على إجراء تغييرات في الإعدادات للخيارات.
  3. أضِف المكوّن الإضافي إلى العنصر plugins:sequence في ملف الإعداد، على النحو التالي. يتم تنفيذ المكوّنات الإضافية بالترتيب الذي تظهر به في هذه القائمة.
edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
     level: info
     dir: /var/tmp
     stats_log_interval: 60
  plugins:
     dir: ../plugins
     sequence:   
     - oauth
     - plugin-name
  1. اضبط المكوّن الإضافي. تتضمّن بعض المكوّنات الإضافية مَعلمات اختيارية يمكنك ضبطها في الـ ملف الإعداد. على سبيل المثال، يمكنك إضافة المقطع التالي لضبط المكوّن الإضافي "منع الارتفاع المفاجئ في عدد الزيارات" . يُرجى الاطّلاع على مقالة استخدام المكوّن الإضافي "منع الارتفاع المفاجئ في عدد الزيارات" لمزيد من المعلومات. 
    edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - spikearrest
spikearrest:
   timeUnit: minute
   allow: 10
  1. احفظ الملف.
  2. أعِد تشغيل Edge Microgateway أو أعد تحميله، استنادًا إلى ملف الإعداد الذي عدّلته.

إعدادات خاصة بالمكوّن الإضافي

يمكنك إلغاء مَعلمات المكوّن الإضافي المحدّدة في ملف الإعداد من خلال إنشاء إعداد خاص بالمكوّن الإضافي في هذا الدليل:

[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins/config

حيث [prefix] هو دليل بادئة npm. يُرجى الاطّلاع على مكان تثبيت Edge Microgateway إذا لم تتمكّن من العثور على هذا الدليل.

plugins/<plugin_name>/config/default.yaml. على سبيل المثال، يمكنك وضع هذا المقطع في plugins/spikearrest/config/default.yaml، وسيؤدي ذلك إلى إلغاء أي إعدادات ضبط أخرى.

spikearrest:
   timeUnit: hour   
   allow: 10000   
   buffersize: 0

استخدام المكوّن الإضافي "منع الارتفاع المفاجئ في عدد الزيارات"

يحمي المكوّن الإضافي "منع الارتفاع المفاجئ في عدد الزيارات" من الارتفاع المفاجئ في عدد الزيارات. ويحدّ من عدد الطلبات التي تعالجها نسخة افتراضية من Edge Microgateway.

إضافة المكوّن الإضافي "منع الارتفاع المفاجئ في عدد الزيارات"

يُرجى الاطّلاع على مقالة إضافة المكوّنات الإضافية وضبطها.

نموذج إعداد للمكوّن الإضافي " منع الارتفاع المفاجئ في عدد الزيارات"

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - spikearrest
spikearrest:
   timeUnit: minute
   allow: 10
   bufferSize: 5

خيارات إعداد المكوّن الإضافي "منع الارتفاع المفاجئ في عدد الزيارات"

  • timeUnit: عدد المرّات التي تتم فيها إعادة ضبط نافذة تنفيذ المكوّن الإضافي "منع الارتفاع المفاجئ في عدد الزيارات". القيم الصالحة هي second أو minute.
  • allow: الحد الأقصى لعدد الطلبات المسموح بها خلال timeUnit. يُرجى الاطّلاع أيضًا على مقالة إذا كنت تشغّل عمليات متعدّدة من Edge Micro processes.
  • bufferSize: (اختياري، القيمة التلقائية = 0) إذا كانت bufferSize > 0، يخزّن المكوّن الإضافي "منع الارتفاع المفاجئ في عدد الزيارات" هذا العدد من الطلبات في مخزن مؤقت. وبمجرد حدوث "نافذة" التنفيذ التالية، ستتم معالجة الطلبات المخزّنة مؤقتًا أولاً. يُرجى الاطّلاع أيضًا على مقالة إضافة مخزن مؤقت.

كيف يعمل المكوّن الإضافي "منع الارتفاع المفاجئ في عدد الزيارات"؟

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

يختلف سلوك المكوّن الإضافي "منع الارتفاع المفاجئ في عدد الزيارات" في وقت التشغيل عن ما قد تتوقّعه من القيم الحرفية التي تدخلها لكل دقيقة أو لكل ثانية.

على سبيل المثال، لنفترض أنّك تحدّد معدّل 30 طلبًا في الدقيقة، على النحو التالي:

spikearrest:
   timeUnit: minute
   allow: 30

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

ما الذي يحدث فعلاً إذًا؟ لمنع السلوك المشابه للارتفاع المفاجئ في عدد الزيارات، ينظّم المكوّن الإضافي "منع الارتفاع المفاجئ في عدد الزيارات" الزيارات المسموح بها من خلال تقسيم إعداداتك إلى فواصل زمنية أصغر، على النحو التالي:

المعدّلات لكل دقيقة

يتم تنظيم المعدّلات لكل دقيقة في فواصل زمنية للطلبات المسموح بها بالثواني. على سبيل المثال، يتم تنظيم 30 طلبًا في الدقيقة على النحو التالي:

60 ثانية (دقيقة واحدة) / 30 = فواصل زمنية مدتها ثانيتان، أو طلب واحد مسموح به كل ثانيتَين تقريبًا. سيتعذّر تنفيذ طلب ثانٍ خلال ثانيتَين. أيضًا، سيتعذّر تنفيذ الطلب الحادي والثلاثين خلال دقيقة واحدة.

المعدّلات لكل ثانية

يتم تنظيم المعدّلات لكل ثانية في فواصل زمنية للطلبات المسموح بها بالملّي ثانية. على سبيل المثال، يتم تنظيم 10 طلبات في الثانية على النحو التالي:

1000 ملّي ثانية (ثانية واحدة) / 10 = فواصل زمنية مدتها 100 ملّي ثانية، أو طلب واحد مسموح به كل 100 ملّي ثانية تقريبًا . سيتعذّر تنفيذ طلب ثانٍ خلال 100 ملّي ثانية. أيضًا، سيتعذّر تنفيذ الطلب الحادي عشر خلال ثانية واحدة.

عند تجاوز الحدّ

إذا تجاوز عدد الطلبات الحدّ خلال الفترة الزمنية المحدّدة، يعرض المكوّن الإضافي "منع الارتفاع المفاجئ في عدد الزيارات" رسالة الخطأ هذه مع حالة HTTP 503:

{"error": "spike arrest policy violated"}

إضافة مخزن مؤقت

لديك خيار إضافة مخزن مؤقت إلى السياسة. لنفترض أنّك تضبط المخزن المؤقت على 10. ستلاحظ أنّ واجهة برمجة التطبيقات لا تعرض خطأً على الفور عند تجاوز الحدّ الذي يفرضه المكوّن الإضافي "منع الارتفاع المفاجئ في عدد الزيارات" بدلاً من ذلك، يتم تخزين الطلبات مؤقتًا (بما يصل إلى العدد المحدّد)، وتتم معالجة الطلبات المخزّنة مؤقتًا بمجرد توفّر نافذة التنفيذ المناسبة التالية. القيمة التلقائية لـ bufferSize هي 0.

إذا كنت تشغّل عمليات متعدّدة من Edge Micro processes

يعتمد عدد الطلبات المسموح بها على عدد عمليات عامل Edge Micro التي يتم تشغيلها. يحسب المكوّن الإضافي "منع الارتفاع المفاجئ في عدد الزيارات" العدد المسموح به من الطلبات لكل عملية عامل. تلقائيًا، يساوي عدد عمليات Edge Micro عدد وحدات المعالجة المركزية على الجهاز الذي تم تثبيت Edge Micro عليه. ومع ذلك، يمكنك ضبط عدد عمليات العامل عند بدء Edge Micro باستخدام الخيار --processes في الأمر start. على سبيل المثال، إذا كنت تريد أن يتم تفعيل المكوّن الإضافي "منع الارتفاع المفاجئ في عدد الزيارات" عند 100 طلب خلال فترة زمنية معيّنة، وإذا بدأت Edge Microgateway باستخدام الخيار --processes 4، اضبط allow: 25 في إعدادات المكوّن الإضافي "منع الارتفاع المفاجئ في عدد الزيارات". باختصار، القاعدة الأساسية هي ضبط مَعلمة الإعداد allow config على القيمة "عدد الارتفاع المفاجئ في عدد الزيارات المطلوب / عدد العمليات".

استخدام المكوّن الإضافي "الحصة"

تحدّد الحصة عدد رسائل الطلبات التي يُسمح لتطبيق بإرسالها إلى واجهة برمجة تطبيقات خلال ساعة أو يوم أو أسبوع أو شهر. عندما يصل التطبيق إلى الحدّ الأقصى للحصة، يتم رفض طلبات واجهة برمجة التطبيقات اللاحقة. يُرجى الاطّلاع أيضًا على مقالة ما الفرق بين منع الارتفاع المفاجئ في عدد الزيارات والمكوّن الإضافي "الحصة"؟.

إضافة المكوّن الإضافي "الحصة"

يُرجى الاطّلاع على مقالة إضافة المكوّنات الإضافية وضبطها.

إعدادات المنتج في Apigee Edge

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

  1. سجِّل الدخول إلى حساب مؤسستك على Apigee Edge.
  2. في واجهة مستخدم Edge، افتح المنتج المرتبط بالخادم الوكيل المتوافق مع البوابة المصغّرة الذي تريد تطبيق الحصة عليه.
    1. في واجهة المستخدم، انقر على المنتجات من قائمة "النشر".
    2. افتح المنتج الذي يحتوي على واجهة برمجة التطبيقات التي تريد تطبيق الحصة عليها.
    3. انقر على تعديل.
    4. في حقل "الحصة"، حدِّد فترة الحصة. على سبيل المثال، 100 طلب كل دقيقة واحدة. أو 50000 طلب كل ساعتَين.

  1. انقر على حفظ.
  2. تأكَّد من إضافة المنتج إلى تطبيق مطوّر. ستحتاج إلى المفاتيح من هذا التطبيق لإجراء طلبات واجهة برمجة تطبيقات مصادَق عليها.

نموذج إعداد للحصة

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - quota

خيارات إعداد المكوّن الإضافي "الحصة"

لضبط المكوّن الإضافي "الحصة"، أضِف العنصر quotas إلى ملف الإعداد، كما هو موضّح في المثال التالي: 

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - quota
quotas:
  bufferSize:
    hour: 20000
    minute: 500
    month: 1
    default: 10000
  useDebugMpId: true
  failOpen: true
  useRedis: true
  redisHost: localhost
  redisPort: 6379
  redisDb: 1
...
Option الوصف
buffersize (عدد صحيح) حجم المخزن المؤقت الذي سيتم ضبطه للفترة الزمنية المحدّدة. تشمل الوحدات الزمنية المسموح بها ما يلي: hour وminute وday وweek وmonth وdefault. (تمت الإضافة: الإصدار 3.0.9)
failOpen عند تفعيل هذه الميزة، إذا حدث خطأ في معالجة الحصة أو إذا تعذّر على طلب "تطبيق الحصة" المُرسَل إلى Edge تعديل عدّادات الحصة عن بُعد، ستتم معالجة الحصة استنادًا إلى الإحصاءات المحلية فقط إلى أن تتم مزامنة الحصة عن بُعد بنجاح في المرة التالية. في كلتا الحالتَين، يتم ضبط علامة quota-failed-open في عنصر الطلب. (تمت الإضافة: الإصدار 3.0.9)

لتفعيل ميزة "الحصة" "fail open"، اضبط الإعدادات التالية: 

edgemicro:
...
quotas:
  failOpen: true
 ...
useDebugMpId اضبط هذه العلامة على true لتفعيل تسجيل رقم تعريف معالج الرسائل في استجابات الحصة. (تمت الإضافة: الإصدار 3.0.9)

لاستخدام هذه الميزة، عليك تعديل الخادم الوكيل edgemicro-auth إلى الإصدار 3.0.7 أو إصدار أعلى وضبط الإعدادات التالية: 

edgemicro:
...
quotas:
  useDebugMpId: true
...

عند ضبط useDebugMpId، ستتضمّن استجابات الحصة من Edge رقم تعريف معالج الرسائل وسيتم تسجيلها من خلال Edge Microgateway. على سبيل المثال: 

{
    "allowed": 20,
    "used": 3,
    "exceeded": 0,
    "available": 17,
    "expiryTime": 1570748640000,
    "timestamp": 1570748580323,
    "debugMpId": "6a12dd72-5c8a-4d39-b51d-2c64f953de6a"
}
useRedis (قيمة منطقية) اضبط هذه العلامة على true لاستخدام وحدة قاعدة بيانات الحصة في Redis. عند ضبط هذه العلامة، تقتصر الحصة على نُسخ Edge Microgateway الافتراضية التي تتصل بـ Redis فقط. وإلا، سيكون عدّاد الحصة عالميًا. القيمة التلقائية: false (يتم استخدام وحدة redis-volos-apigee) (تمت الإضافة: الإصدار 3.0.10)
redisHost المضيف الذي يتم تشغيل نسخة Redis الافتراضية عليه. القيمة التلقائية: 127.0.0.1 (تمت الإضافة: الإصدار 3.0.10)
redisPort منفذ نسخة Redis الافتراضية. القيمة التلقائية: 6379 (تمت الإضافة: الإصدار 3.0.10)
redisDb قاعدة بيانات Redis التي سيتم استخدامها. القيمة التلقائية: 0 (تمت الإضافة: الإصدار 3.0.10)

فهم نطاق الحصة

يقتصر عدد الحصة على منتج واجهة برمجة تطبيقات. إذا كان لدى تطبيق مطوّر منتجات متعدّدة، يقتصر نطاق الحصة على كل منتج على حدة. لتحقيق هذا النطاق، ينشئ Edge Microgateway معرّف حصة يجمع بين "appName + productName".

اختبار المكوّن الإضافي "الحصة"

عند تجاوز الحصة، يتم عرض حالة HTTP 403 للعميل، بالإضافة إلى الرسالة التالية:

{"error": "exceeded quota"}

ما الفرق بين المكوّن الإضافي "منع الارتفاع المفاجئ في عدد الزيارات" والمكوّن الإضافي "الحصة"؟

من المهم اختيار الأداة المناسبة للمهمة المطلوبة. تضبط سياسات الحصة عدد رسائل الطلبات التي يُسمح لتطبيق عميل بإرسالها إلى واجهة برمجة تطبيقات خلال ساعة أو يوم أو أسبوع أو شهر. تفرض سياسة الحصة حدودًا للاستهلاك على تطبيقات العميل من خلال الاحتفاظ بعدّاد موزّع يحسب الطلبات الواردة.

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

استخدِم المكوّن الإضافي "منع الارتفاع المفاجئ في عدد الزيارات" للحماية من الارتفاع المفاجئ في عدد الزيارات إلى واجهة برمجة التطبيقات. عادةً، يتم استخدام المكوّن الإضافي "منع الارتفاع المفاجئ في عدد الزيارات" لمنع هجمات DDoS المحتمَلة أو غيرها من الهجمات الضارة.