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

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

میکروگیت‌وی اج نسخه ۳.۱.x

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

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

این بخش نحوه ارتقاء نسخه موجود Edge Microgateway را توضیح می‌دهد. اگر بدون اتصال به اینترنت کار می‌کنید، به «آیا می‌توانم Edge Microgateway را بدون اتصال به اینترنت نصب کنم؟» مراجعه کنید.

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

1. برای ارتقاء به آخرین نسخه Edge Microgateway، دستور npm زیر را اجرا کنید:

   npm upgrade edgemicro -g

   برای ارتقاء به یک نسخه خاص از Edge Microgateway، باید شماره نسخه را در دستور ارتقاء مشخص کنید. اگر شماره نسخه را مشخص نکنید، آخرین نسخه نصب خواهد شد. به عنوان مثال، برای ارتقاء به نسخه 3.1.0، از دستور زیر استفاده کنید:

   npm upgrade edgemicro@3.1.0 -g

2. شماره نسخه را بررسی کنید. برای مثال، اگر نسخه ۳.۱.۰ را نصب کرده‌اید:

   edgemicro --version
   current nodejs version is v12.5.0
   current edgemicro version is 3.1.0
       

3. در نهایت، به آخرین نسخه از پروکسی edgemicro-auth ارتقا دهید:

   edgemicro upgradeauth -o $ORG -e $ENV -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 -e $ENV -k $KEY -s $SECRET

   کجا:

   • $ORG نام سازمان Edge شما است (شما باید مدیر سازمان باشید).
   • $ENV ‎ یک محیط در سازمان شما است (مانند "test" یا "prod").
   • $KEY ‎ کلیدی است که قبلاً توسط دستور configure برگردانده شده است.
   • $SECRET ‎ کلیدی است که قبلاً توسط دستور configure برگردانده شده است.

   برای مثال

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

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

1. میکروگیت‌وی اج را مجدداً راه‌اندازی کنید:

   edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET

   کجا:

   • $ORG نام سازمان Edge شما است (شما باید مدیر سازمان باشید).
   • $ENV محیطی در سازمان شماست (مانند "test" یا "prod").
   • $KEY ‎ کلیدی است که قبلاً توسط دستور configure برگردانده شده است.
   • $SECRET ‎ کلیدی است که قبلاً توسط دستور configure برگردانده شده است.

   برای مثال:

   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

برای آشنایی با پیکربندی TLS در Apigee Edge Microgateway، ویدیوهای زیر را تماشا کنید:

شما می‌توانید سرور Microgateway را طوری پیکربندی کنید که از SSL استفاده کند. برای مثال، با پیکربندی SSL، می‌توانید APIها را از طریق 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

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

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

می‌توانید Edge Microgateway را طوری پیکربندی کنید که هنگام اتصال به نقاط انتهایی هدف، یک کلاینت TLS یا 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

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

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

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

استفاده از یک سرویس احراز هویت سفارشی

به طور پیش‌فرض، Edge Microgateway از یک پروکسی مستقر در Apigee Edge برای احراز هویت OAuth2 استفاده می‌کند. این پروکسی هنگام اجرای اولیه edgemicro configure مستقر می‌شود. به طور پیش‌فرض، URL این پروکسی در فایل پیکربندی 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

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

نحوه تنظیم سطح ثبت وقایع

شما می‌توانید این سطوح ثبت وقایع را تنظیم کنید: info ، warn و error . سطح info توصیه می‌شود. این سطح، تمام درخواست‌ها و پاسخ‌های 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 توصیه می‌کند که شیوه‌های زیر را اتخاذ کنید:

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

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

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

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

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

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) را حذف می‌کند. اگر می‌خواهید این اشیاء را در فایل‌های گزارش خروجی دهید، هنگام شروع Edge Microgateway، DEBUG=* را تنظیم کنید. به عنوان مثال:

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

