مرجع عملکرد و پیکربندی برای Edge Microgateway

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

Edge Microgateway نسخه ۲.۵.x

این موضوع نحوه مدیریت و پیکربندی Edge Microgateway را مورد بحث قرار می‌دهد.

ارتقا دادن Edge Microgateway درصورت داشتن اتصال اینترنت

  1. فرمان npm زیر را برای ارتقا به جدیدترین نسخه Edge Microgateway اجرا کنید: 
    npm upgrade edgemicro -g

    برای ارتقا به نسخه خاصی از Edge Microgateway، باید شماره نسخه را در فرمان ارتقا مشخص کنید. اگر شماره نسخه را مشخص نکنید، جدیدترین نسخه نصب خواهد شد. برای مثال، برای ارتقا به نسخه ۲.۵.۲۶، از فرمان زیر استفاده کنید:

    npm upgrade edgemicro@2.5.26 -g
  2. شماره نسخه را بررسی کنید؛ برای مثال، اگر نسخه ۲.۵.۲۶ را نصب کرده‌اید: 
    edgemicro --version
current nodejs version is v8.9.0
current edgemicro version is 2.5.26
  3. درنهایت، به جدیدترین نسخه پراکسی edgemicro-auth ارتقا دهید: 
    edgemicro upgradeauth -o org_name -e env_name -u username

درحال اعمال تغییرات پیکربندی

فایل‌های پیکربندی که باید درباره آن‌ها بدانید عبارتند از:

  • فایل پیکربندی پیش‌فرض سیستم
  • فایل پیکربندی پیش‌فرض برای نمونه Edge Microgateway که به‌تازگی مقداردهی اولیه شده است
  • فایل پیکربندی پویا برای نمونه‌های درحال اجرا

این بخش درباره این فایل‌ها و آنچه باید درباره تغییر آن‌ها بدانید بحث می‌کند.

فایل پیکربندی سیستم پیش‌فرض

وقتی Edge Microgateway را نصب می‌کنید، فایل پیکربندی سیستم پیش‌فرض در اینجا قرار می‌گیرد:

prefix/lib/node_modules/edgemicro/config/default.yaml

که prefix دایرکتوری پیشوند npm است. اگر نمی‌توانید این دایرکتوری را پیدا کنید، Edge Microgateway کجا نصب شده است را ببینید.

اگر فایل پیکربندی سیستم را تغییر دهید، باید Edge Microgateway را دوباره مقداردهی اولیه، پیکربندی، و بازراه‌اندازی کنید:

edgemicro init
edgemicro configure [params]
edgemicro start [params]

فایل پیکربندی پیش‌فرض برای نمونه‌های Edge Microgateway که به‌تازگی مقداردهی اولیه شده‌اند

وقتی edgemicro init را اجرا می‌کنید، فایل پیکربندی سیستم (که در بالا شرح داده شد)، default.yaml، در فهرست راهنمای ~/.edgemicro قرار می‌گیرد.

اگر فایل پیکربندی را در ~/.edgemicro تغییر دهید، باید Edge Microgateway را دوباره پیکربندی و بازراه‌اندازی کنید:

edgemicro stop
edgemicro configure [params]
edgemicro start [params]

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

وقتی edgemicro configure [params] را اجرا می‌کنید، فایل پیکربندی پویایی در ~/.edgemicro ایجاد می‌شود. نام فایل براساس این الگو است: org-env-config.yaml، که org و env نام‌های سازمان و محیط Apigee Edge شما هستند. می‌توانید از این فایل برای ایجاد تغییرات پیکربندی استفاده کنید و سپس آن‌ها را بدون زمان خرابی مجدداً بار کنید. برای مثال، اگر افزونه‌ای را اضافه و پیکربندی کنید، می‌توانید پیکربندی را بدون ایجاد زمان خرابی مجدداً بار کنید، همان‌طور که در زیر توضیح داده شده است.

اگر Edge Microgateway درحال اجرا است (گزینه زمان ازکارافتادگی صفر):

  1. پیکربندی Edge Microgateway را مجدداً بار کنید: 
    edgemicro reload -o org_name -e env_name -k key -s secret

    مکان:

    • org_name نام سازمان Edge شما است (باید سرپرست سازمان باشید).
    • env_name محیطی در سازمان شما است (مثل «test» یا «prod»).
    • key کلیدی است که قبلاً توسط فرمان پیکربندی برگردانده شده است.
    • secret کلیدی است که قبلاً توسط فرمان پیکربندی برگردانده شده است.

    برای مثال

    edgemicro reload -o docs -e test -k 701e70ee718ce6dc188...78b6181d000723 \
  -s 05c14356e42ed1...4e34ab0cc824

اگر Edge Microgateway متوقف شده است:

  1. بازراه‌اندازی Edge Microgateway: 
    edgemicro start -o org_name -e env_name -k key -s secret

    مکان:

    • org_name نام سازمان Edge شما است (باید سرپرست سازمان باشید).
    • env_name محیطی در سازمان شما است (مثل «test» یا «prod»).
    • key کلیدی است که قبلاً توسط فرمان پیکربندی برگردانده شده است.
    • secret کلیدی است که قبلاً توسط فرمان پیکربندی برگردانده شده است.

    برای مثال:

    edgemicro start -o docs -e test -k 701e70ee718ce...b6181d000723 \
  -s 05c1435...e34ab0cc824

در اینجا نمونه‌ای از فایل پیکربندی آورده شده است. برای جزئیات درباره تنظیمات فایل پیکربندی، به مرجع پیکربندی Edge Microgateway مراجعه کنید.

edge_config:
  bootstrap: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/docs/environment/test
  jwt_public_key: 'https://docs-test.apigee.net/edgemicro-auth/publicKey'
  managementUri: 'https://api.enterprise.apigee.com'
  vaultName: microgateway
  authUri: 'https://%s-%s.apigee.net/edgemicro-auth'
  baseUri: >-
    https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s
  bootstrapMessage: Please copy the following property to the edge micro agent config
  keySecretMessage: The following credentials are required to start edge micro
  products: 'https://docs-test.apigee.net/edgemicro-auth/products'
edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
headers:
  x-forwarded-for: true
  x-forwarded-host: true
  x-request-id: true
  x-response-time: true
  via: true
oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  verify_api_key_url: 'https://docs-test.apigee.net/edgemicro-auth/verifyApiKey'
analytics:
  uri: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/axpublisher/organization/docs/environment/test

تنظیم متغیرهای محیطی

فرمان‌های میانای خط فرمان که به مقادیری برای سازمان و محیط Edge شما نیاز دارند، و کلید و رمز لازم برای شروع Edge Microgateway را می‌توان در این متغیرهای محیطی ذخیره کرد:

  • EDGEMICRO_ORG
  • EDGEMICRO_ENV
  • EDGEMICRO_KEY
  • EDGEMICRO_SECRET

تنظیم این متغیرها اختیاری است. اگر آن‌ها را تنظیم کنید، لازم نیست مقادیرشان را هنگام استفاده از «میانای خط فرمان» (CLI) برای پیکربندی و راه‌اندازی Edge Microgateway مشخص کنید.

پیکربندی SSL در سرور Edge Microgateway

می‌توانید سرور Microgateway را برای استفاده از SSL پیکربندی کنید. برای مثال، با پیکربندی SSL، می‌توانید میاناهای برنامه‌سازی کاربردی را ازطریق Edge Microgateway با پروتکل «https» فراخوانی کنید، مانند این:

https://localhost:8000/myapi

برای پیکربندی SSL در سرور Microgateway، این مراحل را دنبال کنید:

  1. بااستفاده از ابزار openssl یا هر روشی که ترجیح می‌دهید، گواهی و کلید SSL تولید یا دریافت کنید.
  2. مشخصه edgemicro:ssl را به فایل پیکربندی Edge Microgateway اضافه کنید. برای فهرست کامل گزینه‌ها، جدول زیر را ببینید. برای مثال:
    edgemicro:
  ssl:
   key: <absolute path to the SSL key file>
   cert: <absolute path to the SSL cert file>
   passphrase: admin123 #option added in v2.2.2
   rejectUnauthorized: true #option added in v2.2.2
   requestCert: true
  3. Edge Microgateway را بازراه‌اندازی کنید. مراحل شرح‌داده‌شده در ایجاد تغییرات پیکربندی را بسته به اینکه کدام فایل پیکربندی را ویرایش کرده‌اید (فایل پیش‌فرض یا فایل پیکربندی زمان اجرا) دنبال کنید.

در اینجا مثالی از بخش edgemicro فایل پیکربندی با SSL پیکربندی‌شده آورده شده است:

edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
  ssl:
    key: /MyHome/SSL/em-ssl-keys/server.key
    cert: /MyHome/SSL/em-ssl-keys/server.crt
    passphrase: admin123 #option added in v2.2.2
    rejectUnauthorized: true #option added in v2.2.2

در اینجا فهرستی از همه گزینه‌های سرور پشتیبانی‌شده را مشاهده می‌کنید:

گزینه شرح
key مسیر فایل ca.key (در قالب PEM).
cert مسیر فایل ca.cert (در قالب PEM).
pfx مسیر فایل pfx حاوی کلید خصوصی، گواهی، و گواهی‌های CA کارخواه در قالب PFX.
passphrase رشته‌ای که حاوی عبارت عبور برای کلید خصوصی یا PFX است.
ca مسیر فایل حاوی فهرست گواهی‌های مورداعتماد در قالب PEM.
ciphers رشته‌ای که رمزهای مورداستفاده را شرح می‌دهد و با «:» از هم جدا شده‌اند.
rejectUnauthorized اگر درست باشد، گواهی سرور با فهرست مراجع صدور گواهی ارائه‌شده تأیید می‌شود. اگر درستی‌سنجی ناموفق باشد، خطایی برگردانده می‌شود.
secureProtocol روش SSL برای استفاده. برای مثال، SSLv3_method برای اجبار SSL به نسخه ۳.
servername نام سرور برای افزونه TLS «نشانگر نام سرور» (SNI).
requestCert درست برای SSL دوطرفه؛ نادرست برای SSL یک‌طرفه

درحال استفاده از گزینه‌های SSL/TLS کارخواه

