استفاده از افزایه‌ها

درحال مشاهده اسناد Apigee Edge هستید.
به اسناد Apigee X بروید. اطلاعات

Edge Microgateway نسخه ۲.۴.x

مخاطبان

این موضوع برای اپراتورهای Edge Microgateway درنظر گرفته شده است که می‌خواهند از افزونه‌های موجودی که همراه با microgateway نصب شده‌اند استفاده کنند. همچنین افزایه‌های مهار جهش و سهمیه را به‌طور مفصل (هر دو با نصب ارائه می‌شوند) مورد بحث قرار می‌دهد. اگر توسعه‌دهنده‌ای هستید که می‌خواهید افزایه‌های جدید توسعه دهید، توسعه افزایه‌های سفارشی را ببینید.

افزایه Edge Microgateway چیست؟

افزایه یک واحد Node.js است که عملکرد را به Edge Microgateway اضافه می‌کند. واحدهای افزایه از الگوی ثابتی پیروی می‌کنند و در مکانی ذخیره می‌شوند که Edge Microgateway آن را می‌شناسد، و این امر باعث می‌شود ریزدروازه بتواند آن‌ها را به‌طور خودکار شناسایی و بار کند. ‫Edge Microgateway شامل چندین افزایه موجود است و همچنین می‌توانید افزایه‌های سفارشی ایجاد کنید، همان‌طور که در توسعه افزایه‌های سفارشی توضیح داده شده است.

افزایه‌های موجود همراه با Edge Microgateway

چندین افزایه موجود در زمان نصب Edge Microgateway ارائه می‌شود. این موارد شامل:

افزایه به‌طور پیش‌فرض فعال است شرح
analytics بله داده‌های تجزیه‌وتحلیل را از Edge Microgateway به Apigee Edge ارسال می‌کند.
oauth بله اعتبارسنجی کلید میانای برنامه‌سازی کاربردی و کد OAuth را به Edge Microgateway اضافه می‌کند. راه‌اندازی و پیکربندی Edge Microgateway را ببینید.
سهمیه نه سهمیه را برای درخواست‌های Edge Microgateway اعمال می‌کند. از Apigee Edge برای ذخیره و مدیریت سهمیه‌ها استفاده می‌کند. به استفاده از افزایه سهمیه مراجعه کنید.
spikearrest نه از کاربر دربرابر افزایش ناگهانی ترافیک و حمله‌های منع سرویس محافظت می‌کند. استفاده از افزایه «مهار جهش» را ببینید.
header-uppercase نه پراکسی نمونه‌ای که نظر داده شده است و به‌عنوان راهنمایی برای کمک به توسعه‌دهندگان در نوشتن افزایه‌های سفارشی درنظر گرفته شده است. Edge افزایه نمونه Microgateway را ببینید.
accumulate-request نه داده‌های درخواست را در یک شیء واحد جمع‌آوری می‌کند و سپس داده‌ها را به گرداننده بعدی در زنجیره افزایه ارسال می‌کند. برای نوشتن افزایه‌های تبدیل که باید روی یک شیء محتوای درخواست انباشته‌شده واحد عمل کنند مفید است.
accumulate-response نه داده‌های پاسخ را در یک شیء واحد جمع‌آوری می‌کند و سپس داده‌ها را به گرداننده بعدی در زنجیره افزایه منتقل می‌کند. برای نوشتن افزایه‌های تبدیل که باید روی یک شیء محتوای پاسخ انباشته‌شده واحد عمل کنند مفید است.
transform-uppercase نه داده‌های درخواست یا پاسخ را تبدیل می‌کند. این افزایه نشان‌دهنده پیاده‌سازی روال مطلوب افزایه تبدیل است. افزایه نمونه تبدیل ساده‌ای انجام می‌دهد (داده‌های درخواست یا پاسخ را به حروف بزرگ تبدیل می‌کند)؛ بااین‌حال، به‌راحتی می‌تواند برای انجام انواع دیگر تبدیل‌ها، مثل تبدیل XML به JSON، تطبیق داده شود.
json2xml نه داده‌های درخواست یا پاسخ را براساس سرایندهای پذیرش یا نوع محتوا تبدیل می‌کند. برای جزئیات، به اسناد افزایه در GitHub مراجعه کنید.
سهمیه-حافظه نه سهمیه را برای درخواست‌های Edge Microgateway اعمال می‌کند. سهمیه‌ها را در حافظه محلی ذخیره و مدیریت می‌کند.
healthcheck نه اطلاعاتی درباره فرایند Edge Microgateway برمی‌گرداند -- استفاده از حافظه، استفاده از واحد پردازش مرکزی، و غیره. برای استفاده از افزایه، نشانی وب /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: پنجره اجرای «مهار جهش» هر چند وقت یک‌بار بازنشانی می‌شود. مقادیر معتبر ثانیه یا دقیقه است.
  • اجازه دادن: حداکثر تعداد درخواست‌هایی که درطول timeUnit مجاز است.
  • bufferSize: (اختیاری، پیش‌فرض = ۰) اگر bufferSize > 0، «مهار جهش» این تعداد درخواست را در میان‌گیری ذخیره می‌کند. به‌محض اینکه «پنجره» اجرای بعدی رخ دهد، درخواست‌های بافرشده ابتدا پردازش خواهند شد. همچنین افزودن میان‌گیری را ببینید.