• ۱۴۳۶۴۰۳۸۸۸۶۵۱ - مهر تاریخ یونیکس
• اطلاعات - بستگی به متن دارد. بسته به سطح لاگ، می‌تواند اطلاعات، هشدار یا خطا باشد. می‌تواند برای یک رکورد آمار، آمار، هشدار یا خطا باشد.
• req - رویداد را شناسایی می‌کند. در این مورد، از کلاینت درخواست می‌شود.
• m - فعل HTTP استفاده شده در درخواست.
• u - بخشی از URL که پس از مسیر پایه قرار می‌گیرد.
• h - شماره میزبان و پورتی که Edge Microgateway در آن مشغول گوش دادن است.
• r - میزبان و پورت راه دور که درخواست کلاینت از آنجا ارسال شده است.
• i - شناسه درخواست. هر چهار ورودی رویداد این شناسه را به اشتراک می‌گذارند. به هر درخواست یک شناسه درخواست منحصر به فرد اختصاص داده می‌شود. مرتبط کردن رکوردهای لاگ بر اساس شناسه درخواست می‌تواند بینش ارزشمندی در مورد تأخیر هدف ارائه دهد.
• d - مدت زمان بر حسب میلی‌ثانیه از زمان دریافت درخواست توسط Edge Microgateway. در مثال بالا، پاسخ هدف برای درخواست 0 پس از 7 میلی‌ثانیه (خط 3) دریافت شد و پاسخ پس از 4 میلی‌ثانیه اضافی (خط 4) به کلاینت ارسال شد. به عبارت دیگر، کل تأخیر درخواست 11 میلی‌ثانیه بود که از این تعداد 7 میلی‌ثانیه توسط هدف و 4 میلی‌ثانیه توسط خود Edge Microgateway گرفته شده است.

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

1436403888665 info treq m=GET, u=/, h=127.0.0.1:8080, i=0

• ۱۴۳۶۴۰۳۸۸۸۶۵۱ - مهر تاریخ یونیکس
• اطلاعات - بستگی به متن دارد. بسته به سطح لاگ، می‌تواند اطلاعات، هشدار یا خطا باشد. می‌تواند برای یک رکورد آمار، آمار، هشدار یا خطا باشد.
• treq - رویداد را شناسایی می‌کند. در این مورد، درخواست هدف.
• m - فعل HTTP استفاده شده در درخواست هدف.
• u - بخشی از URL که پس از مسیر پایه قرار می‌گیرد.
• h - شماره میزبان و پورت هدف backend.
• i - شناسه‌ی ورودی لاگ. هر چهار ورودی رویداد این شناسه را به اشتراک می‌گذارند.

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

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

۱۴۳۶۴۰۳۸۸۸۶۵۱ - مهر تاریخ یونیکس

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

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

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

۱۴۳۶۴۰۳۸۸۸۶۵۱ - مهر تاریخ یونیکس

• اطلاعات - بستگی به متن دارد. بسته به سطح لاگ، می‌تواند اطلاعات، هشدار یا خطا باشد. می‌تواند برای یک رکورد آمار، آمار، هشدار یا خطا باشد.
• res - رویداد را شناسایی می‌کند. در این مورد، پاسخ به کلاینت.
• s - وضعیت پاسخ HTTP.
• d - مدت زمان بر حسب میلی‌ثانیه. این کل زمان صرف شده برای فراخوانی API است، شامل زمان صرف شده توسط API هدف و زمان صرف شده توسط خود Edge Microgateway.
• i - شناسه‌ی ورودی لاگ. هر چهار ورودی رویداد این شناسه را به اشتراک می‌گذارند.

برنامه زمانبندی فایل لاگ

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

پیام‌های خطا

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

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

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

ویژگی‌های پیکربندی شرح داده شده در این بخش در فایل پیکربندی Edge Microgateway قرار دارند. همچنین به بخش «ایجاد تغییرات پیکربندی» مراجعه کنید.

ویژگی‌های edge_config

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

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

  edge_config:
    quotaUri: https://your_org-your_env.apigee.net/edgemicro-auth
  

ویژگی‌های edgemicro

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

• پورت : (پیش‌فرض: ۸۰۰۰) شماره پورتی که پردازش Edge Microgateway به آن گوش می‌دهد.
• max_connections : (پیش‌فرض: -1) حداکثر تعداد اتصالات ورودی همزمان که Edge Microgateway می‌تواند دریافت کند را مشخص می‌کند. اگر از این تعداد تجاوز شود، وضعیت زیر برگردانده می‌شود:
  
  res.statusCode = 429; // Too many requests
  
• max_connections_hard : (پیش‌فرض: -1) حداکثر تعداد درخواست‌های همزمان که Edge Microgateway می‌تواند قبل از قطع اتصال دریافت کند. این تنظیم برای خنثی کردن حملات انکار سرویس در نظر گرفته شده است. معمولاً آن را روی عددی بزرگتر از max_connections تنظیم کنید.
• ثبت وقایع :
  • سطح : (پیش‌فرض: خطا)
    • info - تمام درخواست‌ها و پاسخ‌هایی را که از طریق یک نمونه Edge Microgateway جریان دارند، ثبت می‌کند.
    • هشدار - فقط پیام‌های هشدار را ثبت می‌کند.
    • 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 (تغییر در محصولات، پروکسی‌های آگاه از microgateway و غیره) و همچنین تغییرات ایجاد شده در فایل پیکربندی محلی را ثبت می‌کند.
  