می‌توانید Edge Microgateway را به‌گونه‌ای پیکربندی کنید که هنگام اتصال به نقاط پایانی هدف، کارخواه «امنیت لایه انتقال» یا SSL باشد. در فایل پیکربندی Microgateway، از عنصر targets برای تنظیم گزینه‌های SSL/TLS استفاده کنید.

این مثال تنظیماتی را ارائه می‌دهد که برای همه میزبان‌ها اعمال خواهد شد:

edgemicro:
...
targets:
  ssl:
    client:
      key: /Users/jdoe/nodecellar/twowayssl/ssl/client.key
      cert: /Users/jdoe/nodecellar/twowayssl/ssl/ca.crt
      passphrase: admin123
      rejectUnauthorized: true

در این مثال، تنظیمات فقط برای میزبان مشخص‌شده اعمال می‌شود:

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    ssl:
      client:
        key: /Users/myname/twowayssl/ssl/client.key
        cert: /Users/myname/twowayssl/ssl/ca.crt
        passphrase: admin123
        rejectUnauthorized: true

در اینجا مثالی برای TLS آورده شده است:

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    tls:
      client:
        pfx: /Users/myname/twowayssl/ssl/client.pfx
        passphrase: admin123
        rejectUnauthorized: true

در اینجا فهرستی از همه گزینه‌های مشتری پشتیبانی‌شده ارائه شده است:

گزینه شرح
pfx مسیر فایل pfx حاوی کلید خصوصی، گواهی، و گواهی‌های CA کارخواه در قالب PFX.
key مسیر فایل ca.key (در قالب PEM).
passphrase رشته‌ای که حاوی عبارت عبور برای کلید خصوصی یا PFX است.
cert مسیر فایل ca.cert (در قالب PEM).
ca مسیر فایل حاوی فهرست گواهی‌های مورداعتماد در قالب PEM.
ciphers رشته‌ای که رمزهای مورداستفاده را شرح می‌دهد و با «:» از هم جدا شده‌اند.
rejectUnauthorized اگر درست باشد، گواهی سرور با فهرست مراجع صدور گواهی ارائه‌شده تأیید می‌شود. اگر درستی‌سنجی ناموفق باشد، خطایی برگردانده می‌شود.
secureProtocol روش SSL برای استفاده. برای مثال، SSLv3_method برای اجبار SSL به نسخه ۳.
servername نام سرور برای افزونه TLS «نشانگر نام سرور» (SNI).

سفارشی‌سازی کردن پراکسی edgemicro-auth

به‌طور پیش‌فرض، Edge Microgateway از پراکسی مستقرشده در Apigee Edge برای اصالت‌سنجی OAuth2 استفاده می‌کند. این پراکسی زمانی مستقر می‌شود که برای اولین‌بار edgemicro configure را اجرا می‌کنید. می‌توانید پیکربندی پیش‌فرض این پراکسی را تغییر دهید تا پشتیبانی از ادعاهای سفارشی را به JSON Web Token (JWT) اضافه کنید، انقضای ژتون را پیکربندی کنید، و ژتون‌های بازآوری تولید کنید. برای جزئیات، صفحه edgemicro-auth را در GitHub ببینید.

استفاده از سرویس اصالت‌سنجی سفارشی

به‌طور پیش‌فرض، Edge Microgateway از پراکسی مستقرشده در Apigee Edge برای اصالت‌سنجی OAuth2 استفاده می‌کند. این پراکسی زمانی مستقر می‌شود که برای اولین‌بار edgemicro configure را اجرا می‌کنید. به‌طور پیش‌فرض، نشانی وب این پراکسی در فایل پیکربندی Edge Microgateway به‌صورت زیر مشخص شده است:

authUri: https://myorg-myenv.apigee.net/edgemicro-auth

اگر می‌خواهید از سرویس سفارشی خودتان برای رسیدگی به اصالت‌سنجی استفاده کنید، مقدار authUri را در فایل پیکربندی تغییر دهید تا به سرویس شما اشاره کند. برای مثال، ممکن است سرویسی داشته باشید که از LDAP برای تأیید هویت استفاده می‌کند.

درحال مدیریت فایل‌های گزارش

Edge Microgateway اطلاعات مربوط به هر درخواست و پاسخ را ثبت می‌کند. فایل‌های گزارش اطلاعات مفیدی برای اشکال‌زدایی و عیب‌یابی ارائه می‌دهند.

محل ذخیره شدن فایل‌های گزارش

به‌طور پیش‌فرض، فایل‌های گزارش در /var/tmp ذخیره می‌شوند.

نحوه تغییر دادن فهرست راهنمای فایل گزارش پیش‌فرض

فهرست راهنمایی که فایل‌های گزارش در آن ذخیره می‌شود در فایل پیکربندی Edge Microgateway مشخص شده است. ایجاد تغییرات پیکربندی را نیز ببینید.

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

مقدار dir را تغییر دهید تا فهرست راهنمای فایل گزارش دیگری را مشخص کنید.

ارسال گزارش‌ها به کنسول

می‌توانید ثبت گزارش را به‌گونه‌ای پیکربندی کنید که اطلاعات گزارش به‌جای ارسال به فایل گزارش، به برونداد استاندارد ارسال شود. پرچم to_console را به‌صورت زیر روی true تنظیم کنید:

edgemicro:
  logging:
    to_console: true

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

نحوه تنظیم سطح ثبت گزارش

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

نحوه تغییر دادن فواصل گزارش‌گیری

می‌توانید این فاصله‌ها را در فایل پیکربندی Edge Microgateway پیکربندی کنید. ایجاد تغییرات پیکربندی را نیز ببینید.

مشخصه‌های قابل‌پیکربندی عبارت‌اند از:

  • stats_log_interval: (پیش‌فرض: ۶۰) فاصله زمانی، برحسب ثانیه، که در آن سابقه آمار در فایل گزارش API نوشته می‌شود.
  • rotate_interval: (پیش‌فرض: ۲۴) فاصله زمانی، برحسب ساعت، که فایل‌های گزارش چرخانده می‌شوند. برای مثال:
edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

روش‌های خوب نگهداری فایل گزارش

ازآنجایی‌که داده‌های فایل گزارش به‌مرور زمان انباشته می‌شوند، Apigee توصیه می‌کند که از روش‌های زیر استفاده کنید:

  • چون فایل‌های گزارش می‌توانند بسیار بزرگ شوند، مطمئن شوید که فهرست راهنمای فایل گزارش فضای کافی داشته باشد. بخش‌های زیر را ببینید: محل ذخیره فایل‌های گزارش و نحوه تغییر دادن فهرست راهنمای پیش‌فرض فایل گزارش.
  • حداقل هفته‌ای یک‌بار فایل‌های گزارش را حذف کنید یا به فهرست بایگانی جداگانه‌ای منتقل کنید.
  • اگر خط‌مشی شما حذف گزارش‌ها است، می‌توانید از فرمان CLI edgemicro log -c برای برداشتن (پاک کردن) گزارش‌های قدیمی‌تر استفاده کنید.

قرارداد نام‌گذاری فایل گزارش

هر نمونه Edge Microgateway سه نوع فایل گزارش تولید می‌کند:

  • api - همه درخواست‌ها و پاسخ‌هایی را که ازطریق Edge Microgateway جریان می‌یابند ثبت می‌کند. شمارنده‌های میانای برنامه‌سازی کاربردی (آمار) و خطاها نیز در این فایل ثبت می‌شوند.
  • err - هر چیزی را که به stderr ارسال شده است ثبت می‌کند.
  • out - هر چیزی را که به stdout ارسال شده است ثبت می‌کند.

این قرارداد نام‌گذاری است:

edgemicro-<Host Name>-<Instance ID>-<Log Type>.log

برای مثال:

edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log
edgemicro-mymachine-local-MTQzNTg1NDMODAyMQ-err.log
edgemicro-mymachine-local-mtqzntgndmxodaymq-out.log

درباره محتوای فایل گزارش

اضافه‌شده در: نسخه ۲.۳.۳

به‌طور پیش‌فرض، سرویس ثبت گزارش JSON پراکسی‌ها، محصولات، و JSON Web Token (JWT) بارگیری‌شده را حذف می‌کند. اگر می‌خواهید این اشیاء را به فایل‌های گزارش خروجی دهید، DEBUG=* را هنگام شروع Edge Microgateway تنظیم کنید. برای مثال:

DEBUG=* edgemicro start -o docs -e test -k abc123 -s xyz456

محتوای فایل گزارش «api»

فایل گزارش «api» حاوی اطلاعات دقیقی درباره جریان درخواست‌ها و پاسخ‌ها ازطریق Edge Microgateway است. نام فایل‌های گزارش «api» به این صورت است:

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

برای هر درخواست ارسالی به Edge Microgateway، چهار رویداد در فایل گزارش «api» ثبت می‌شود:

  • درخواست ورودی از مشتری
  • درخواست خروجی به هدف ارسال شد
  • پاسخ ورودی از هدف
  • پاسخ ارسالی به کارخواه

هرکدام از این ورودی‌های جداگانه با نماد اختصاری نشان داده می‌شود تا فایل‌های گزارش فشرده‌تر شوند. در اینجا چهار ورودی نمونه آورده شده است که هرکدام یکی از چهار رویداد را نشان می‌دهد. در فایل گزارش، این خطاها به این شکل هستند (شماره‌های خط فقط برای ارجاع در سند هستند و در فایل گزارش نشان داده نمی‌شوند).

(1) 1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
(2) 1436403888665 info treq m=GET, u=/, h=127.0.0.18080, i=0
(3) 1436403888672 info tres s=200, d=7, i=0
(4) 1436403888676 info res s=200, d=11, i=0

بیایید یکی‌یکی به آن‌ها نگاه کنیم:

۱. نمونه درخواست ورودی از مشتری:

1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
  • 1436403888651 - مُهر تاریخ یونیکس
  • info - بستگی به بافت دارد. بسته به سطح گزارش، می‌تواند info (اطلاعات)، warn (هشدار)، یا error (خطا) باشد. می‌تواند stats برای سابقه آمار، warn برای هشدارها، یا error برای خطاها باشد.
  • req - رویداد را شناسایی می‌کند. در این مورد، درخواست از کلاینت.
  • m - فعل HTTP استفاده‌شده در درخواست.
  • u - بخشی از نشانی وب که پس‌از مسیر پایه می‌آید.
  • h - میزبان و شماره درگاهی که Edge Microgateway در آن گوش می‌دهد.
  • r - میزبان و درگاه راه دور که درخواست مشتری از آنجا منشأ گرفته است.
  • i - شناسه درخواست. هر چهار ورودی رویداد این شناسه را هم‌رسانی خواهند کرد. به هر درخواست یک شناسه درخواست یکتا اختصاص داده می‌شود. مرتبط کردن سوابق گزارش با شناسه درخواست می‌تواند اطلاعات آماری ارزشمندی درباره تأخیر هدف ارائه دهد.
  • d - مدت زمان برحسب میلی‌ثانیه از زمانی که درخواست توسط Edge Microgateway دریافت شد. در مثال بالا، پاسخ هدف برای درخواست ۰ پس‌از ۷ میلی‌ثانیه دریافت شد (خط ۳)، و پاسخ پس‌از ۴ میلی‌ثانیه دیگر به مشتری ارسال شد (خط ۴). به عبارت دیگر، کل تأخیر درخواست ۱۱ میلی‌ثانیه بود که از این مقدار، ۷ میلی‌ثانیه توسط هدف و ۴ میلی‌ثانیه توسط خود Edge Microgateway صرف شد.

۲. نمونه درخواست خروجی به هدف:

1436403888665 info treq m=GET, u=/, h=127.0.0.1:8080, i=0
  • 1436403888651 - مُهر تاریخ یونیکس
  • info - بستگی به بافت دارد. بسته به سطح گزارش، می‌تواند info (اطلاعات)، warn (هشدار)، یا error (خطا) باشد. می‌تواند stats برای سابقه آمار، warn برای هشدارها، یا error برای خطاها باشد.
  • treq - رویداد را شناسایی می‌کند. دراین‌صورت، درخواست هدف.
  • m - فعل HTTP استفاده‌شده در درخواست هدف.
  • u - بخشی از نشانی وب که پس‌از مسیر پایه می‌آید.
  • h - شماره میزبان و درگاه هدف باطن.
  • i - شناسه ورودی گزارش. هر چهار ورودی رویداد این شناسه را هم‌رسانی خواهند کرد.

۳. نمونه پاسخ ورودی از هدف

1436403888672 info tres s=200, d=7, i=0

1436403888651 - مُهر تاریخ یونیکس

  • info - بستگی به بافت دارد. بسته به سطح گزارش، می‌تواند info (اطلاعات)، warn (هشدار)، یا error (خطا) باشد. می‌تواند stats برای سابقه آمار، warn برای هشدارها، یا error برای خطاها باشد.
  • tres - رویداد را شناسایی می‌کند. در این مورد، پاسخ هدف.
  • s - وضعیت پاسخ‌های HTTP.
  • d - مدت‌زمان به میلی‌ثانیه. زمان صرف‌شده برای فراخوانی میانای برنامه‌سازی کاربردی توسط هدف.
  • i - شناسه ورودی گزارش. هر چهار ورودی رویداد این شناسه را هم‌رسانی خواهند کرد.

۴. نمونه پاسخ ارسالی به مشتری

1436403888676 info res s=200, d=11, i=0

1436403888651 - مُهر تاریخ یونیکس

  • info - بستگی به بافت دارد. بسته به سطح گزارش، می‌تواند info (اطلاعات)، warn (هشدار)، یا error (خطا) باشد. می‌تواند stats برای سابقه آمار، warn برای هشدارها، یا error برای خطاها باشد.
  • res - رویداد را شناسایی می‌کند. در این مورد، پاسخ به کارخواه.
  • s - وضعیت پاسخ‌های HTTP.
  • d - مدت‌زمان به میلی‌ثانیه. این کل زمان صرف‌شده برای فراخوانی میانای برنامه‌سازی کاربردی است، ازجمله زمان صرف‌شده برای میانای برنامه‌سازی کاربردی هدف و زمان صرف‌شده توسط خود Edge Microgateway.
  • i - شناسه ورودی گزارش. هر چهار ورودی رویداد این شناسه را هم‌رسانی خواهند کرد.

زمان‌بندی فایل گزارش

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

پیام‌های خطا

برخی‌از ورودی‌های گزارش حاوی پیام‌های خطا خواهند بود. برای کمک به شناسایی محل و دلیل وقوع خطاها، مرجع خطای Edge Microgateway را ببینید.

مرجع پیکربندی Edge Microgateway

مکان فایل پیکربندی

مشخصه‌های پیکربندی شرح‌داده‌شده در این بخش در فایل پیکربندی Edge Microgateway قرار دارند. ایجاد تغییرات پیکربندی را نیز ببینید.

مشخصه‌های edge_config

از این تنظیمات برای پیکربندی تعامل بین نمونه Edge Microgateway و Apigee Edge استفاده می‌شود.

  • bootstrap: (پیش‌فرض: هیچ‌کدام) نشانی وبی که به سرویس Edge Microgateway-specific درحال اجرا در Apigee Edge اشاره می‌کند. Edge Microgateway از این سرویس برای ارتباط با Apigee Edge استفاده می‌کند. این نشانی وب زمانی برگردانده می‌شود که فرمان تولید جفت کلید عمومی/خصوصی را اجرا کنید: edgemicro genkeys. برای جزئیات، راه‌اندازی و پیکربندی Edge Microgateway را ببینید.
  • jwt_public_key: (پیش‌فرض: هیچ) نشانی وبی که به پراکسی Edge Microgateway که در Apigee Edge مستقر شده است اشاره می‌کند. این پراکسی به‌عنوان نقطه پایانی اصالت‌سنجی برای صدور کد دسترسی امضاشده برای سرویس‌گیرندگان عمل می‌کند. این نشانی وب وقتی برگردانده می‌شود که فرمان استقرار پراکسی را اجرا کنید: edgemicro configure. برای جزئیات، راه‌اندازی و پیکربندی Edge Microgateway را ببینید.

مشخصه‌های edgemicro

این تنظیمات فرایند Edge Microgateway را پیکربندی می‌کند.

  • درگاه: (پیش‌فرض: ۸۰۰۰) شماره درگاهی که فرایند Edge Microgateway به آن گوش می‌دهد.
  • max_connections: (پیش‌فرض: -1) حداکثر تعداد اتصالات ورودی هم‌زمان را که Edge Microgateway می‌تواند دریافت کند مشخص می‌کند. اگر از این تعداد فراتر بروید، وضعیت زیر برگردانده می‌شود:

    res.statusCode = 429; // Too many requests
  • max_connections_hard: (پیش‌فرض: -1) حداکثر تعداد درخواست‌های هم‌زمان که Edge Microgateway می‌تواند قبل‌از قطع اتصال دریافت کند. این تنظیم برای خنثی کردن حملات منع سرویس درنظر گرفته شده است. معمولاً آن را روی عددی بزرگ‌تر از max_connections تنظیم کنید.
  • ورود به سیستم:
    • level: (پیش‌فرض: error)
      • info - همه درخواست‌ها و پاسخ‌هایی را که ازطریق نمونه Edge Microgateway جریان می‌یابند ثبت می‌کند.
      • warn - فقط پیام‌های هشدار را ثبت می‌کند.
      • error - فقط پیام‌های خطا را ثبت می‌کند.
    • dir: (پیش‌فرض: var/tmp/) دایرکتوری‌ای که فایل‌های گزارش در آن ذخیره می‌شوند.
    • stats_log_interval: (پیش‌فرض: ۶۰) فاصله زمانی، برحسب ثانیه، که در آن سوابق آمار در فایل گزارش api نوشته می‌شود.
    • rotate_interval: (پیش‌فرض: ۲۴) فاصله زمانی، برحسب ساعت، که فایل‌های گزارش چرخانده می‌شوند.
  • افزایه‌ها: افزایه‌ها عملکرد را به Edge Microgateway اضافه می‌کنند. برای جزئیات بیشتر درباره توسعه افزونه‌ها، به توسعه افزونه‌های سفارشی مراجعه کنید.
  • dir: مسیر نسبی از دایرکتوری gateway/. به دایرکتوری plugins/. یا مسیر مطلق.
  • sequence: فهرستی از ماژول‌های افزونه برای افزودن به نمونه Edge Microgateway شما. واحدها به ترتیبی که در اینجا مشخص شده است اجرا خواهند شد.
  • اشکال‌زدایی: اشکال‌زدایی ازراه‌دور را به فرایند Edge Microgateway اضافه می‌کند.
    • درگاه: شماره درگاهی که باید به آن گوش داده شود. برای مثال، اشکال‌زدای IDE خود را تنظیم کنید تا به این درگاه گوش دهد.
    • args: متغیرهای مستقل برای فرایند اشکال‌زدایی. برای مثال: args --nolazy
  • config_change_poll_interval: (پیش‌فرض: ۶۰۰ ثانیه) Edge Microgateway پیکربندی جدیدی را به‌صورت دوره‌ای بار می‌کند و اگر چیزی تغییر کرده باشد، بارگیری مجدد را اجرا می‌کند. نظرسنجی هرگونه تغییر ایجادشده در Edge (تغییرات در محصولات، پراکسی‌های آگاه از ریزدروازه، و غیره) و همچنین تغییرات ایجادشده در فایل پیکربندی محلی را دریافت می‌کند.
  • disable_config_poll_interval: (پیش‌فرض: false) برای خاموش کردن نظرسنجی تغییر خودکار، روی true تنظیم کنید.
  • request_timeout: زمان استراحت را برای درخواست‌های هدف تنظیم می‌کند. زمان استراحت برحسب ثانیه تنظیم شده است. اگر وقفه زمانی رخ دهد، Edge Microgateway با رمز وضعیت ۵۰۴ پاسخ می‌دهد. (افزوده‌شده v2.4.x)

مشخصه‌های سرصفحه