مهار جهش چگونه کار می‌کند؟

«مهار جهش» را به‌عنوان روشی برای محافظت کلی دربرابر جهش‌های ترافیک درنظر بگیرید، نه به‌عنوان روشی برای محدود کردن ترافیک به تعداد مشخصی از درخواست‌ها. میاناهای برنامه‌سازی کاربردی و زیرینه شما می‌توانند مقدار مشخصی از ترافیک را مدیریت کنند، و خط‌مشی «مهار جهش» به شما کمک می‌کند ترافیک را به مقادیر کلی موردنظرتان هموار کنید.

عملکرد جلوگیری از جهش زمان اجرا با آنچه ممکن است از مقادیر دقیق در هر دقیقه یا هر ثانیه که وارد می‌کنید انتظار داشته باشید متفاوت است.

برای مثال، فرض کنید نرخی معادل ۳۰ درخواست در دقیقه را به‌صورت زیر مشخص می‌کنید:

spikearrest:
   timeUnit: minute
   allow: 30

در آزمایش، ممکن است فکر کنید می‌توانید ۳۰ درخواست را در ۱ ثانیه ارسال کنید، به‌شرطی که در یک دقیقه ارسال شوند. اما خط‌مشی این تنظیم را به این شکل اجرا نمی‌کند. اگر به آن فکر کنید، ۳۰ درخواست در یک دوره ۱ ثانیه‌ای می‌تواند در برخی محیط‌ها به‌عنوان یک جهش کوچک درنظر گرفته شود.

پس درواقع چه اتفاقی می‌افتد؟ برای جلوگیری از رفتار جهشی، «مهار جهش» ترافیک مجاز را با تقسیم تنظیمات شما به بازه‌های زمانی کوچک‌تر هموار می‌کند، به این صورت:

نرخ‌های دقیقه‌ای

نرخ‌های دقیقه به فواصل مجاز درخواست‌های ثانیه تبدیل می‌شوند. برای مثال، ۳۰ درخواست در دقیقه به‌صورت زیر هموار می‌شود:

‫۶۰ ثانیه (۱ دقیقه) / ۳۰ = فواصل ۲ ثانیه‌ای، یا تقریباً ۱ درخواست مجاز در هر ۲ ثانیه. درخواست دوم در کمتر از ۲ ثانیه انجام نخواهد شد. همچنین، درخواست سی‌ویکم در یک دقیقه ناموفق خواهد بود.

نرخ‌های ثانیه‌ای

نرخ‌های ثانیه‌ای به درخواست‌های مجاز در فواصل میلی‌ثانیه‌ای تبدیل می‌شوند. برای مثال، ۱۰ درخواست/ثانیه به‌صورت زیر هموار می‌شود:

‫۱۰۰۰ میلی‌ثانیه (۱ ثانیه) / ۱۰ = فاصله‌های ۱۰۰ میلی‌ثانیه‌ای، یا حدود ۱ درخواست مجاز در هر ۱۰۰ میلی‌ثانیه . درخواست دوم در فاصله ۱۰۰ میلی‌ثانیه انجام نخواهد شد. همچنین، یازدهمین درخواست در یک ثانیه انجام نخواهد شد.

وقتی از حد مجاز فراتر می‌رود

اگر تعداد درخواست‌ها در بازه زمانی مشخص‌شده از حد مجاز فراتر برود، هشدار جهش این پیام خطا را با وضعیت HTTP 503 برمی‌گرداند:

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

درحال افزودن میان‌گیری

گزینه‌ای برای افزودن حاشیه به خط‌مشی دارید. فرض کنیم که حاشیه را روی ۱۰ تنظیم کنید. خواهید دید که وقتی از حد مجاز «مهار جهش» فراتر می‌روید، API بلافاصله خطا برنمی‌گرداند. درعوض، درخواست‌ها بافر می‌شوند (تا تعداد مشخص‌شده)، و درخواست‌های بافرشده به‌محض دردسترس قرار گرفتن پنجره اجرای مناسب بعدی پردازش می‌شوند. پیش‌فرض bufferSize صفر است.