• disable_config_poll_interval: (پیش‌فرض: false) برای غیرفعال کردن نظرسنجی خودکار تغییر، روی true تنظیم کنید.
• request_timeout : برای درخواست‌های هدف، مهلت زمانی تعیین می‌کند. این مهلت زمانی بر حسب ثانیه تنظیم می‌شود. در صورت وقوع مهلت زمانی، Edge Microgateway با کد وضعیت ۵۰۴ پاسخ می‌دهد. (نسخه ۲.۴.x اضافه شده است)
• keep_alive_timeout : این ویژگی به شما امکان می‌دهد تا زمان انقضای Edge Microgateway را (به میلی‌ثانیه) تنظیم کنید. (پیش‌فرض: ۵ ثانیه) (اضافه شده در نسخه ۳.۰.۶)
• headers_timeout : این ویژگی مدت زمانی (برحسب میلی‌ثانیه) را که تجزیه‌کننده HTTP برای دریافت کل هدرهای HTTP منتظر می‌ماند، محدود می‌کند.

  برای مثال:

  edgemicro:
  keep_alive_timeout: 6000
  headers_timeout: 12000

  این پارامتر به صورت داخلی، ویژگی Server.headersTimeout مربوط به Node.js را برای درخواست‌ها تنظیم می‌کند. (پیش‌فرض: ۵ ثانیه بیشتر از زمان تعیین‌شده با edgemicro.keep_alive_timeout . این تنظیم پیش‌فرض مانع از قطع اشتباه اتصال توسط متعادل‌کننده‌های بار یا پروکسی‌ها می‌شود.) (نسخه ۳.۱.۱ اضافه شده است)

ویژگی‌های هدرها

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

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

ویژگی‌های oauth

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

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

ویژگی‌های خاص افزونه

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

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

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

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

فیلتر کردن محصولات

از پیکربندی زیر برای محدود کردن تعداد محصولات API که Edge Microgateway دانلود و پردازش می‌کند، استفاده کنید. برای فیلتر کردن محصولات دانلود شده، پارامتر query productnamefilter به API /products که در فایل *.config.yaml Edge Microgateway فهرست شده است، اضافه کنید. به عنوان مثال:

edge_config:
  bootstrap: >-
    https://edgemicroservices.apigee.net/edgemicro/bootstrap/organization/willwitman/environment/test
  jwt_public_key: 'https://myorg-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://myorg-test.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24'

توجه داشته باشید که مقدار پارامتر پرس‌وجو باید در قالب عبارت منظم مشخص شده و به صورت URL کدگذاری شود. برای مثال، عبارت منظم ^[Ee]dgemicro.*$ نام‌هایی مانند: "edgemicro-test-1"، "edgemicro_demo" و "Edgemicro_New_Demo" را دریافت می‌کند. مقدار کدگذاری شده URL که برای استفاده در پارامتر پرس‌وجو مناسب است، عبارت است از: %5E%5BEe%5Ddgemicro.%2A%24 .

خروجی اشکال‌زدایی زیر نشان می‌دهد که فقط محصولات فیلتر شده دانلود شده‌اند:

...
2020-05-27T03:13:50.087Z [76060] [microgateway-config network] products download from https://gsc-demo-prod.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24 returned 200 OK
...
....
....
{
   "apiProduct":[
      {
         "apiResources":[

         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1590549037549,
         "createdBy":"k***@g********m",
         "displayName":"test upper case in name",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1590549037549,
         "lastModifiedBy":"k***@g********m",
         "name":"Edgemicro_New_Demo",
         "proxies":[
            "catchall"
         ],
         "quota":"null",
         "quotaInterval":"null",
         "quotaTimeUnit":"null",
         "scopes":[

         ]
      },
      {
         "apiResources":[

         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1590548328998,
         "createdBy":"k***@g********m",
         "displayName":"edgemicro test 1",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1590548328998,
         "lastModifiedBy":"k***@g********m",
         "name":"edgemicro-test-1",
         "proxies":[
            "Lets-Encrypt-Validation-DoNotDelete"
         ],
         "quota":"null",
         "quotaInterval":"null",
         "quotaTimeUnit":"null",
         "scopes":[

         ]
      },
      {
         "apiResources":[
            "/",
            "/**"
         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1558182193472,
         "createdBy":"m*********@g********m",
         "displayName":"Edge microgateway demo product",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1569077897465,
         "lastModifiedBy":"m*********@g********m",
         "name":"edgemicro_demo",
         "proxies":[
            "edgemicro-auth",
            "edgemicro_hello"
         ],
         "quota":"600",
         "quotaInterval":"1",
         "quotaTimeUnit":"minute",
         "scopes":[

         ]
      }
   ]
}

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

از این پارامترهای پیکربندی برای کنترل فرکانس ارسال داده‌های تحلیلی توسط 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'

جداسازی فراخوانی‌های API در Edge Analytics

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

edgemicro_proxyname-health

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

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

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

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

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

در پیکربندی زیر، هر API با مسیر پروکسی /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 پشت فایروال شرکت

برای ارتباط با Apigee Edge از پروکسی HTTP استفاده کنید

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

برای استفاده از پروکسی HTTP برای ارتباط بین Edge Microgateway و Apigee Edge، موارد زیر را انجام دهید:

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

   export HTTP_PROXY='http://localhost:3786'
   export HTTPS_PROXY='https://localhost:3786'
   export NO_PROXY='localhost,localhost:8080'

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

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

2. Edge Microgateway را مجدداً راه اندازی کنید.

استفاده از پروکسی HTTP برای ارتباط با هدف

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

برای استفاده از پروکسی HTTP برای ارتباط بین Edge Microgateway و اهداف backend، موارد زیر را انجام دهید:

1. پیکربندی زیر را به فایل پیکربندی microgateway اضافه کنید:

   edgemicro:
     proxy:
       tunnel: true | false
       url: proxy_url
       bypass: target_host # target hosts to bypass the proxy.
       enabled: true | false

   کجا:

   • tunnel : (اختیاری) وقتی مقدار آن درست باشد، Edge Microgateway از متد HTTP CONNECT برای تونل کردن درخواست‌های HTTP روی یک اتصال TCP واحد استفاده می‌کند. (اگر متغیرهای محیطی، همانطور که در زیر ذکر شده است، برای پیکربندی پروکسی، TLS فعال باشند، نیز همین وضعیت صادق است.) پیش‌فرض: false
   • url : آدرس اینترنتی پروکسی HTTP.
   • bypass : (اختیاری) یک یا چند URL میزبان هدف جدا شده با کاما را مشخص می‌کند که باید از پروکسی HTTP عبور کنند. اگر این ویژگی تنظیم نشده باشد، از متغیر محیطی NO_PROXY برای مشخص کردن URLهای هدفی که باید عبور کنند، استفاده کنید.
   • enabled : اگر true باشد و proxy.url تنظیم شده باشد، از مقدار proxy.url برای پروکسی HTTP استفاده کنید. اگر true باشد و proxy.url تنظیم نشده باشد، از پروکسی‌های مشخص شده در متغیرهای محیطی پروکسی HTTP HTTP_PROXY و HTTPS_PROXY ، همانطور که در بخش «استفاده از پروکسی HTTP برای ارتباط با Apigee Edge» توضیح داده شده است، استفاده کنید.

   برای مثال:

   edgemicro:
     proxy:
       tunnel: true
       url: 'http://localhost:3786'
       bypass: 'localhost','localhost:8080' # target hosts to bypass the proxy.
       enabled: true

2. Edge Microgateway را مجدداً راه اندازی کنید.

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

شما می‌توانید از یک یا چند کاراکتر "*" در مسیر پایه یک پروکسی edgemicro_* (Microgateway-aware) استفاده کنید. برای مثال، مسیر پایه /team/*/members به ​​کلاینت‌ها اجازه می‌دهد تا بدون نیاز به ایجاد پروکسی‌های API جدید برای پشتیبانی از تیم‌های جدید، https://[host]/team/blue/members و https://[host]/team/green/members را فراخوانی کنند. توجه داشته باشید که /**/ پشتیبانی نمی‌شود.

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

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

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

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

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

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

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

تولید یک JWT جدید

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

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

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

یا می‌توانید با استفاده از 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 - The latest (most recently created) RSA private key used to sign JWTs.

• public_key - The latest (most recently created) certificate used to verify JWTs signed with the private_key.

• private_key_kid - The latest (most recently created) private key ID. This key ID is associated with the private_key value and is used to support key rotation.

• public_key1_kid - The latest (most recently created) public key ID. This key is associated with the public_key1 value and is used to support key rotation. This value is the same as the private key kid.

• public_key1 - The latest (most recently created) public key.

When you perform key rotation, existing key values are replaced in the map and new keys are added to retain the old public keys. For example:

• public_key2_kid - The old public key ID. This key is associated with the public_key2 value and is used to support key rotation.

• public_key2 - The old public key.

JWTs presented for verification will be verified using the new public key. If verification fails, then the old public key will be used, until it expires (after 30 minutes). In this way, you can "rotate" keys without immediately disrupting API traffic.

How to do key rotation

This section explains how to perform a key rotation.

If you configured your Edge Microgateway instance before version 2.5.2

If you configured your Edge Microgateway instance before version 2.5.2, then you must run the following two commands to upgrade the KVM and the authentication policy:

upgradekvm -o $ORG -e $ENV -u $USERNAME

For more information on this command, see Upgrading the KVM .

The next command upgrades the edgemicro-oauth proxy that was deployed to your Apigee org when you configured Edge Microgateway. This proxy provides services required to generate tokens.

upgradeauth -o $ORG -e $ENV -u $USERNAME

For more information on this command, see Upgrading the edgemicro-auth proxy .

Rotating the keys

Add the following line to your ~/.edgemicro/org-env-config.yaml file, where you must specify the same organization and environment that you configured the microgateway to use:

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

Run the key rotation command to rotate the keys. (For more information on this command, see Rotating keys .)

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 v12.5.0
current edgemicro version is 3.1.0
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!

The -k parameter specifies a Key ID (kid). This ID is used to match a specific key. Edge Microgateway uses this value to choose among a set of keys during key rotation. For more information, see Section 4.5 of the JSON Web Key specification .

After key rotation, Edge returns multiple keys to Edge Microgateway. Note in the following example, each key has a unique "kid" (Key ID) value. The microgateway then uses these keys to validate authorization tokens. If the token validation fails, the microgateway looks to see if there is an older key in the key set and tries that key. The format of the returned keys is JSON Web Key (JWK). You can read about this format in 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"
    }
  ]
}