این تنظیمات نحوه برخورد با برخی‌از سرایندهای HTTP را پیکربندی می‌کند.

  • x-forwarded-for: (پیش‌فرض: true) روی false تنظیم کنید تا از ارسال سرصفحه‌های x-forwarded-for به هدف جلوگیری شود. توجه داشته باشید که اگر سرصفحه x-forwarded-for در درخواست باشد، مقدار آن روی مقدار client-ip در Edge Analytics تنظیم خواهد شد.
  • x-forwarded-host: (پیش‌فرض: درست) روی نادرست تنظیم کنید تا از ارسال سرصفحه‌های x-forwarded-host به هدف جلوگیری شود.
  • x-request-id: (پیش‌فرض: true) روی false تنظیم کنید تا از ارسال سرصفحه‌های x-request-id به هدف جلوگیری شود.
  • x-response-time: (پیش‌فرض: درست) روی نادرست تنظیم کنید تا از ارسال سرایندهای x-response-time به هدف جلوگیری شود.
  • via: (پیش‌فرض: true) روی false تنظیم کنید تا از ارسال سرصفحه‌های via به هدف جلوگیری شود.

مشخصه‌های oauth

این تنظیمات نحوه اعمال اصالت‌سنجی کارخواه توسط Edge Microgateway را پیکربندی می‌کند.

  • allowNoAuthorization: (پیش‌فرض: false) اگر روی true تنظیم شود، تماس‌های API مجازند بدون هیچ‌گونه سرصفحه «مجوز» از Edge Microgateway عبور کنند. این را روی false تنظیم کنید تا سرایند «مجوز» لازم باشد (پیش‌فرض).
  • allowInvalidAuthorization: (پیش‌فرض: نادرست) اگر روی درست تنظیم شود، فراخوانی‌های میانای برنامه‌سازی کاربردی درصورتی‌که کد ارسال‌شده در سرصفحه «مجوز» نامعتبر یا منقضی‌شده باشد، مجاز به عبور هستند. این را روی false تنظیم کنید تا به کدهای معتبر نیاز داشته باشید (پیش‌فرض).
  • authorization-header: (پیش‌فرض: Authorization: Bearer) سرصفحه استفاده‌شده برای ارسال کد دسترسی به Edge Microgateway. ممکن است بخواهید پیش‌فرض را در مواردی تغییر دهید که هدف باید از سرایند «مجوز» برای هدف دیگری استفاده کند.
  • api-key-header: (پیش‌فرض: x-api-key) نام سرصفحه یا پارامتر پُرسمان استفاده‌شده برای ارسال کلید میانای برنامه‌سازی کاربردی به Edge Microgateway. استفاده از کلید میانای برنامه‌سازی کاربردی را نیز ببینید.
  • keep-authorization-header: (پیش‌فرض: false) اگر روی true تنظیم شود، سرصفحه Authorization ارسال‌شده در درخواست به هدف منتقل می‌شود (حفظ می‌شود).
  • allowOAuthOnly -- اگر روی true تنظیم شود، هر میانای برنامه‌سازی کاربردی باید یک سرصفحه «مجوز» با «کد دسترسی حامل» داشته باشد. به شما امکان می‌دهد فقط مدل امنیتی OAuth را مجاز کنید (درحالی‌که سازگاری با نسخه قدیمی حفظ می‌شود). (افزوده‌شده در نسخه ۲.۴.x)
  • allowAPIKeyOnly -- اگر روی true تنظیم شود، هر API باید یک سرصفحه x-api-key (یا یک مکان سفارشی) با یک کلید API داشته باشد.به شما امکان می‌دهد فقط مدل امنیتی کلید API را مجاز کنید (درحالی‌که سازگاری با نسخه‌های قدیمی حفظ می‌شود). (اضافه‌شده در نسخه ۲.۴.x)
  • gracePeriod -- این پارامتر به جلوگیری از خطاهای ناشی از اختلافات جزئی بین ساعت سیستم شما و زمان‌های «نه قبل‌از» (nbf) یا «صادرشده در» (iat) مشخص‌شده در کد مجوز JWT کمک می‌کند. این پارامتر را روی تعداد ثانیه‌هایی تنظیم کنید که برای چنین مغایرت‌هایی مجاز است. (نسخه ۲.۵.۷ اضافه شد)

مشخصه‌های مختص افزایه

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

پراکسی‌های فیلترکننده

می‌توانید فیلتر کنید که کدام پراکسی‌های آگاه از ریزدروازه توسط نمونه Edge Microgateway پردازش شوند. وقتی Edge Microgateway شروع می‌شود، همه پراکسی‌های آگاه از microgateway را در سازمانی که با آن مرتبط است بارگیری می‌کند. از پیکربندی زیر برای محدود کردن پراکسی‌هایی که microgateway پردازش خواهد کرد استفاده کنید. برای مثال، این پیکربندی پراکسی‌هایی را که ریزدروازه پردازش خواهد کرد به سه مورد محدود می‌کند: edgemicro_proxy-1، edgemicro_proxy-2، و edgemicro_proxy-3:

proxies:
  - edgemicro_proxy-1
  - edgemicro_proxy-2
  - edgemicro_proxy-3

درحال پیکربندی بسامد ارسال Analytics

از این پارامترهای پیکربندی برای کنترل کردن فرکانسی که Edge Microgateway داده‌های تحلیلی را به Apigee ارسال می‌کند استفاده کنید:

  • bufferSize (اختیاری): حداکثر تعداد سوابق تجزیه‌وتحلیل که میان‌گیر می‌تواند قبل‌از شروع به حذف قدیمی‌ترین سوابق نگه دارد. پیش‌فرض: ۱۰۰۰۰
  • batchSize (اختیاری): حداکثر اندازه دسته‌ای از سوابق تجزیه‌وتحلیل ارسال‌شده به Apigee. پیش‌فرض: ۵۰۰
  • flushInterval (اختیاری): تعداد میلی‌ثانیه‌های بین هر تخلیه دسته‌ای از رکوردهای تجزیه‌وتحلیل ارسال‌شده به Apigee. پیش‌فرض: ۵۰۰۰

برای مثال:

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

درحال پنهان کردن داده‌های تجزیه‌وتحلیل

پیکربندی زیر از نمایش اطلاعات مسیر درخواست در Edge analytics جلوگیری می‌کند. برای پنهان کردن شناسه URI درخواست و/یا مسیر درخواست، موارد زیر را به پیکربندی microgateway اضافه کنید. توجه داشته باشید که URI شامل بخش‌های نام میزبان و مسیر درخواست است.

analytics:
  mask_request_uri: 'string_to_mask'
  mask_request_path: 'string_to_mask'

جداسازی فراخوانی‌های میانای برنامه‌سازی کاربردی در Edge Analytics

می‌توانید افزونه تجزیه‌وتحلیل را برای جداسازی مسیر API خاصی پیکربندی کنید تا به‌عنوان پراکسی جداگانه‌ای در داشبوردهای Edge Analytics نشان داده شود. برای مثال، می‌توانید یک میانای برنامه‌سازی کاربردی بررسی سلامت را در داشبورد جدا کنید تا با فراخوانی‌های واقعی پراکسی میانای برنامه‌سازی کاربردی اشتباه گرفته نشود. در داشبورد Analytics، پراکسی‌های تفکیک‌شده از این الگوی نام‌گذاری پیروی می‌کنند:

edgemicro_proxyname-health

تصویر زیر دو پراکسی تفکیک‌شده را در داشبورد Analytics نشان می‌دهد: edgemicro_hello-health و edgemicro_mock-health:

از این پارامترها برای جدا کردن مسیرهای نسبی و مطلق در داشبورد Analytics به‌عنوان پراکسی‌های جداگانه استفاده کنید:

  • relativePath (اختیاری): مسیر نسبی را برای تفکیک در داشبورد Analytics مشخص می‌کند. برای مثال، اگر /healthcheck را مشخص کنید، همه فراخوانی‌های API که حاوی مسیر /healthcheck باشند به‌صورت edgemicro_proxyname-health در داشبورد نشان داده می‌شوند. توجه داشته باشید که این پرچم مسیر پایه پراکسی را نادیده می‌گیرد. برای تفکیک براساس مسیر کامل، ازجمله مسیر پایه، از پرچم proxyPath استفاده کنید.
  • proxyPath (اختیاری): مسیر کامل پراکسی میانای برنامه‌سازی کاربردی را، شامل مسیر پایه پراکسی، برای تفکیک در داشبورد Analytics مشخص می‌کند. برای مثال، اگر /mocktarget/healthcheck را مشخص کنید، که در آن /mocktarget مسیر پایه پراکسی است، همه فراخوانی‌های API با مسیر /mocktarget/healthcheck به‌صورت edgemicro_proxyname-health در داشبورد نشان داده خواهند شد.

برای مثال، در پیکربندی زیر، هر مسیر API که حاوی /healthcheck باشد، توسط افزونه تجزیه‌وتحلیل جدا خواهد شد. یعنی /foo/healthcheck و /foo/bar/healthcheck به‌عنوان پراکسی جداگانه‌ای به‌نام edgemicro_proxyname-health در داشبورد تجزیه‌وتحلیل تفکیک خواهند شد.

analytics:
  uri: >-
    https://xx/edgemicro/ax/org/docs/environment/test
  bufferSize: 100
  batchSize: 50
  flushInterval: 500
  relativePath: /healthcheck

در پیکربندی زیر، هر میانای برنامه‌سازی کاربردی با مسیر پراکسی /mocktarget/healthcheck به‌عنوان پراکسی جداگانه‌ای به‌نام edgemicro_proxyname-health در داشبورد تجزیه‌وتحلیل تفکیک خواهد شد.

analytics:
  uri: >-
    https://xx/edgemicro/ax/org/docs/environment/test
  bufferSize: 100
  batchSize: 50
  flushInterval: 500
  proxyPath: /mocktarget/healthcheck

راه‌اندازی Edge Microgateway پشت دیوار آتش شرکت

پشتیبانی‌شده v2.4.x

اگر Edge Microgateway پشت دیوار آتش نصب شده باشد، ممکن است دروازه نتواند با Apigee Edge ارتباط برقرار کند. در این مورد، دو گزینه وجود دارد که می‌توانید درنظر بگیرید:

گزینه ۱:

گزینه اول این است که گزینه edgemicro: proxy_tunnel را در فایل پیکربندی microgateway روی true تنظیم کنید:

edge_config:

    proxy: http://10.224.16.85:3128
    proxy_tunnel: true

وقتی proxy_tunnel true باشد، Edge Microgateway از روش CONNECT HTTP برای تونل‌سازی درخواست‌های HTTP ازطریق یک اتصال TCP استفاده می‌کند. (اگر متغیرهای محیطی برای پیکربندی پراکسی دارای TLS فعال باشند نیز همین‌طور است).