استفاده از افزایه سهمیه

این بخش درباره افزایه سهمیه بحث می‌کند.

درباره افزایه سهمیه

سهمیه تعداد پیام‌های درخواستی را که یک برنامه مجاز است درطول یک ساعت، یک روز، یک هفته، یا یک ماه به یک API ارسال کند مشخص می‌کند. وقتی برنامه‌ای به حد سهمیه خود می‌رسد، فراخوانی‌های بعدی API رد می‌شود. همچنین تفاوت بین جلوگیری از جهش و سهمیه چیست؟ را ببینید.

درحال افزودن افزایه سهمیه

برای مراحل اولیه که باید برای هر افزایه‌ای دنبال کنید، به افزودن و پیکربندی افزایه‌ها مراجعه کنید.

پیکربندی محصول در Apigee Edge

سهمیه‌ها را در «واسط کاربر Apigee Edge» پیکربندی می‌کنید، جایی که محصولات میانای برنامه‌سازی کاربردی را پیکربندی می‌کنید. باید بدانید کدام محصول حاوی پراکسی آگاه از ریزدروازه‌ای است که می‌خواهید با سهمیه محدود کنید. این محصول باید به برنامه توسعه‌دهنده اضافه شود. وقتی بااستفاده از کلیدهای موجود در برنامه توسعه‌دهنده، تماس‌های API اصالت‌سنجی‌شده برقرار می‌کنید، سهمیه به آن تماس‌های API اعمال خواهد شد.

  1. به سیستم حساب سازمان Apigee Edge خود وارد شوید.
  2. در «میانای کاربری Edge»، محصول منسوب به پراکسی آگاه از دروازه کوچک را که می‌خواهید سهمیه را روی آن اعمال کنید باز کنید.
    1. در رابط کاربری، محصولات را از منو «انتشار» انتخاب کنید.
    2. محصول حاوی API را که می‌خواهید سهمیه را روی آن اعمال کنید باز کنید.
    3. روی ویرایش کلیک کنید.
    4. در فیلد «سهمیه»، بازه سهمیه را مشخص کنید. برای مثال، ۱۰۰ درخواست در هر یک دقیقه. یا ۵۰۰۰۰ درخواست در هر ۲ ساعت.

  1. روی ذخیره کلیک کنید.
  2. مطمئن شوید که محصول به برنامه توسعه‌دهنده اضافه شده باشد. برای انجام تماس‌های API اصیل‌سازی‌شده، به کلیدهای این برنامه نیاز دارید.

پیکربندی نمونه برای سهمیه

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

گزینه‌های پیکربندی برای سهمیه

گزینه‌های پیکربندی اضافی برای افزایه سهمیه وجود ندارد.

درحال آزمایش افزایه سهمیه

وقتی از سهمیه فراتر رفتید، وضعیت HTTP 403 همراه با پیام زیر به کارخواه برگردانده می‌شود: پیام زیر:

{"error": "exceeded quota"}

تفاوت بین مهار جهش و سهمیه چیست؟

انتخاب ابزار مناسب برای کار موردنظر مهم است. خط‌مشی‌های سهمیه تعداد پیام‌های درخواستی را که یک برنامه کارخواه مجاز است در طول یک ساعت، یک روز، یک هفته، یا یک ماه به یک API ارسال کند پیکربندی می‌کنند. خط‌مشی سهمیه با حفظ یک شمارنده توزیع‌شده که درخواست‌های ورودی را شمارش می‌کند، محدودیت‌های مصرف را در برنامه‌های مشتری اعمال می‌کند.

از خط‌مشی سهمیه برای اجرای قراردادهای کسب‌وکار یا «قراردادهای سطح خدمات» با توسعه‌دهندگان و شرکا استفاده کنید، نه برای مدیریت ترافیک عملیاتی. برای مثال، از سهمیه ممکن است برای محدود کردن ترافیک سرویس رایگان استفاده شود، درحالی‌که به مشتریان پولی دسترسی کامل داده می‌شود. همچنین استفاده از افزایه سهمیه را ببینید.

برای محافظت دربرابر افزایش ناگهانی ترافیک API، از «مهار جهش» استفاده کنید. معمولاً از «مهار جهش» برای جلوگیری از حمله‌های احتمالی «منع سرویس توزیع‌شده» یا حمله‌های مخرب دیگر استفاده می‌شود.