Filtering downloaded proxies

By default, Edge Microgateway downloads all of the proxies in your Edge organization that start with the naming prefix "edgemicro_". You can change this default to download proxies whose names match a pattern.

1. Open your Edge Micro config file: ~/.edgemicro/org-env-config.yaml
2. Add the proxyPattern element under edge_config. For example, the following pattern will download proxies such as edgemicro_foo, edgemicro_fast, and edgemicro_first.

   edge_config:
   …
   proxyPattern: edgemicro_f*

Specifying products without API proxies

In Apigee Edge, you can create an API product that does not contain any API proxies. This product configuration allows an API key associated with that product to work for with any proxy deployed in your organization. As of version 2.5.4, Edge Microgateway supports this product configuration.

Debugging and troubleshooting

Connecting to a debugger

You can run Edge Microgateway with a debugger, such as node-inspector . This is useful for troubleshooting and debugging custom plugins.

1. Restart Edge Microgateway in debug mode. To do this, add DEBUG=* to the beginning of the start command:

   DEBUG=* edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET

   To direct debug output to a file, you can use this command:

   export DEBUG=* nohup edgemicro start \
   -o $ORG -e $ENV -k $KEY -s $SECRET 2>&1 | tee /tmp/file.log

2. Start your debugger and set it to listen on the port number for the debugging process.
3. You can now step through the Edge Microgateway code, set breakpoints, watch expressions, and so on.

You can specify standard Node.js flags related to debug mode. For example, --nolazy helps with debugging asynchronous code.

Checking log files

If you're having problems, be sure to examine the log files for execution details and error information. For details, see Managing log files .

Using API key security

API keys provide a simple mechanism for authenticating clients making requests to Edge Microgateway. You can obtain an API key by copying the Consumer Key (also called Client ID) value from an Apigee Edge product that includes the Edge Microgateway authentication proxy.

Caching of keys

API keys are exchanged for bearer tokens, which are cached. You can disable caching by setting the Cache-Control: no-cache header on incoming requests to Edge Microgateway.

Using an API key

You can pass the API key in an API request either as a query parameter or in a header. By default, the header and query param name are both x-api-key .

Query parameter example:

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

Header example:

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

Configuring the API key name

By default, x-api-key is the name used for both the API key header and query parameter. You can change this default in the configuration file, as explained in Making configuration changes . For example, to change the name to apiKey :

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

In this example, both the query parameter and header name are changed to apiKey . The name x-api-key will no longer work in either case. See also Making configuration changes .

برای مثال:

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

For more information about using API keys with proxy requests, see Secure Edge Microgateway .

Enable upstream response codes

By default, the oauth plugin returns only 4xx error status codes if the response is not a 200 status. You can change this behavior so that it always returns the exact 4xx or 5xx code, depending on the error.

To enable this feature, add the oauth.useUpstreamResponse: true property to your Edge Microgateway configuration. For example:

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  gracePeriod: 10
  useUpstreamResponse: true

Using OAuth2 token security

This section explains how to get OAuth2 access tokens and refresh tokens. Access tokens are used to make secure API calls through the microgateway. Refresh tokens are used to obtain new access tokens.

How to get an access token