گزینه ۲:

گزینه دوم این است که پراکسی را مشخص کنید و proxy_tunnel را در فایل پیکربندی microgateway روی false تنظیم کنید. برای مثال:

edge_config:
     proxy: http://10.224.16.85:3128
     proxy_tunnel: false

در این حالت، می‌توانید متغیرهای زیر را برای کنترل میزبان‌ها برای هر پراکسی HTTP که می‌خواهید استفاده کنید، یا اینکه کدام میزبان‌ها نباید پراکسی‌های Edge Microgateway را مدیریت کنند، تنظیم کنید: HTTP_PROXY،‏ HTTPS_PROXY، و NO_PROXY.

می‌توانید NO_PROXY را به‌عنوان فهرست دامنه‌های جداشده با کاما تنظیم کنید که Edge Microgateway نباید به آن‌ها پراکسی کند. برای مثال:

export NO_PROXY='localhost,localhost:8080'

HTTP_PROXY و HTTPS_PROXY را روی نقطه پایانی پروکسی HTTP تنظیم کنید که Edge Microgateway بتواند به آن پیام ارسال کند. برای مثال:

export HTTP_PROXY='http://localhost:3786'

export HTTPS_PROXY='https://localhost:3786'

برای اطلاعات بیشتر درباره این متغیرها، https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables را ببینید

همچنین مراجعه کنید به

نحوه راه‌اندازی Edge Microgateway پشت دیوار آتش شرکت در «انجمن Apigee».

استفاده از نویسه‌های عام در پراکسی‌های آگاه از Microgateway

می‌توانید از یک یا چند نویسه عام «*» در مسیر پایه یک پراکسی edgemicro_* (آگاه از Microgateway) استفاده کنید. برای مثال، مسیر پایه /team/*/members به کارخواه‌ها اجازه می‌دهد https://[host]/team/blue/members و https://[host]/team/green/members را بدون نیاز به ایجاد پراکسی‌های میانای برنامه‌سازی کاربردی جدید برای پشتیبانی از تیم‌های جدید فراخوانی کنند. توجه داشته باشید که از /**/ پشتیبانی نمی‌شود.

مهم: Apigee از استفاده از نویسه عام «*» به‌عنوان اولین عنصر مسیر پایه پشتیبانی نمی‌کند. برای مثال، این مورد پشتیبانی نمی‌شود: جستجوی /*/.

درحال چرخش کلیدهای JWT

مدتی پس‌از تولید اولیه JWT، ممکن است لازم باشد جفت کلید عمومی/خصوصی ذخیره‌شده در KVM رمزگذاری‌شده Edge را تغییر دهید. به این فرایند تولید جفت کلید جدید، چرخش کلید می‌گویند.

نحوه استفاده Edge Microgateway از JWT

‫JSON Web Token (JWT)‎ یک استاندارد داده‌واحد است که در RFC7519 شرح داده شده است. ‫JWT روشی برای امضای مجموعه‌ای از ادعاها ارائه می‌دهد، که می‌تواند به‌طور قابل‌اعتمادی توسط گیرنده JWT تأیید شود.

‫Edge Microgateway از JWT به‌عنوان رمزیاب دارنده برای امنیت OAuth استفاده می‌کند. وقتی‌که یک کد OAuth برای Edge Microgateway تولید می‌کنید، یک JWT دریافت می‌کنید. سپس می‌توانید از JWT در سرصفحه «مجوز» تماس‌های API استفاده کنید. برای مثال:

curl -i http://localhost:8000/hello -H "Authorization: Bearer eyJhbGciOiJ..dXDefZEA"

درحال تولید JWT جدید

می‌توانید بااستفاده از فرمان edgemicro token یا میانای برنامه‌سازی کاربردی، JWT برای Edge Microgateway تولید کنید. برای مثال:

edgemicro token get -o docs -e test -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

این فرمان از Apigee Edge می‌خواهد تا JWT تولید کند که سپس می‌توان از آن برای درستی‌سنجی تماس‌های API استفاده کرد. پارامترهای -i و -s مقادیر شناسه مصرف‌کننده و کلید مخفی از برنامه توسعه‌دهنده در سازمان Apigee Edge شما هستند.

یا می‌توانید بااستفاده از Management API، یک JWT تولید کنید:

curl -i -X POST "http://org-env.apigee.net/edgemicro-auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your consumer key",
    "client_secret": "your consumer secret",
    "grant_type": "client_credentials"
  }'

مکان:

  • org نام سازمان Edge شما است (باید سرپرست سازمان باشید).
  • env محیطی در سازمان شما است (مثل «test» یا «prod»).
  • ‫client_id شناسه مصرف‌کننده در «برنامه توسعه‌دهنده» است که قبلاً ایجاد کرده‌اید.
  • client_secret «رمز مصرف‌کننده» در «برنامه توسعه‌دهنده» است که قبلاً ایجاد کرده‌اید.

تغییر کلید چیست؟

مدتی پس‌از تولید اولیه JWT، ممکن است لازم باشد جفت کلید عمومی/خصوصی ذخیره‌شده در KVM رمزگذاری‌شده Edge را تغییر دهید. به این فرایند تولید جفت کلید جدید، چرخش کلید می‌گویند. وقتی کلیدها را می‌چرخانید، جفت کلید خصوصی/عمومی جدیدی تولید می‌شود و در KVM «microgateway» در سازمان/محیط Apigee Edge شما ذخیره می‌شود. به‌علاوه، کلید عمومی قدیمی همراه با مقدار شناسه کلید اصلی آن حفظ می‌شود.

برای تولید JWT،‏ Edge از اطلاعات ذخیره‌شده در KVM رمزگذاری‌شده استفاده می‌کند. یک KVM به‌نام microgateway ایجاد شد و وقتی برای اولین‌بار Edge Microgateway را راه‌اندازی (پیکربندی) کردید، با کلیدهایی پر شد. از کلیدهای موجود در KVM برای امضا و رمزگذاری JWT استفاده می‌شود.

کلیدهای KVM شامل موارد زیر است:

  • private_key - جدیدترین (آخرین ایجادشده) کلید خصوصی RSA که برای امضای JWTها استفاده می‌شود.

  • public_key - جدیدترین (اخیراً ایجادشده) گواهی استفاده‌شده برای تأیید JWTهای امضاشده با private_key.

  • private_key_kid - جدیدترین (آخرین ایجادشده) شناسه کلید خصوصی. این شناسه کلید با مقدار private_key مرتبط است و برای پشتیبانی از چرخش کلید استفاده می‌شود.

  • public_key1_kid - جدیدترین (آخرین ایجادشده) شناسه کلید عمومی. این کلید با مقدار public_key1 مرتبط است و برای پشتیبانی از چرخش کلید استفاده می‌شود. این مقدار با شناسه کلید خصوصی یکسان است.

  • public_key1 - جدیدترین کلید عمومی (که اخیراً ایجاد شده است).

وقتی چرخش کلید را انجام می‌دهید، مقادیر کلید موجود در نقشه جایگزین می‌شوند و کلیدهای جدید برای حفظ کلیدهای عمومی قدیمی اضافه می‌شوند. برای مثال:

  • public_key2_kid - شناسه کلید عمومی قدیمی. این کلید با مقدار public_key2 مرتبط است و برای پشتیبانی از چرخش کلید استفاده می‌شود.

  • public_key2 - کلید عمومی قدیمی.

JWTهای ارائه‌شده برای درستی‌سنجی بااستفاده از کلید عمومی جدید درستی‌سنجی خواهند شد. اگر درستی‌سنجی ناموفق باشد، از کلید عمومی قدیمی استفاده خواهد شد تا زمانی که منقضی شود (پس‌از ۳۰ دقیقه). به‌این‌ترتیب، می‌توانید کلیدها را بدون ایجاد اختلال فوری در ترافیک میانای برنامه‌سازی کاربردی «بچرخانید».

نحوه انجام چرخش کلید

این بخش نحوه انجام چرخش کلید را توضیح می‌دهد.

اگر نمونه Edge Microgateway خود را قبل‌از نسخه ۲.۵.۲ پیکربندی کرده‌اید

اگر نمونه Edge Microgateway را قبل‌از نسخه ۲.۵.۲ پیکربندی کرده‌اید، باید دو فرمان زیر را برای ارتقای KVM و خط‌مشی اصالت‌سنجی اجرا کنید:

upgradekvm -o org -e env -u username

برای اطلاعات بیشتر درباره این فرمان، ارتقا دادن KVM را ببینید.

فرمان بعدی پراکسی edgemicro-oauth را که هنگام پیکربندی Edge Microgateway در سازمان Apigee شما مستقر شده بود ارتقا می‌دهد. این پراکسی سرویس‌های لازم برای تولید کردن رمزه را ارائه می‌دهد. 

upgradeauth -o org -e env -u username

برای اطلاعات بیشتر درباره این فرمان، به ارتقا دادن پراکسی edgemicro-auth مراجعه کنید.

درحال چرخش کلیدها

خط زیر را به فایل ~/.edgemicro/org-env-config.yaml اضافه کنید، که در آن باید همان سازمان و محیطی را که برای استفاده از ریزدروازه پیکربندی کرده‌اید مشخص کنید:

jwk_public_keys: 'https://org-env.apigee.net/edgemicro-auth/jwkPublicKeys'

فرمان چرخش کلید را برای چرخاندن کلیدها اجرا کنید. (برای اطلاعات بیشتر درباره این فرمان، کلیدهای چرخشی را ببینید.)

edgemicro rotatekey -o org -e env -u username -k kid_value

برای مثال:

edgemicro rotatekey -o jdoe -e test -u jdoe@google.com -k 2
current nodejs version is v6.9.1
current edgemicro version is 2.5.7
password:
Checking if private key exists in the KVM...
Checking for certificate...
Found Certificate
Generating New key/cert pair...
Extract new public key
Key Rotation successfully completed!

پارامتر -k «شناسه کلید» (kid) را مشخص می‌کند. از این شناسه برای مطابقت دادن کلیدی خاص استفاده می‌شود. Edge Microgateway از این مقدار برای انتخاب از میان مجموعه‌ای از کلیدها درطول چرخش کلید استفاده می‌کند. برای اطلاعات بیشتر، به بخش ۴.۵ از مشخصات کلید وب JSON مراجعه کنید.

پس‌از چرخش کلید، Edge چندین کلید را به Edge Microgateway برمی‌گرداند. توجه داشته باشید که در مثال زیر، هر کلید مقدار «kid» (شناسه کلید) یکتایی دارد. سپس ریزدروازه از این کلیدها برای اعتبارسنجی کردن توکن‌های مجوز استفاده می‌کند. اگر اعتبارسنجی کد ناموفق باشد، ریزدروازه بررسی می‌کند که آیا کلید قدیمی‌تری در مجموعه کلید وجود دارد یا نه و آن کلید را امتحان می‌کند. قالب کلیدهای برگردانده‌شده JSON Web Key (JWK) است. می‌توانید درباره این قالب در RFC 7517 بخوانید.

{
  "keys": [
    {
      "kty": "RSA",
      "n": "nSl7R_0wKLiWi6cO3n8aOJwYGBtinq723Jgg8i7KKWTSTYoszOjgGsJf_MX4JEW1YCScwpE5o4o8ccQN09iHVTlIhk8CNiMZNPipClmRVjaL_8IWvMQp1iN66qy4ldWXzXnHfivUZZogCkBNqCz7VSC5rw2Jf57pdViULVvVDGwTgf46sYveW_6h8CAGaD0KLd3vZffxIkoJubh0yMy0mQP3aDOeIGf_akeZeZ6GzF7ltbKGd954iNTiKmdm8IKhz6Y3gLpC9iwQ-kex_j0CnO_daHl1coYxUSCIdv4ziWIeM3dmjQ5_2dEvUDIGG6_Az9hTpNgPE5J1tvrOHAmunQ",
      "e": "AQAB",
      "kid": "2"
    },
    {
      "kty": "RSA",
      "n": "8BKwzx34BMUcHwTuQtmp8LFRCMxbkKg_zsWD6eOMIUTAsORexTGJsTy7z-4aH0wJ3fT-3luAAUPLBQwGcuHo0P1JnbtPrpuYjaJKSZOeIMOnlryJCspmv-1xG4qAqQ9XaZ9C97oecuj7MMoNwuaZno5MvsY-oi5B_gqED3vIHUjaWCErd4reONyFSWn047dvpE6mwRhZbcOTkAHT8ZyKkHISzopkFg8CD-Mij12unxA3ldcTV7yaviXgxd3eFSD1_Z4L7ZRsDUukCJkJ-8qY2-GWjewzoxl-mAW9D1tLK6qAdc89yFem3JHRW6L1le3YK37-bs6b2a_AqJKsKm5bWw",
      "e": "AQAB",
      "kid": "1"
    }
  ]
}

درحال فیلتر کردن پراکسی‌های بارگیری‌شده

به‌طور پیش‌فرض، Edge Microgateway همه پراکسی‌های موجود در سازمان Edge شما را که با پیشوند نام‌گذاری «edgemicro_» شروع می‌شوند بارگیری می‌کند. می‌توانید این پیش‌فرض را تغییر دهید تا پراکسی‌هایی را بارگیری کنید که نامشان با الگویی مطابقت دارد.

  1. فایل پیکربندی Edge Micro را باز کنید: ~/.edgemicro/org-env-config.yaml
  2. عنصر proxyPattern را زیر edge_config اضافه کنید. برای مثال، الگوی زیر پراکسی‌هایی مثل edgemicro_foo،‏ edgemicro_fast، و edgemicro_first را بارگیری می‌کند. 
    edge_config:
…
proxyPattern: edgemicro_f*

مشخص کردن محصولات بدون پراکسی‌های میانای برنامه‌سازی کاربردی

در Apigee Edge، می‌توانید محصول میانای برنامه‌سازی کاربردی‌ای ایجاد کنید که حاوی هیچ پراکسی میانای برنامه‌سازی کاربردی‌ای نباشد. این پیکربندی محصول به کلید میانای برنامه‌سازی کاربردی مرتبط با آن محصول اجازه می‌دهد با هر پراکسی مستقرشده در سازمانتان کار کند. از نسخه ۲.۵.۴، Edge Microgateway از این پیکربندی محصول پشتیبانی می‌کند.

اشکال‌زدایی و عیب‌یابی

درحال اتصال به اشکال‌زدا

می‌توانید Edge Microgateway را با اشکال‌زدایی مثل node-inspector اجرا کنید. این برای عیب‌یابی و اشکال‌زدایی افزونه‌های سفارشی مفید است.

  1. Edge Microgateway را در حالت اشکال‌زدایی بازراه‌اندازی کنید. برای انجام این کار، DEBUG=* را به ابتدای فرمان start اضافه کنید. برای مثال: 
    DEBUG=* edgemicro start -o  myorg -e test -k
      db4e9e8a95aa7fabfdeacbb1169d0a8cbe42bec19c6b98129e02 -s
      6e56af7c1b26dfe93dae78a735c8afc9796b077d105ae5618ce7ed
  2. اشکال‌زدا را راه‌اندازی کنید و آن را روی شماره درگاه فرایند اشکال‌زدایی تنظیم کنید.
  3. اکنون می‌توانید کد Edge Microgateway را گام‌به‌گام اجرا کنید، نقاط توقف تنظیم کنید، عبارت‌ها را تماشا کنید، و غیره.

می‌توانید پرچم‌های استاندارد Node.js مربوط به حالت اشکال‌زدایی را مشخص کنید. برای مثال، --nolazy به اشکال‌زدایی کد ناهمگام کمک می‌کند.

درحال بررسی فایل‌های گزارش

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

استفاده از امنیت کلید میانای برنامه‌سازی کاربردی

کلیدهای میانای برنامه‌سازی کاربردی سازوکار ساده‌ای برای اصالت‌سنجی کردن کارخواه‌هایی که به Edge Microgateway درخواست ارسال می‌کنند ارائه می‌دهد. می‌توانید با کپی کردن مقدار «کلید مصرف‌کننده» (که «شناسه کارخواه» نیز نامیده می‌شود) از محصول Apigee Edge که شامل پراکسی اصالت‌سنجی Edge Microgateway است، کلید میانای برنامه‌سازی کاربردی دریافت کنید.

ذخیره کلیدها در حافظه پنهان

کلیدهای میانای API با رمزیاب‌های دارنده مبادله می‌شوند که در حافظه نهان ذخیره می‌شوند. می‌توانید با تنظیم سرایند Cache-Control: no-cache در درخواست‌های ورودی به Edge Microgateway، ذخیره‌سازی در حافظه نهان را غیرفعال کنید.

استفاده از کلید میانای برنامه‌سازی کاربردی

می‌توانید کلید میانای برنامه‌سازی کاربردی را در درخواست میانای برنامه‌سازی کاربردی به‌عنوان پارامتر پُرسمان یا در سرصفحه ارسال کنید. به‌طور پیش‌فرض، نام پارامتر پُرسمان و سرایند هر دو x-api-key است.

نمونه پارامتر پُرسمان:

curl http://localhost:8000/foobar?x-api-key=JG616Gjz7xs4t0dvpvVsGdI49G34xGsz

نمونه سرایند:

curl http://localhost:8000/foobar -H "x-api-key:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

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

به‌طور پیش‌فرض، x-api-key نامی است که هم برای سرصفحه کلید API و هم برای پارامتر پُرسمان استفاده می‌شود. می‌توانید این پیش‌فرض را در فایل پیکربندی تغییر دهید، همان‌طور که در ایجاد تغییرات پیکربندی توضیح داده شده است. برای مثال، برای تغییر دادن نام به apiKey:

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  api-key-header: apiKey

در این مثال، هم پارامتر پُرسمان و هم نام سرصفحه به apiKey تغییر کرده است. نام x-api-key دیگر در هیچ‌کدام از این موارد کار نخواهد کرد. همچنین ببینید ایجاد تغییرات پیکربندی.

برای مثال:

curl http://localhost:8000/foobar -H "apiKey:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

برای اطلاعات بیشتر درباره استفاده از کلیدهای میانای برنامه‌سازی کاربردی با درخواست‌های پراکسی، به Secure Edge Microgateway مراجعه کنید.

استفاده از امنیت کد OAuth2

این بخش توضیح می‌دهد که چگونه می‌توانید کدهای دسترسی OAuth2 و کدهای بازآوری را دریافت کنید. از کد دسترسی برای برقراری تماس‌های امن میانای برنامه‌سازی کاربردی ازطریق ریزدروازه استفاده می‌شود. از ژتون‌های بازآوری برای دریافت ژتون‌های دسترسی جدید استفاده می‌شود.

نحوه دریافت کد دسترسی

این بخش توضیح می‌دهد که چگونه از پراکسی edgemicro-auth برای دریافت کد دسترسی استفاده کنید.

همچنین می‌توانید بااستفاده از فرمان edgemicro token CLI کد دسترسی دریافت کنید. برای جزئیات مربوط به میانای خط فرمان، به مدیریت کردن توکن‌ها مراجعه کنید.

API 1

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

curl -i -X POST "http://<org>-<test>.apigee.net/edgemicro-auth/token" \
-d '{"grant_type": "client_credentials", "client_id": "your_client_id", \
"client_secret": "your_client_secret"}' -H "Content-Type: application/json"

API 2

(در نسخه ۲.۵.۳۱ اضافه شده است) اطلاعات کارخواه را به‌عنوان سرایند «اصالت‌سنجی پایه» و grant_type را به‌عنوان پارامتر فرم ارسال کنید. این فرم فرمان در RFC 6749: چارچوب مجوز OAuth 2.0 نیز مورد بحث قرار گرفته است. 
http://<org>-<test>.apigee.net/edgemicro-auth/token -v -u your_client_id:your_client_secret \
-d 'grant_type=client_credentials' -H "Content-Type: application/x-www-form-urlencoded"

نمونه خروجی

میانای برنامه‌سازی کاربردی پاسخ JSON برمی‌گرداند. توجه داشته باشید که هیچ تفاوتی بین ویژگی‌های token و access_token وجود ندارد. می‌توانید از هرکدام استفاده کنید. 
{
"token": "eyJraWQiOiIxIiwidHlwIjoi",
"access_token": "eyJraWQiOiIxIiwid",
"token_type": "bearer",
"expires_in": "108000"
}

نحوه دریافت ژتون بازآوری

برای دریافت ژتون بازآوری، یک فراخوانی میانای برنامه‌سازی کاربردی به نقطه پایانی /token از پراکسی edgemicro-auth انجام دهید. باید این فراخوانی میانای برنامه‌سازی کاربردی را با نوع اعطای مجوز password انجام دهید. مراحل زیر این فرایند را توضیح می‌دهد.

  1. بااستفاده از میانای برنامه‌سازی کاربردی /token، یک کد دسترسی و کد بازآوری دریافت کنید. توجه داشته باشید که نوع اعطای مجوز password است: 
    curl -X POST \
  https://your_organization-your_environment.apigee.net/edgemicro-auth/token \
  -H 'Content-Type: application/json' \
  -d '{
   "client_id":"mpK6l1Bx9oE5zLdifoDbF931TDnDtLq",
   "client_secret":"bUdDcFgv3nXffnU",
   "grant_type":"password",
   "username":"mpK6lBx9RoE5LiffoDbpF931TDnDtLq",
   "password":"bUdD2FvnMsXffnU"
}'

    میانای برنامه‌سازی کاربردی یک کد دسترسی و یک ژتون بازآوری برمی‌گرداند. پاسخ شبیه به این است: 

    {
    "token": "your-access-token",
    "access_token": "your-access-token",
    "token_type": "bearer",
    "expires_in": "108000",
    "refresh_token": "your-refresh-token",
    "refresh_token_expires_in": "431999",
    "refresh_token_issued_at": "1562087304302",
    "refresh_token_status": "approved"
}
  2. اکنون می‌توانید با فراخوانی نقطه پایانی /refresh در همان API، از کد بازآوری برای دریافت کد دسترسی جدید استفاده کنید. برای مثال: 
    curl -X POST \
  https://willwitman-test.apigee.net/edgemicro-auth/refresh \
  -H 'Content-Type: application/json' \
  -d '{
   "client_id":"mpK6l1Bx9RoE5zLifoDbpF931TDnDtLq",
   "client_secret":"bUdDc2Fv3nMXffnU",
   "grant_type":"refresh_token",
   "refresh_token":"your-refresh-token"
}'

    میانای برنامه‌سازی کاربردی کد دسترسی جدیدی برمی‌گرداند. پاسخ شبیه به این است: 

    {
    "token": "your-new-access-token"
    }

پایش همیشگی

Forever ابزاری در Node.js است که برنامه Node.js را درصورت توقف یا بروز خطا در فرایند به‌طور خودکار بازراه‌اندازی می‌کند. Edge Microgateway دارای فایل forever.json است که می‌توانید آن را پیکربندی کنید تا کنترل کنید Edge Microgateway چند بار و با چه فاصله‌های زمانی باید بازراه‌اندازی شود. این فایل یک سرویس Forever به‌نام forever-monitor را پیکربندی می‌کند که Forever را به‌صورت برنامه‌نویسی‌شده مدیریت می‌کند.

می‌توانید فایل forever.json را در دایرکتوری نصب ریشه Edge Microgateway پیدا کنید. Where is Edge Microgateway installed (Edge Microgateway کجا نصب شده است) را ببینید. برای جزئیات مربوط به گزینه‌های پیکربندی، به مستندات forever-monitor مراجعه کنید.

فرمان edgemicro forever شامل پرچم‌هایی است که به شما امکان می‌دهد مکان فایل forever.json (پرچم -f) را مشخص کنید و فرایند نظارت Forever (پرچم -a) را شروع/متوقف کنید. برای مثال:

edgemicro forever -f ~/mydir/forever.json -a start

برای اطلاعات بیشتر، به پایش Forever در مرجع میانای خط فرمان مراجعه کنید.

مشخص کردن نقطه پایانی فایل پیکربندی

اگر چند نمونه Edge Microgateway اجرا می‌کنید، شاید بخواهید پیکربندی‌های آن‌ها را از یک مکان مدیریت کنید. می‌توانید این کار را با مشخص کردن نقطه پایانی HTTP که Edge Micro می‌تواند فایل پیکربندی خود را از آن بارگیری کند انجام دهید. وقتی Edge Micro را بااستفاده از پرچم -u راه‌اندازی می‌کنید، می‌توانید این نقطه پایانی را مشخص کنید.

برای مثال:

edgemicro start -o jdoe -e test -u http://mylocalserver/mgconfig -k public_key -s secret_key

که در آن نقطه پایان mgconfig محتوای فایل پیکربندی شما را برمی‌گرداند. این فایلی است که به‌طور پیش‌فرض در ~/.edgemicro قرار دارد و از این قاعده نام‌گذاری پیروی می‌کند: org-env-config.yaml.

درحال غیرفعال کردن میان‌گیری داده‌های اتصال TCP

می‌توانید از مشخصه پیکربندی nodelay برای غیرفعال کردن میان‌گیر داده‌ها برای اتصال‌های TCP استفاده‌شده توسط Edge Microgateway استفاده کنید.

به‌طور پیش‌فرض، اتصال‌های TCP از الگوریتم Nagle برای میان‌گیر کردن داده‌ها قبل‌از ارسال آن‌ها استفاده می‌کنند. تنظیم nodelay روی true، این رفتار را غیرفعال می‌کند (هر بار که socket.write() فراخوانی شود، داده‌ها بلافاصله ارسال می‌شوند). برای جزئیات بیشتر، اسناد Node.js را نیز ببینید.

برای فعال کردن nodelay، فایل پیکربندی Edge Micro را به‌صورت زیر ویرایش کنید:

edgemicro:
  nodelay: true
  port: 8000
  max_connections: 1000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

درحال اجرای Edge Microgateway در حالت مستقل

می‌توانید Edge Microgateway را کاملاً جدا از هرگونه وابستگی به Apigee Edge اجرا کنید. این سناریو که حالت مستقل نامیده می‌شود، به شما امکان می‌دهد Edge Microgateway را بدون اتصال اینترنت اجرا و آزمایش کنید.

در حالت مستقل، ویژگی‌های زیر کار نمی‌کنند، زیرا به اتصال به Apigee Edge نیاز دارند:

  • OAuth و کلید میانای برنامه‌سازی کاربردی
  • سهمیه
  • Analytics

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

درحال پیکربندی و راه‌اندازی درگاه

برای اجرای Edge Microgateway در حالت مستقل:

  1. مطمئن شوید که Edge Microgateway نسخه ۲.۵.۲۵ یا جدیدتر را نصب کرده‌اید. اگر نه، باید فرمان زیر را برای ارتقا به جدیدترین نسخه اجرا کنید: 
    npm install -g edgemicro

    اگر به راهنمایی نیاز دارید، نصب Edge Microgateway را ببینید.

  2. فایل پیکربندی‌ای با نام زیر ایجاد کنید: $HOME/.edgemicro/org_name-env_name-config.yaml

    برای مثال:

    vi $HOME/.edgemicro/foo-bar-config.yaml
  3. کد زیر را در فایل جای‌گذاری کنید: 
    edgemicro:
  port: 8000
  max_connections: 1000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - extauth
      - spikearrest
headers:
  x-forwarded-for: true
  x-forwarded-host: true
  x-request-id: true
  x-response-time: true
  via: true
extauth:
  publickey_url: https://www.googleapis.com/oauth2/v1/certs
spikearrest:
  timeUnit: second
  allow: 10
  buffersize: 0
  4. متغیر محیطی زیر را با مقدار «۱» صادر کنید: 
    export EDGEMICRO_LOCAL=1
  5. فرمان start زیر را اجرا کنید و مقادیر را برای نمونه‌سازی پراکسی محلی ارائه دهید: 
    edgemicro start -o org_name -e environment_name -a local_proxy_name \
  -v local_proxy_version -t target_url -b base_path

    مکان:

    • your_org نام «سازمان» است که در نام فایل پیکربندی استفاده کرده‌اید.
    • your_environment نام «env» است که در نام فایل پیکربندی استفاده کرده‌اید.
    • local_proxy_name نام پراکسی محلی است که ایجاد خواهد شد. می‌توانید از هر نامی که می‌خواهید استفاده کنید.
    • local_proxy_version شماره نسخه پراکسی است.
    • ‫target_url نشانی وب هدف پراکسی است. (هدف سرویسی است که پراکسی آن را فراخوانی می‌کند.)
    • base_path مسیر پایه پراکسی است. این مقدار باید با خط مورب رو به جلو شروع شود. برای مسیر پایه ریشه، فقط یک خط مورب رو به جلو مشخص کنید؛ برای مثال، «/».

    برای مثال:

    edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
  6. پیکربندی را آزمایش کنید. 
    curl http://localhost:8000/echo  { "error" : "missing_authorization" }

    چون افزونه extauth در فایل foo-bar-config.yaml است، خطای «missing_authorization» دریافت می‌کنید. این افزونه JWT را که باید در سرصفحه «مجوز» فراخوانی میانای برنامه‌سازی کاربردی وجود داشته باشد، اعتبارسنجی می‌کند. در بخش بعدی، یک JWT دریافت خواهید کرد که به فراخوانی‌های API اجازه می‌دهد بدون خطا انجام شوند.

مثال: دریافت کردن نمودافزار مجوز

مثال زیر نشان می‌دهد که چگونه می‌توان یک JWT را از نقطه پایانی JWT Edge Microgateway در Apigee Edge (edgemicro-auth/jwkPublicKeys) دریافت کرد. این نقطه پایانی زمانی مستقر می‌شود که شما یک راه‌اندازی و پیکربندی استاندارد از Edge Microgateway انجام دهید. برای دریافت JWT از نقطه پایانی Apigee، ابتدا باید راه‌اندازی استاندارد Edge Microgateway را انجام دهید و به اینترنت متصل باشید. نقطه پایانی Apigee در اینجا فقط برای اهداف نمونه استفاده می‌شود و الزامی نیست. درصورت تمایل می‌توانید از نقطه پایانی توکن JWT دیگری استفاده کنید. اگر این کار را انجام دهید، باید JWT را بااستفاده از میانای برنامه‌سازی کاربردی ارائه‌شده برای آن نقطه پایانی دریافت کنید.

مراحل زیر نحوه دریافت کردن توکن بااستفاده از نقطه پایانی edgemicro-auth/jwkPublicKeys را توضیح می‌دهد:.

  1. برای استقرار پراکسی edgemicro-auth در سازمان/محیط خود در Apigee Edge، باید راه‌اندازی و پیکربندی استاندارد Edge Microgateway را انجام دهید. اگر قبلاً این مرحله را انجام داده‌اید، نیازی به تکرار آن نیست.
  2. اگر Edge Microgateway را در Apigee Cloud مستقر کرده‌اید، باید به اینترنت متصل باشید تا بتوانید JWT را از این نقطه پایانی دریافت کنید.
  3. توقف Edge Microgateway: 
    edgemicro stop
  4. در فایل پیکربندی که قبلاً ایجاد کرده‌اید ($HOME/.edgemicro/org-env-config.yaml)، مشخصه extauth:publickey_url را به نقطه پایانی edgemicro-auth/jwkPublicKeys در سازمان/محیط Apigee Edge خودتان هدایت کنید. برای مثال: 
    extauth:
  publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'
  5. Edge Microgateway را مانند قبل بااستفاده از نام‌های org/env که در نام فایل پیکربندی استفاده کردید بازراه‌اندازی کنید. برای مثال: 
    edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
  6. یک کد JWT از نقطه پایان مجوز دریافت کنید. چون از نقطه پایانی edgemicro-auth/jwkPublicKeys استفاده می‌کنید، می‌توانید از این فرمان CLI استفاده کنید:

می‌توانید بااستفاده از فرمان edgemicro token یا میانای برنامه‌سازی کاربردی، JWT برای Edge Microgateway تولید کنید. برای مثال:

edgemicro token get -o your_org -e your_env \
  -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

مکان:

  • your_org نام سازمان Apigee شما است که قبلاً Edge Microgateway را برای آن پیکربندی کرده‌اید.
  • ‫your_env محیطی در سازمان است.
  • گزینه i «کلید مصرف‌کننده» را از برنامه توسعه‌دهنده‌ای که محصولی دارد که شامل پراکسی edgemicro-auth است مشخص می‌کند.
  • گزینه s «رمز مصرف‌کننده» را از برنامه توسعه‌دهنده‌ای که محصولی شامل پراکسی edgemicro-auth دارد مشخص می‌کند.

این فرمان از Apigee Edge می‌خواهد تا JWT تولید کند که سپس می‌توان از آن برای درستی‌سنجی تماس‌های API استفاده کرد.

تولید کردن توکن را نیز ببینید.

آزمایش پیکربندی مستقل

برای آزمایش پیکربندی، میانای برنامه‌سازی کاربردی را با کد اضافه‌شده در سرصفحه «مجوز» به‌صورت زیر فراخوانی کنید:

curl http://localhost:8000/echo -H "Authorization: Bearer your_token

مثال:

curl http://localhost:8000/echo -H "Authorization: Bearer eyJraWQiOiIxIiwidHlwIjo...iryF3kwcDWNv7OQ"

خروجی نمونه:

{
   "headers":{
      "user-agent":"curl/7.54.0",
      "accept":"*/*",
      "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
      "client_received_start_timestamp":"1535134472699",
      "x-authorization-claims":"eyJhdDbiO...M1OTE5MTA1NDkifQ==",
      "target_sent_start_timestamp":"1535134472702",
      "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
      "x-forwarded-proto":"http",
      "x-forwarded-host":"localhost:8000",
      "host":"mocktarget.apigee.net",
      "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
      "via":"1.1 localhost, 1.1 google",
      "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
      "connection":"Keep-Alive"
   },
   "method":"GET",
   "url":"/",
   "body":""
}

استفاده از حالت پراکسی محلی

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

مورد استفاده و نمونه

حالت پراکسی محلی زمانی مفید است که فقط لازم باشد یک پراکسی را با یک نمونه Edge Microgateway مرتبط کنید. برای مثال، می‌توانید Edge Microgateway را به‌عنوان پراکسی جانبی به Kubernetes تزریق کنید، که در آن یک microgateway و یک سرویس هرکدام در یک pod اجرا می‌شوند، و microgateway ترافیک ورودی و خروجی سرویس همراه خود را مدیریت می‌کند. شکل زیر این معماری را نشان می‌دهد که در آن Edge Microgateway به‌عنوان پراکسی جانبی در خوشه Kubernetes عمل می‌کند. هر نمونه ریزدروازه فقط با یک نقطه پایانی در سرویس همراه خود صحبت می‌کند:

Edgemicro به‌عنوان Sidecar

یکی از مزایای این سبک معماری این است که Edge Microgateway مدیریت میانای برنامه‌سازی کاربردی را برای سرویس‌های تکی مستقرشده در محیط محفظه، مانند خوشه Kubernetes، ارائه می‌دهد.

درحال پیکربندی حالت پراکسی محلی

برای پیکربندی Edge Microgateway برای اجرا در حالت پراکسی محلی، این مراحل را دنبال کنید:

  1. مطمئن شوید که Edge Microgateway نسخه ۲.۵.۲۵ یا جدیدتر را نصب کرده‌اید. اگر نه، باید فرمان زیر را برای ارتقا به جدیدترین نسخه اجرا کنید: 
    npm install -g edgemicro

    اگر به راهنمایی نیاز دارید، نصب Edge Microgateway را ببینید.

  2. edgemicro init را اجرا کنید تا محیط پیکربندی محلی‌تان را دقیقاً همان‌طور که در راه‌اندازی Edge Microgateway معمولی انجام می‌دهید، راه‌اندازی کنید. همچنین پیکربندی Edge Microgateway را ببینید.
  3. edgemicro configure را اجرا کنید، همان‌طور که در روش راه‌اندازی Edge Microgateway معمولی انجام می‌دهید. برای مثال: 
    edgemicro configure -o your_org -e your_env -u your_apigee_username

    این فرمان خط‌مشی edgemicro-auth را در Edge مستقر می‌کند و کلید و رمزی را برمی‌گرداند که برای شروع microgateway به آن نیاز دارید. اگر به راهنمایی نیاز دارید، پیکربندی Edge Microgateway را ببینید.

  4. در Apigee Edge، محصول API را با الزامات پیکربندی اجباری زیر ایجاد کنید (می‌توانید همه پیکربندی‌های دیگر را به‌دلخواه خودتان مدیریت کنید):

  5. در Apigee Edge، توسعه‌دهنده‌ای ایجاد کنید یا اگر مایلید می‌توانید از توسعه‌دهنده موجود استفاده کنید. برای راهنمایی، افزودن توسعه‌دهندگان بااستفاده از واسط کاربر مدیریت Edge را ببینید.

  6. در Apigee Edge، برنامه توسعه‌دهنده ایجاد کنید. باید محصول API را که به‌تازگی ایجاد کرده‌اید به برنامه اضافه کنید. برای راهنمایی، ثبت برنامه در Edge رابط کاربری مدیریت را ببینید.
  7. در دستگاهی که Edge Microgateway نصب شده است، متغیر محیطی زیر را با مقدار «۱» صادر کنید. 
    export EDGEMICRO_LOCAL_PROXY=1
  8. فرمان start زیر را اجرا کنید: 
    edgemicro start -o your_org -e your_environment -k your_key -s your_secret \
    -a local_proxy_name -v local_proxy_version -t target_url -b base_path

    مکان:

    • your_org سازمان Apigee شما است.
    • your_environment محیطی در سازمان شما است.
    • your_key کلیدی است که هنگام اجرای edgemicro configure برگردانده شد.
    • your_secret کلیدی است که هنگام اجرای edgemicro configure برگردانده شد.
    • local_proxy_name نام پراکسی محلی است که ایجاد خواهد شد.
    • local_proxy_version شماره نسخه پراکسی است.
    • target_url نشانی وب هدف پیشکار است (سرویسی که پیشکار با آن تماس خواهد گرفت).
    • base_path مسیر پایه پراکسی است. این مقدار باید با خط مورب رو به جلو شروع شود. برای مسیر پایه ریشه، فقط یک خط مورب رو به جلو مشخص کنید؛ برای مثال، «/».

    برای مثال:

    edgemicro start -o your_org -e test -k 7eb6aae644cbc09035a...d2eae46a6c095f \
  -s e16e7b1f5d5e24df...ec29d409a2df853163a -a proxy1 -v 1 \
  -t http://mocktarget.apigee.net -b /echo

درحال آزمایش پیکربندی

می‌توانید پیکربندی پراکسی محلی را با فراخوانی نقطه پایانی پراکسی آزمایش کنید. برای مثال، اگر مسیر پایه /echo را مشخص کرده باشید، می‌توانید پراکسی را به‌صورت زیر فراخوانی کنید:

curl  http://localhost:8000/echo
{
  "error" : "missing_authorization",
  "error_description" : "Missing Authorization header"
}

این فراخوانی اولیه میانای برنامه‌سازی کاربردی (API) با خطا مواجه شد زیرا کلید میانای برنامه‌سازی کاربردی معتبری ارائه نکردید. می‌توانید کلید را در برنامه «توسعه‌دهنده» که قبلاً ایجاد کرده‌اید پیدا کنید. برنامه را در Edge UI باز کنید، «کلید مصرف‌کننده» را کپی کنید، و از آن کلید به‌صورت زیر استفاده کنید:

curl  http://localhost:8000/echo -H 'x-api-key:your_api_key'

برای مثال:

curl  http://localhost:8000/echo -H "x-api-key:DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP"

خروجی نمونه:

{
  "headers":{
    "user-agent":"curl/7.54.0",
    "accept":"*/*",
    "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
    "client_received_start_timestamp":"1535134472699",
    "x-authorization-claims":"eyJhdWQiOi...TQ0YmUtOWNlOS05YzM1OTE5MTA1NDkifQ==",
    "target_sent_start_timestamp":"1535134472702",
    "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
    "x-forwarded-proto":"http",
    "x-forwarded-host":"localhost:8000",
    "host":"mocktarget.apigee.net",
    "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
    "via":"1.1 localhost, 1.1 google",
    "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
    "connection":"Keep-Alive"
  },
  "method":"GET",
  "url":"/",
  "body":""
}