This section explains how to use the edgemicro-auth proxy to get an access token.

You can also get an access token using the edgemicro token CLI command. For details on the CLI, see Managing tokens .

API 1: Send credentials as body parameters

Substitute your org and environment names in the URL, and substitute the Consumer Id and Consumer Secret values obtained from a developer app on Apigee Edge for the client_id and client_secret body parameters:

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: Send credentials in a Basic Auth header

Send the client credentials as a Basic Authentication header and the grant_type as a form parameter. This command form is also discussed in RFC 6749: The OAuth 2.0 Authorization Framework .

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"

Sample output

{
"token": "eyJraWQiOiIxIiwidHlwIjoi",
"access_token": "eyJraWQiOiIxIiwid",
"token_type": "bearer",
"expires_in": "108000"
}

How to get a refresh token

To get a refresh token, make an API call to the /token endpoint of the edgemicro-auth proxy. You MUST make this API call with the password grant type. The following steps walk through the process.

1. Get an access and refresh token with the /token API. Note that the grant type is 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"
   }'

   The API returns an access token and a refresh token. The response looks similar to this:

   {
       "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. You can now use the refresh token to get a new access token by calling the /refresh endpoint of the same API. For example:

   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"
   }'

   The API returns a new access token. The response looks similar to this:

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

Forever monitoring

Forever is a Node.js tool that automatically restarts a Node.js app in case the process goes down or has an error. Edge Microgateway has a forever.json file that you can configure to control how many times and with what intervals Edge Microgateway should be restarted. This file configures a Forever service called forever-monitor , which manages Forever programmatically.

You can find the forever.json file in the Edge Microgateway root install directory. See Where is Edge Microgateway installed . For details on the configuration options, refer to the forever-monitor documentation .

The edgemicro forever command includes flags that let you specify the location of the forever.json file (the -f flag), and start/stop the Forever monitoring process (the -a flag). For example:

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

For more information, see the Forever monitoring in the CLI reference.

Specifying a config file endpoint

If you run multiple Edge Microgateway instances, you may wish to manage their configurations from a single location. You can do this by specifying an HTTP endpoint where Edge Micro can download its configuration file. You can specify this endpoint when you start Edge Micro using the -u flag.

برای مثال:

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

where the mgconfig endpoint returns the contents of your configuration file. This is the file that, by default, is located in ~/.edgemicro and has the naming convention: org-env-config.yaml .

Disabling TCP connection data buffering

You can use the nodelay configuration attribute to disable data buffering for TCP connections used by Edge Microgateway.

By default TCP connections use the Nagle algorithm to buffer data before sending it off. Setting nodelay to true , disables this behavior (data will immediately fire off data each time socket.write() is called). See also the Node.js documentation for more details.

To enable nodelay , edit the Edge Micro config file as follows:

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

Running Edge Microgateway in standalone mode

You can run Edge Microgateway disconnected completely from any Apigee Edge dependency. This scenario, called standalone mode, lets you run and test Edge Microgateway without an Internet connection.

In standalone mode, the following features do not work, as they require connection to Apigee Edge:

• OAuth and API key
• سهمیه
• تجزیه و تحلیل

On the other hand, custom plugins and spike arrest work normally, because they do not require a connection to Apigee Edge. In addition, a new plugin called extauth lets you authorize API calls to the microgateway with a JWT while in standalone mode.

Configuring and starting the gateway

To run Edge Microgateway in standalone mode:

1. Create a configuration file named as follows: $HOME/.edgemicro/ $ORG - $ENV -config.yaml

   برای مثال:

   vi $HOME/.edgemicro/foo-bar-config.yaml

2. Paste the following code into the file:

   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

3. Export the following environment variable with the value "1":

   export EDGEMICRO_LOCAL=1

4. Execute the following start command, where you provide values to instantiate the local proxy:

   edgemicro start -o $ORG -e $ENV -a $LOCAL_PROXY_NAME \
     -v $LOCAL_PROXY_VERSION -t $TARGET_URL -b $BASE_PATH

   کجا:

   • $ORG is the "org" name that you used in the configuration file name.
   • $ENV is the "env" name that you used in the configuration file name.
   • $LOCAL_PROXY_NAME is the name of the local proxy that will be created. You can use any name you want.
   • $LOCAL_PROXY_VERSION is the version number for the proxy.
   • $TARGET_URL is the URL for the target of the proxy. (The target is the service that the proxy calls.)
   • $BASE_PATH is the base path of the proxy. This value must start with a forward slash. For a root base path, specify just a forward slash; for example, "/".

   برای مثال:

   edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /

5. Test the configuration.

   curl http://localhost:8000/echo  { "error" : "missing_authorization" }

   Because the extauth plugin is in the foo-bar-config.yaml file, you get a "missing_authorization" error. This plugin validates a JWT that must be present in the Authorization header of the API call. In the next section, you will obtain a JWT that will allow API calls to go through without the error.

Example: Obtaining an authorization token

The following example shows how to obtain a JWT from the Edge Microgateway JWT endpoint on Apigee Edge ( edgemicro-auth/jwkPublicKeys ). This endpoint is deployed when you perform a standard setup and configuration of Edge Microgateway. To obtain the JWT from the Apigee endpoint, you must first do the standard Edge Microgateway setup, and be connected to the Internet. The Apigee endpoint is used here for example purposes only and is not required. You can use another JWT token endpoint if you wish. If you do, then you'll need to obtain the JWT using the API provided for that endpoint.

The following steps explain how to get a token using the edgemicro-auth/jwkPublicKeys endpoint:.

1. You must perform a standard setup and configuration of Edge Microgateway to deploy the edgemicro-auth proxy to your organization/environment on Apigee Edge. If you did this step previously, you do not need to repeat it.
2. If you deployed Edge Microgateway to Apigee Cloud, you must be connected to the Internet so that you can obtain a JWT from this endpoint.
3. Stop Edge Microgateway:

   edgemicro stop

4. In the configuration file you created previously ( $HOME/.edgemicro / org - env -config.yaml ), point the extauth:publickey_url attribute to the edgemicro-auth/jwkPublicKeys endpoint in your Apigee Edge organization/environment. For example:

   extauth:
     publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'

5. Restart Edge Microgateway as you did previously, using the org/env names you used in the config file name. For example:

   edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /

6. Get a JWT token from the authorization endpoint. Because you are using the edgemicro-auth/jwkPublicKeys endpoint, you can use this CLI command:

You can generate a JWT for Edge Microgateway using the edgemicro token command or an API. For example:

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

کجا:

• your_org is the name of your Apigee organization for which you previously configured Edge Microgateway.
• your_env is an environment in the organization.
• The i option specifies the Consumer Key from a developer app that has a product that includes the edgemicro-auth proxy.
• The s option specifies the Consumer Secret from a developer app that has a product that includes the edgemicro-auth proxy.

This command asks Apigee Edge to generate a JWT that can then be used to verify API calls.

Test the standalone configuration

To test the configuration, call the API with the token added in the Authorization header as follows:

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":""
}

Using local proxy mode

In local proxy mode, Edge Microgateway does not require a microgateway-aware proxy to be deployed on Apigee Edge. Instead, you configure a "local proxy" by providing a local proxy name, basepath, and target URL when you start the microgateway. API calls to the microgateway are then sent to the target URL of the local proxy. In all other respects, local proxy mode works exactly the same as running Edge Microgateway in its normal mode. Authentication works the same, as do spike arrest and quota enforcement, custom plugins, and so on.

Use case and example

Local proxy mode is useful when you only need to associate one single proxy with an Edge Microgateway instance. For example, you can inject Edge Microgateway into Kubernetes as a sidecar proxy, where a microgateway and a service each run in a single pod, and where the microgateway manages traffic to and from its companion service. The following figure illustrates this architecture where Edge Microgateway functions as a sidecar proxy in a Kubernetes cluster. Each microgateway instance talks only to a single endpoint on its companion service:

A benefit of this style of architecture is that Edge Microgateway provides API management for individual services deployed to a container environment, such as a Kubernetes cluster.

Configuring local proxy mode

To configure Edge Microgateway to run in local proxy mode, follow these steps:

1. Run edgemicro init to set up your local configuration environment, exactly as you would in a typical Edge Microgateway setup. See also Configure Edge Microgateway .
2. Run edgemicro configure , as you would in a typical Edge Microgateway setup procedure. For example:

   edgemicro configure -o your_org -e your_env -u your_apigee_username

   This command deploys the edgemicro-auth policy to Edge and returns a key and secret that you will need to start the microgateway. If you need help, see Configure Edge Microgateway .

3. On Apigee Edge, create an API product and with the following mandatory configuration requirements (you can manage all other configurations as you wish):
   • You must add the edgemicro-auth proxy to the product. This proxy was deployed automatically when you ran edgemicro configure .
   • You must provide a resource path. Apigee recommends adding this path to the product: /** . To learn more, see Configuring the behavior of the resource path . See also Create API products in the Edge documentation.

4. On Apigee Edge, create a developer, or you can use an existing developer if you wish. For help, see Adding developers using the Edge management UI .

5. On Apigee Edge, create a developer app. You must add the API product you just created to the app. For help, see Registering an app in the Edge management UI .
6. On the machine where Edge Microgateway is installed, export the following environment variable with the value "1".

   export EDGEMICRO_LOCAL_PROXY=1

7. Execute the following start command:

   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 is your Apigee organization.
   • your_environment is an environment in your organization.
   • your_key is the key that was returned when you ran edgemicro configure .
   • your_secret is the secret that was returned when you ran edgemicro configure .
   • local_proxy_name is the name of the local proxy that will be created.
   • local_proxy_version is the version number for the proxy.
   • target_url is the URL for the target of the proxy (the service the proxy will call).
   • base_path is the base path of the proxy. This value must start with a forward slash. For a root base path, specify just a forward slash; for example, "/".

   برای مثال:

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

Testing the configuration

You can test the local proxy configuration by calling the proxy endpoint. For example, if you specified a basepath of /echo , you can call the proxy as follows:

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

This initial API call produced an error because you did not provide a valid API key. You can find the key in the Developer app you created previously. Open the app in the Edge UI, copy the Consumer Key, and use that key as follows:

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":""
}

Using the synchronizer

This section explains how to use the synchronizer, an optional feature that improves the resiliency of Edge Microgteway by allowing it to retrieve configuration data from Apigee Edge and write it to a local Redis database. With a synchronizer instance running, other Edge Microgateway instances running on different nodes can retrieve their configuration directly from this database.

The syncrhonizer feature is currently supported to work with Redis 5.0.x.

What is the synchronizer?

The synchronizer provides a level of resilience for Edge Microgateway. It helps ensure that every instance of Edge Microgateway uses the same configuration, and that in the event of an internet disruption, Edge Microgateway instances can start up and run properly.

By default, Edge Microgateway instances must be able to communicate with Apigee Edge to retrieve and refresh their configuration data, such as API proxy and API product configurations. If the internet connection with Edge is disrupted, microgateway instances can continue to function because the latest configuration data is cached. However, new microgateway instances cannot start up without a clear connection. Furthermore, it is possible for an internet disruption to result in one or more microgateway instances running with configuration information that is out of sync with other instances.

The Edge Microgateway synchronizer provides an alternative mechanism for Edge Microgateway instances to retrieve configuration data that they require to start up and process API proxy traffic. The synchronizer makes it possible for all of the Edge Microgateway instances running on different nodes to start up properly and stay in sync even if the internet connection between Edge Microgateway and Apigee Edge is disrupted.

The synchronizer is a specially configured instance of Edge Microgateway. Its only purpose is to poll Apigee Edge (the timing is configurable), retrieve configuration data, and write it to a local Redis database. The synchronizer instance itself cannot process API proxy traffic. Other instances of Edge Microgateway running on different nodes can be configured to retrieve configuration data from the Redis database rather than from Apigee Edge. Because all microgateway instances pull their configuration data from the local database, they can start up and process API requests even in the event of an internet disruption.

Configuring a synchronizer instance

Add the following configuration to the org-env /config.yaml file for the Edge Microgateway installation that you wish to use as the synchronizer:

edgemicro:
  redisHost: host_IP
  redisPort: host_port
  redisDb: database_index
  redisPassword: password
edge_config:
  synchronizerMode: 1
  redisBasedConfigCache: true

برای مثال:

edgemicro:
  redisHost: 192.168.4.77
  redisPort: 6379
  redisDb: 0
  redisPassword: codemaster
edge_config:
  synchronizerMode: 1
  redisBasedConfigCache: true

Finally, save the configuration file and start the Edge Microgateway instance. It will begin polling Apigee Edge and storing downloaded configuration data in the Redis database.

Configuring regular Edge Microgateway instances

With the synchronizer running, you can configure additional Edge Microgateway nodes to run regular microgateway instances that process API proxy traffic. However, you configure these instances to obtain their configuration data from the Redis database rather than from Apigee Edge.

Add the following configuration to each additional Edge Microgateway node's org-env /config.yaml file. Note that the synchronizerMode property is set to 0 . This property sets the instance to operate as a normal Edge Microgateway instance that processes API proxy traffic, and the instance will obtain its configuration data from the Redis database.

edgemicro:
  redisHost: host_IP
  redisPort: host_port
  redisDb: database_index
  redisPassword: password
edge_config:
  synchronizerMode: 0
  redisBasedConfigCache: true

برای مثال:

edgemicro:
  redisHost: 192.168.4.77
  redisPort: 6379
  redisDb: 0
  redisPassword: codemaster
edge_config:
  synchronizerMode: 0
  redisBasedConfigCache: true

Configuration properties

The following configuration properties have been added to support the use of the synchronizer: