مرجع التشغيل والضبط لطريق Edge Microgateway

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

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

يتناول هذا الموضوع كيفية إدارة Edge Microgateway وإعدادها.

ترقية Edge Microgateway في حال توفّر اتصال بالإنترنت

يوضّح هذا القسم كيفية ترقية عملية تثبيت حالية لـ Edge Microgateway. إذا كنت تعمل بدون اتصال بالإنترنت، يُرجى الاطّلاع على هل يمكنني تثبيت Edge Microgateway بدون اتصال بالإنترنت؟.

تنصح Apigee باختبار الإعداد الحالي باستخدام الإصدار الجديد قبل ترقية بيئة التشغيل الفعلي.

1. نفِّذ الأمر npm التالي للترقية إلى أحدث إصدار من Edge Microgateway:

   npm upgrade edgemicro -g

   لترقية Edge Microgateway إلى إصدار معيّن، عليك تحديد رقم الإصدار في أمر الترقية. في حال عدم تحديد رقم الإصدار، سيتم تثبيت أحدث إصدار. على سبيل المثال، للترقية إلى الإصدار 3.1.0، استخدِم الأمر التالي:

   npm upgrade edgemicro@3.1.0 -g

2. تحقَّق من رقم الإصدار. على سبيل المثال، إذا ثبّت الإصدار 3.1.0:

   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 هي بيئة في مؤسستك (مثل "اختبار" أو "إنتاج").
   • $KEY هو المفتاح الذي تم عرضه سابقًا من خلال الأمر configure.
   • $SECRET هو المفتاح الذي تم عرضه سابقًا من خلال الأمر configure.

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

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

في حال إيقاف Edge Microgateway:

1. أعِد تشغيل Edge Microgateway:

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

   المكان:

   • $ORG هو اسم مؤسسة Edge (يجب أن تكون مشرفًا في المؤسسة).
   • ‫$ENV هي بيئة في مؤسستك (مثل "اختبار" أو "إنتاج").
   • $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

شاهِد الفيديوهات التالية للتعرّف على كيفية ضبط بروتوكول أمان طبقة النقل في Apigee Edge Microgateway:

يمكنك ضبط خادم Microgateway لاستخدام بروتوكول SSL. على سبيل المثال، عند ضبط SSL، يمكنك استدعاء واجهات برمجة التطبيقات من خلال Edge Microgateway باستخدام بروتوكول "https"، على النحو التالي:

https://localhost:8000/myapi

لضبط بروتوكول SSL على خادم Microgateway، اتّبِع الخطوات التالية:

1. أنشئ شهادة ومفتاح SSL أو احصل عليهما باستخدام أداة openssl أو أي طريقة أخرى تفضّلها.
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

في ما يلي مثال على طبقة النقل الآمنة:

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 المميّز للويب (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 على "صحيح" كما يلي:

edgemicro:
  logging:
    to_console: true

باستخدام هذا الإعداد، سيتم إرسال السجلات إلى الإخراج العادي. لا يمكنك حاليًا إرسال السجلات إلى كل من stdout وإلى ملف سجلّ.

كيفية ضبط مستوى التسجيل

يمكنك ضبط مستويات السجلّ التالية: info وwarn وerror. ويُنصح باستخدام المستوى INFO. تسجّل هذه السمة جميع طلبات البيانات من واجهة برمجة التطبيقات وردودها، وهي السمة التلقائية.

كيفية تغيير فواصل سجلّ التغييرات

يمكنك ضبط هذه الفواصل الزمنية في ملف إعداد Edge Microgateway. اطّلِع أيضًا على إجراء تغييرات على الإعدادات.

السمات القابلة للضبط هي:

• ‫stats_log_interval: (القيمة التلقائية: 60) الفترة الزمنية بالثواني التي يتم خلالها كتابة سجلّ الإحصاءات في ملف سجلّ واجهة برمجة التطبيقات.
• rotate_interval: (القيمة التلقائية: 24) الفاصل الزمني بالساعات الذي يتم عنده تغيير ملفات السجلّ. على سبيل المثال:

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 لإزالة السجلات القديمة (تنظيفها).

اصطلاح تسمية ملفات السجلّ

ينتج كل مثيل من 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

لمحة عن محتوى ملف السجلّ

تمت الإضافة في: الإصدار 2.3.3

بشكلٍ تلقائي، تحذف خدمة التسجيل ملف JSON الخاص بالوكلاء والمنتجات التي تم تنزيلها ورمز JSON المميّز للويب (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

لنلقِ نظرة على كل منها على حدة:

1. عيّنة من الطلب الوارد من العميل:

1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0

• ‫1436403888651 - طابع التاريخ بتوقيت يونكس
• info: يعتمد ذلك على السياق. يمكن أن تكون info أو warn أو error، حسب مستوى السجلّ. يمكن أن تكون إحصاءات لسجلّ إحصاءات أو تحذيرًا بشأن التحذيرات أو خطأً بشأن الأخطاء.
• req: تحدّد الحدث. في هذه الحالة، يجب أن يكون الطلب من العميل.
• m: فعل HTTP المستخدَم في الطلب.
• u: الجزء من عنوان URL الذي يلي basepath.
• استبدِل h بالمضيف ورقم المنفذ الذي يستمع إليهما Edge Microgateway.
• r - المضيف البعيد والمنفذ اللذان صدر منهما طلب العميل.
• استبدِل i برقم تعريف الطلب. ستتشارك جميع إدخالات الأحداث الأربعة هذا المعرّف. يتمّ تعيين معرّف طلب فريد لكل طلب. يمكن أن يؤدي ربط سجلّات السجلّ برقم تعريف الطلب إلى تقديم معلومات قيّمة حول وقت استجابة الهدف.
• d: المدة بالمللي ثانية منذ أن تلقّى Edge Microgateway الطلب. في المثال أعلاه، تم تلقّي ردّ الجهاز المستهدف على الطلب 0 بعد 7 مللي ثانية (السطر 3)، وتم إرسال الردّ إلى العميل بعد 4 مللي ثانية إضافية (السطر 4). بعبارة أخرى، كان إجمالي وقت استجابة الطلب 11 ملي ثانية، منها 7 ملي ثانية استغرقها الهدف و4 ملي ثانية استغرقها Edge Microgateway نفسه.

2. عيّنة من الطلب الصادر إلى الهدف:

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

• ‫1436403888651 - طابع التاريخ بتوقيت يونكس
• info: يعتمد ذلك على السياق. يمكن أن تكون info أو warn أو error، حسب مستوى السجلّ. يمكن أن تكون إحصاءات لسجلّ إحصاءات أو تحذيرًا بشأن التحذيرات أو خطأً بشأن الأخطاء.
• ‫treq: تحدّد الحدث. في هذه الحالة، يكون الطلب مستهدفًا.
• m: فعل HTTP المستخدَم في الطلب المستهدف.
• u: الجزء من عنوان URL الذي يلي basepath.
• استبدِل h بالمضيف ورقم المنفذ للهدف الخلفي.
• i: معرّف إدخال في السجلّ. ستتشارك جميع إدخالات الأحداث الأربعة هذا المعرّف.

3. نموذج للرد الوارد من الهدف

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

‫1436403888651 - طابع التاريخ بتوقيت يونكس

• info: يعتمد ذلك على السياق. يمكن أن تكون info أو warn أو error، حسب مستوى السجلّ. يمكن أن تكون إحصاءات لسجلّ إحصاءات أو تحذيرًا بشأن التحذيرات أو خطأً بشأن الأخطاء.
• ‫tres: تحدّد الحدث. في هذه الحالة، يكون الردّ المستهدف.
• s: حالة استجابة HTTP.
• d: المدة بالمللي ثانية الوقت الذي استغرقه الجهاز المستهدف في تنفيذ طلب البيانات من واجهة برمجة التطبيقات
• i: معرّف إدخال في السجلّ. ستتشارك جميع إدخالات الأحداث الأربعة هذا المعرّف.

4. نموذج للردّ الصادر إلى العميل

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

‫1436403888651 - طابع التاريخ بتوقيت يونكس

• info: يعتمد ذلك على السياق. يمكن أن تكون info أو warn أو error، حسب مستوى السجلّ. يمكن أن تكون إحصاءات لسجلّ إحصاءات أو تحذيرًا بشأن التحذيرات أو خطأً بشأن الأخطاء.
• res: تحدّد الحدث. في هذه الحالة، يتم الرد على العميل.
• s: حالة استجابة HTTP.
• d: المدة بالمللي ثانية يشير ذلك إلى إجمالي الوقت المستغرَق في طلب البيانات من واجهة برمجة التطبيقات، بما في ذلك الوقت المستغرَق في واجهة برمجة التطبيقات المستهدَفة والوقت المستغرَق في Edge Microgateway نفسها.
• i: معرّف إدخال في السجلّ. ستتشارك جميع إدخالات الأحداث الأربعة هذا المعرّف.

الجدول الزمني لملف السجلّ

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

رسائل الخطأ

ستتضمّن بعض إدخالات السجلّ رسائل خطأ. للمساعدة في تحديد مكان حدوث الأخطاء وسبب حدوثها، راجِع مرجع أخطاء Edge Microgateway.

مرجع إعدادات Edge Microgateway

موقع ملف الإعداد

تتوفّر سمات الإعدادات الموضّحة في هذا القسم في ملف إعداد Edge Microgateway. يُرجى الاطّلاع أيضًا على إجراء تغييرات على الإعدادات.

سمات edge_config

تُستخدَم هذه الإعدادات لضبط التفاعل بين مثيل Edge Microgateway وApigee Edge.

• bootstrap: (القيمة التلقائية: none) عنوان URL يشير إلى خدمة خاصة بـ Edge Microgateway تعمل على Apigee Edge. تستخدم Edge Microgateway هذه الخدمة للتواصل مع Apigee Edge. يتم عرض عنوان URL هذا عند تنفيذ الأمر لإنشاء مفتاحَي التشفير العام والخاص: edgemicro genkeys. لمزيد من التفاصيل، راجِع إعداد Edge Microgateway وضبطه.
• jwt_public_key: (القيمة التلقائية: none) عنوان 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 attributes

تضبط هذه الإعدادات عملية Edge Microgateway.

• port: (القيمة التلقائية: 8000) رقم المنفذ الذي تستمع إليه عملية Edge Microgateway.
• max_connections: (القيمة التلقائية: -1) تحدّد الحد الأقصى لعدد الاتصالات الواردة المتزامنة التي يمكن أن يتلقّاها Edge Microgateway. في حال تجاوز هذا العدد، سيتم عرض الحالة التالية:
  
  res.statusCode = 429; // Too many requests
  
• max_connections_hard: (القيمة التلقائية: -1) الحد الأقصى لعدد الطلبات المتزامنة التي يمكن أن يتلقّاها Edge Microgateway قبل إغلاق الاتصال. يهدف هذا الإعداد إلى إحباط هجمات الحرمان من الخدمات. عادةً، اضبطه على رقم أكبر من max_connections.
• تسجيل البيانات:
  • المستوى: (القيمة التلقائية: خطأ)
    • info: يسجّل جميع الطلبات والردود التي تمر عبر مثيل Edge Microgateway.
    • warn: لتسجيل رسائل التحذير فقط.
    • error: لتسجيل رسائل الخطأ فقط
  • dir: (القيمة التلقائية: /var/tmp) الدليل الذي يتم فيه تخزين ملفات السجلّ.
  • stats_log_interval: (القيمة التلقائية: 60) الفترة الزمنية، بالثواني، التي يتم خلالها كتابة سجلّ الإحصاءات في ملف سجلّ واجهة برمجة التطبيقات.
  • rotate_interval: (القيمة التلقائية: 24) الفاصل الزمني بالساعات الذي يتم عنده تغيير ملفات السجلّ.

• المكوّنات الإضافية: تضيف المكوّنات الإضافية وظائف إلى Edge Microgateway. للحصول على تفاصيل حول تطوير المكوّنات الإضافية، يُرجى الاطّلاع على تطوير مكوّنات إضافية مخصّصة.

• dir: مسار نسبي من الدليل ‎ ./gateway إلى الدليل ‎./plugins، أو مسار مطلق.
• sequence: قائمة بوحدات المكوّنات الإضافية التي ستتم إضافتها إلى مثيل Edge Microgateway. سيتم تنفيذ الوحدات بالترتيب المحدّد هنا.

• debug: يضيف تصحيح الأخطاء عن بُعد إلى عملية Edge Microgateway.
  • port: رقم المنفذ الذي سيتم الاستماع إليه. على سبيل المثال، اضبط مصحّح أخطاء بيئة التطوير المتكاملة (IDE) على الاستماع على هذا المنفذ.
  • args: وسيطات عملية تصحيح الأخطاء على سبيل المثال: args --nolazy
    
• config_change_poll_interval: (القيمة التلقائية: 600 ثانية) تحمّل Edge Microgateway إعدادات جديدة بشكل دوري وتنفّذ عملية إعادة تحميل إذا تم تغيير أي شيء. يتم رصد أي تغييرات يتم إجراؤها على Edge (تغييرات على المنتجات، والوكلاء الذين يمكنهم استخدام البوابة المصغّرة، وما إلى ذلك) بالإضافة إلى التغييرات التي يتم إجراؤها على ملف الإعدادات المحلي.
  
• disable_config_poll_interval: (القيمة التلقائية: false) اضبط على true لإيقاف عملية الاقتراع التلقائي للتغيير.
• ‫request_timeout: لضبط مهلة لطلبات الاستهداف. يتم ضبط المهلة بالثواني. في حال حدوث مهلة، يستجيب Edge Microgateway برمز الحالة 504. (تمت الإضافة في الإصدار 2.4.x)
• keep_alive_timeout: تتيح لك هذه السمة ضبط مهلة Edge Microgateway (بالمللي ثانية). (القيمة التلقائية: 5 ثوانٍ) (تمت الإضافة في الإصدار 3.0.6)
• headers_timeout: تحدّد هذه السمة مقدار الوقت (بالمللي ثانية) الذي سينتظره محلّل HTTP لتلقّي عناوين HTTP الكاملة.

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

  edgemicro:
  keep_alive_timeout: 6000
  headers_timeout: 12000

  داخليًا، تضبط المَعلمة السمة Server.headersTimeout في Node.js على الطلبات. (القيمة التلقائية: 5 ثوانٍ أكثر من الوقت الذي تم ضبطه باستخدام edgemicro.keep_alive_timeout. يمنع هذا الإعداد التلقائي موازنات التحميل أو الخوادم الوكيلة من قطع الاتصال عن طريق الخطأ.) (تمت الإضافة في الإصدار 3.1.1)

سمات العناوين

تضبط هذه الإعدادات طريقة التعامل مع بعض عناوين HTTP.

• x-forwarded-for: (القيمة التلقائية: true) اضبط القيمة على false لمنع تمرير رؤوس x-forwarded-for إلى الهدف. يُرجى العِلم أنّه إذا كان عنوان x-forwarded-for مضمّنًا في الطلب، سيتم ضبط قيمته على قيمة client-ip في Edge Analytics.
• x-forwarded-host: (القيمة التلقائية: true) اضبط القيمة على false لمنع تمرير عناوين x-forwarded-host إلى الهدف.
• x-request-id: (القيمة التلقائية: true) اضبط القيمة على false لمنع تمرير عناوين x-request-id إلى الهدف.
• x-response-time: (القيمة التلقائية: true) اضبطها على false لمنع تمرير عناوين x-response-time إلى الهدف.
• via: (القيمة التلقائية: true) اضبط القيمة على false لمنع تمرير عناوين via إلى الهدف.

سمات OAuth

تضبط هذه الإعدادات طريقة فرض مصادقة العميل من خلال Edge Microgateway.

• allowNoAuthorization: (القيمة التلقائية: false) إذا تم ضبطها على true، سيتم السماح بمرور طلبات البيانات من واجهة برمجة التطبيقات عبر Edge Microgateway بدون أي عنوان Authorization على الإطلاق. اضبط هذا الخيار على false لطلب عنوان Authorization (تلقائي).
• allowInvalidAuthorization: (القيمة التلقائية: false) في حال ضبطها على true، يُسمح بتمرير طلبات البيانات من واجهة برمجة التطبيقات إذا كان الرمز المميّز الذي تم تمريره في عنوان Authorization غير صالح أو انتهت صلاحيته. اضبط هذه السمة على "خطأ" لطلب رموز مميزة صالحة (الإعداد التلقائي).
• authorization-header: (القيمة التلقائية: Authorization: Bearer) العنوان المستخدَم لإرسال رمز الدخول إلى Edge Microgateway. يمكنك تغيير الإعداد التلقائي في الحالات التي يحتاج فيها الهدف إلى استخدام عنوان Authorization لغرض آخر.
• api-key-header: (القيمة التلقائية: x-api-key) اسم العنوان أو مَعلمة الطلب المستخدَمة لتمرير مفتاح واجهة برمجة التطبيقات إلى Edge Microgateway. يمكنك أيضًا الاطّلاع على استخدام مفتاح واجهة برمجة تطبيقات.
• keep-authorization-header: (القيمة التلقائية: false) إذا تم ضبطها على true، سيتم تمرير عنوان Authorization الذي تم إرساله في الطلب إلى الهدف (سيتم الاحتفاظ به).
• allowOAuthOnly: إذا تم ضبط القيمة على "صحيح"، يجب أن يتضمّن كل طلب لواجهة برمجة التطبيقات عنوان Authorization مع رمز مميّز للدخول من النوع Bearer. يسمح لك بالسماح بنموذج أمان OAuth فقط (مع الحفاظ على التوافق مع الإصدارات القديمة). (تمت الإضافة في الإصدار 2.4.x)
• allowAPIKeyOnly: إذا تم ضبطها على "صحيح"، يجب أن تتضمّن كل واجهة برمجة تطبيقات عنوان x-api-key (أو موقعًا مخصّصًا) مع مفتاح واجهة برمجة التطبيقات.يتيح لك ذلك السماح بنموذج أمان مفتاح واجهة برمجة التطبيقات فقط (مع الحفاظ على التوافق مع الإصدارات السابقة). (تمت الإضافة في الإصدار 2.4.x)
• gracePeriod: تساعد هذه المَعلمة في تجنُّب الأخطاء الناتجة عن الاختلافات الطفيفة بين ساعة نظامك وأوقات "ليس قبل" (nbf) أو "تم الإصدار في" (iat) المحدّدة في رمز التخويل المميز بتنسيق JWT. اضبط هذه المَعلمة على عدد الثواني المسموح بها لهذه التناقضات. (تمت إضافة هذه الميزة في الإصدار 2.5.7)

السمات الخاصة بالإضافة

راجِع مقالة استخدام المكوّنات الإضافية للحصول على تفاصيل حول السمات القابلة للضبط لكل مكوّن إضافي.

خوادم الوكيل التي تتيح الفلترة

يمكنك فلترة الخوادم الوكيلة المتوافقة مع microgateway التي ستعالجها إحدى مثيلات Edge Microgateway. عند بدء تشغيل Edge Microgateway، يتم تنزيل جميع الخوادم الوكيلة المتوافقة مع microgateway في المؤسسة المرتبطة بها. استخدِم الإعدادات التالية للحدّ من الخوادم الوكيلة التي ستعالجها البوابة المصغّرة. على سبيل المثال، يحدّ هذا الإعداد من عدد الخوادم الوكيلة التي ستعالجها البوابة المصغّرة إلى ثلاثة: edgemicro_proxy-1 وedgemicro_proxy-2 وedgemicro_proxy-3:

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

فلترة المنتجات

استخدِم الإعداد التالي للحدّ من عدد منتجات واجهة برمجة التطبيقات التي تنزّلها Edge Microgateway وتعالجها. لفلترة المنتجات التي تم تنزيلها، أضِف مَعلمة طلب البحث productnamefilter إلى واجهة برمجة التطبيقات /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":[

         ]
      }
   ]
}

ضبط معدّل تكرار إرسال البيانات إلى "إحصاءات Google"

استخدِم مَعلمات الإعداد هذه للتحكّم في معدّل تكرار إرسال Edge Microgateway لبيانات الإحصاءات إلى Apigee:

• bufferSize (اختياري): الحد الأقصى لعدد سجلات الإحصاءات التي يمكن أن يحتويها المخزن المؤقت قبل البدء في حذف أقدم السجلات. القيمة التلقائية: 10000
• batchSize (اختياري): الحدّ الأقصى لحجم مجموعة من سجلّات الإحصاءات المرسَلة إلى Apigee. القيمة التلقائية: 500
• flushInterval (اختياري): عدد الملّي ثواني بين كل عملية إرسال لمجموعة من سجلات الإحصاءات إلى Apigee. القيمة التلقائية: 5000

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

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

إخفاء بيانات الإحصاءات

يمنع الإعداد التالي ظهور معلومات مسار الطلب في إحصاءات Edge. أضِف ما يلي إلى إعدادات البوابة المصغّرة لإخفاء معرّف الموارد المنتظم (URI) للطلب و/أو مسار الطلب. يُرجى العِلم أنّ معرّف الموارد المنتظم (URI) يتألف من اسم المضيف وأجزاء المسار من الطلب.

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

فصل طلبات البيانات من واجهة برمجة التطبيقات في Edge Analytics

يمكنك ضبط مكوّن الإحصاءات الإضافي لفصل مسار واجهة برمجة تطبيقات معيّن حتى يظهر كخادم وكيل منفصل في لوحات بيانات Edge Analytics. على سبيل المثال، يمكنك فصل واجهة برمجة تطبيقات فحص السلامة في لوحة البيانات لتجنُّب الخلط بينها وبين طلبات خادم وكيل واجهة برمجة التطبيقات الفعلية. في لوحة بيانات "إحصاءات Google"، تتّبع الخوادم الوكيلة المنفصلة نمط التسمية التالي:

edgemicro_proxyname-health

تعرض الصورة التالية خادِمَين وكيلَين منفصلَين في لوحة بيانات "إحصاءات Google": edgemicro_hello-health وedgemicro_mock-health:

استخدِم المَعلمات التالية لفصل المسارات النسبية والمطلقة في لوحة بيانات "إحصاءات Google" كخوادم وكيل منفصلة:

• ‫relativePath (اختياري): تحدّد مسارًا نسبيًا للفصل في لوحة بيانات "إحصاءات Google". على سبيل المثال، إذا حدّدت /healthcheck، ستظهر جميع طلبات البيانات من واجهة برمجة التطبيقات التي تتضمّن المسار /healthcheck في لوحة البيانات على النحو edgemicro_proxyname-health. يُرجى العِلم أنّ هذه العلامة تتجاهل مسار قاعدة الخادم الوكيل. للتصنيف استنادًا إلى مسار كامل، بما في ذلك basepath، استخدِم العلامة proxyPath.
• proxyPath (اختياري): يحدّد مسارًا كاملاً لخادم وكيل لواجهة برمجة التطبيقات، بما في ذلك basepath الخاص بالخادم الوكيل، وذلك للفصل في لوحة بيانات الإحصاءات. على سبيل المثال، إذا حدّدت /mocktarget/healthcheck، حيث /mocktarget هو المسار الأساسي للخادم الوكيل، ستظهر جميع طلبات البيانات من واجهة برمجة التطبيقات التي تتضمّن المسار /mocktarget/healthcheck في لوحة البيانات على النحو edgemicro_proxyname-health.

على سبيل المثال، في الإعداد التالي، سيتم فصل أي مسار لواجهة برمجة التطبيقات يحتوي على /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 خلف جدار حماية تابع للشركة

استخدام خادم وكيل HTTP للتواصل مع Apigee Edge

تمت إضافة هذه الميزة في الإصدار 3.1.2.

لاستخدام خادم وكيل 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 للتواصل مع الهدف

تمت إضافة هذه الميزة في الإصدار 3.1.2.

لاستخدام خادم وكيل HTTP للتواصل بين Edge Microgateway وأهداف الخلفية، اتّبِع الخطوات التالية:

1. أضِف الإعدادات التالية إلى ملف إعداد البوابة المصغّرة:

   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: عنوان URL لخادم وكيل HTTP.
   • bypass: (اختياري) يحدّد عنوان URL واحدًا أو أكثر للمضيف المستهدف مفصولاً بفواصل، ويجب أن يتجاوز الخادم الوكيل HTTP. في حال عدم ضبط هذه السمة، استخدِم متغيّر البيئة NO_PROXY لتحديد عناوين URL المستهدَفة التي سيتم تجاوزها.
   • enabled: إذا كانت القيمة صحيحة وتم ضبط proxy.url، استخدِم قيمة proxy.url للخادم الوكيل HTTP. إذا كانت القيمة صحيحة ولم يتم ضبط 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.

استخدام أحرف البدل في الخوادم الوكيلة المتوافقة مع Microgateway

يمكنك استخدام حرف بدل واحد أو أكثر من حرف البدل "*" في المسار الأساسي لخادم وكيل edgemicro_* (متوافق مع Microgateway). على سبيل المثال، يسمح مسار أساسي بقيمة /team/*/members للعملاء باستدعاء https://[host]/team/blue/members وhttps://[host]/team/green/members بدون الحاجة إلى إنشاء خوادم وكيلة جديدة لواجهة برمجة التطبيقات لدعم فِرق جديدة. يُرجى العِلم أنّ /**/ غير متاح.

ملاحظة مُهمّة: لا تتيح Apigee استخدام حرف البدل "*" كعنصر أول في مسار أساسي. على سبيل المثال، لا يمكن استخدام البحث /*/.

تدوير مفاتيح JWT

بعد إنشاء رمز JWT في البداية، قد تحتاج إلى تغيير زوج المفتاح العام/الخاص المخزَّن في KVM المشفّر على Edge. وتُعرف عملية إنشاء زوج مفاتيح جديد باسم "تغيير المفتاح".

طريقة استخدام Edge Microgateway لرموز JWT

رمز JSON المميّز للويب (JWT) هو معيار للرموز المميّزة موصوف في RFC7519. توفّر رموز JWT طريقة لتوقيع مجموعة من المطالبات، ويمكن للمستلم التحقّق منها بشكل موثوق.

يستخدم Edge Microgateway رموز JWT المميزة كرموز مميزة لحاملها لأمان OAuth. عند إنشاء رمز مميّز لبروتوكول OAuth في Edge Microgateway، سيتم إرجاع رمز JWT إليك. يمكنك بعد ذلك استخدام رمز JWT في عنوان Authorization لطلبات البيانات من واجهة برمجة التطبيقات. على سبيل المثال:

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

إنشاء رمز JWT جديد

يمكنك إنشاء رمز JWT لـ Edge Microgateway باستخدام الأمر edgemicro token أو واجهة برمجة تطبيقات. على سبيل المثال:

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

يطلب هذا الأمر من Apigee Edge إنشاء رمز JWT يمكن استخدامه بعد ذلك للتحقّق من صحة طلبات واجهة برمجة التطبيقات. المَعلمتان -i و-s هما معرّف المستهلك وقيم السرّ من تطبيق مطوّر في مؤسسة Apigee Edge.

يمكنك أيضًا إنشاء رمز JWT باستخدام Management API:

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 هي بيئة في مؤسستك (مثل "اختبار" أو "إنتاج").
• $CLIENT_ID هو رقم تعريف المستهلك في تطبيق المطوّر الذي أنشأته سابقًا.
• $CLIENT_SECRET هو Consumer Secret في تطبيق المطوّر الذي أنشأته سابقًا.

ما هو تغيير المفتاح؟

بعد إنشاء رمز JWT في البداية، قد تحتاج إلى تغيير زوج المفتاح العام/الخاص المخزَّن في KVM المشفّر على Edge. وتُعرف عملية إنشاء زوج مفاتيح جديد باسم "تغيير المفتاح". عند تدوير المفاتيح، يتم إنشاء زوج مفتاح خاص/عام جديد وتخزينه في KVM الخاص بـ "البوابة المصغّرة" في مؤسسة/بيئة 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 المقدَّمة باستخدام المفتاح العام الجديد. إذا تعذّر إثبات صحة المفتاح، سيتم استخدام المفتاح العام القديم إلى أن تنتهي صلاحيته (بعد 30 دقيقة). بهذه الطريقة، يمكنك "تدوير" المفاتيح بدون إيقاف زيارات واجهة برمجة التطبيقات على الفور.

كيفية تغيير المفتاح

يوضّح هذا القسم كيفية إجراء عملية تدوير المفتاح.

إذا سبق لك ضبط إعدادات مثيل Edge Microgateway قبل الإصدار 2.5.2

إذا سبق لك ضبط مثيل Edge Microgateway قبل الإصدار 2.5.2، عليك تنفيذ الأمرَين التاليَين لترقية KVM وسياسة المصادقة:

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

لمزيد من المعلومات حول هذا الأمر، يُرجى الاطّلاع على ترقية KVM.

تعمل الأوامر التالية على ترقية الخادم الوكيل edgemicro-oauth الذي تم نشره في مؤسسة Apigee عند ضبط إعدادات Edge Microgateway. يقدّم هذا الخادم الوكيل الخدمات المطلوبة لإنشاء الرموز المميزة.

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 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!

تحدّد المَعلمة -k رقم تعريف المفتاح (kid). يُستخدَم رقم التعريف هذا لمطابقة مفتاح معيّن. تستخدم Edge Microgateway هذه القيمة للاختيار من بين مجموعة من المفاتيح أثناء تدوير المفاتيح. لمزيد من المعلومات، يُرجى الاطّلاع على القسم 4.5 من مواصفات مفتاح الويب بتنسيق JSON.

بعد تدوير المفتاح، يعرض Edge مفاتيح متعددة إلى Edge Microgateway. يُرجى العِلم أنّه في المثال التالي، يحتوي كل مفتاح على قيمة فريدة لـ "kid" (معرّف المفتاح). بعد ذلك، تستخدم البوابة المصغّرة هذه المفاتيح للتحقّق من صحة رموز التفويض. إذا تعذّر التحقّق من صحة الرمز المميّز، يبحث البوابة المصغّرة عن مفتاح أقدم في مجموعة المفاتيح ويحاول استخدامه. تكون المفاتيح التي يتم عرضها بتنسيق مفتاح ويب JSON (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، يمكنك إنشاء منتج لواجهة برمجة التطبيقات لا يحتوي على أي خوادم وكيلة لواجهة برمجة التطبيقات. يسمح إعداد المنتج هذا بأن يعمل مفتاح واجهة برمجة التطبيقات المرتبط بهذا المنتج مع أي وكيل تم نشره في مؤسستك. اعتبارًا من الإصدار 2.5.4، يتيح Edge Microgateway إعدادات المنتج هذه.

تصحيح الأخطاء وتحديد المشاكل وحلّها

الاتصال بأداة تصحيح الأخطاء

يمكنك تشغيل Edge Microgateway باستخدام أداة تصحيح أخطاء، مثل node-inspector. ويفيد ذلك في تحديد المشاكل وحلّها في المكوّنات الإضافية المخصّصة.

1. أعِد تشغيل Edge Microgateway في وضع تصحيح الأخطاء. لإجراء ذلك، أضِف DEBUG=* إلى بداية الأمر start:

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

   لتوجيه ناتج تصحيح الأخطاء إلى ملف، يمكنك استخدام الأمر التالي:

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

2. ابدأ برنامج تصحيح الأخطاء واضبطه على الاستماع إلى رقم المنفذ لعملية تصحيح الأخطاء.
3. يمكنك الآن تتبُّع الرمز البرمجي لـ Edge Microgateway خطوة بخطوة، وضبط نقاط توقّف، ومشاهدة التعبيرات، وما إلى ذلك.

يمكنك تحديد علامات Node.js العادية ذات الصلة بوضع تصحيح الأخطاء. على سبيل المثال، تساعد --nolazy في تصحيح الأخطاء في الرموز غير المتزامنة.

التحقّق من ملفات السجلّ

إذا كنت تواجه مشاكل، احرص على فحص ملفات السجلّ للحصول على تفاصيل التنفيذ ومعلومات الخطأ. لمزيد من التفاصيل، يُرجى الاطّلاع على إدارة ملفات السجلّ.

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

توفر مفاتيح واجهة برمجة التطبيقات آلية بسيطة لمصادقة العملاء الذين يرسلون طلبات إلى Edge Microgateway. يمكنك الحصول على مفتاح واجهة برمجة التطبيقات من خلال نسخ قيمة "مفتاح المستهلك" (المعروف أيضًا باسم "معرّف العميل") من منتج Apigee Edge يتضمّن وكيل مصادقة Edge Microgateway.

تخزين المفاتيح مؤقتًا

يتم استبدال مفاتيح واجهة برمجة التطبيقات برموز مميّزة حاملة يتم تخزينها مؤقتًا. يمكنك إيقاف التخزين المؤقت من خلال ضبط عنوان 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 هو الاسم المستخدَم لكلّ من عنوان مفتاح واجهة برمجة التطبيقات ومَعلمة طلب البحث. يمكنك تغيير هذه القيمة التلقائية في ملف الإعداد، كما هو موضّح في مقالة إجراء تغييرات في الإعدادات. على سبيل المثال، لتغيير الاسم إلى 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.

تفعيل رموز الاستجابة من المصدر

تُرجع إضافة oauth تلقائيًا رموز حالة الخطأ 4xx فقط إذا لم تكن الاستجابة هي الحالة 200. يمكنك تغيير هذا السلوك ليعرض دائمًا رمز الخطأ 4xx أو 5xx، وذلك حسب نوع الخطأ.

لتفعيل هذه الميزة، أضِف السمة oauth.useUpstreamResponse: true إلى إعدادات Edge Microgateway. على سبيل المثال:

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

استخدام أمان الرمز المميز OAuth2

يوضّح هذا القسم كيفية الحصول على رموز الدخول ورموز إعادة التحميل لبروتوكول OAuth2. تُستخدَم رموز الدخول المميزة لإجراء طلبات آمنة من واجهة برمجة التطبيقات من خلال البوابة المصغّرة. تُستخدَم رموز إعادة التحميل للحصول على رموز دخول جديدة.

كيفية الحصول على رمز دخول

يوضّح هذا القسم كيفية استخدام الخادم الوكيل edgemicro-auth للحصول على رمز دخول.

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

واجهة برمجة التطبيقات 1: إرسال بيانات الاعتماد كمعلَمات في نص الطلب

استبدِل اسمَي المؤسسة والبيئة في عنوان URL، واستبدِل قيمتَي معرّف المستهلك وسر المستهلك اللتين تم الحصول عليهما من تطبيق مطوّر على 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"

واجهة برمجة التطبيقات 2: إرسال بيانات الاعتماد في عنوان Basic Auth

أرسِل بيانات اعتماد العميل كعنوان مصادقة أساسية و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"

مثال على الناتج

{
"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 لواجهة برمجة التطبيقات نفسها. على سبيل المثال:

   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. اطّلِع على مكان تثبيت Edge Microgateway. للحصول على تفاصيل حول خيارات الإعداد، يُرجى الرجوع إلى مستندات forever-monitor.

يتضمّن الأمر edgemicro forever علامات تتيح لك تحديد موقع الملف forever.json (العلامة -f) وبدء عملية المراقبة المستمرة وإيقافها (العلامة -a). على سبيل المثال:

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

لمزيد من المعلومات، يُرجى الاطّلاع على المراقبة الدائمة في مرجع واجهة سطر الأوامر.

تحديد نقطة نهاية لملف الإعداد

في حال تشغيل نُسخ متعددة من 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 ومفتاح واجهة برمجة التطبيقات
• الحصة
• إحصاءات Google

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

ضبط المدخل وبدء استخدامه

لتشغيل Edge Microgateway في الوضع المستقل، اتّبِع الخطوات التالية:

1. أنشئ ملف إعداد بالاسم التالي: $HOME/.edgemicro/$ORG-$ENV-config.yaml

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

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

2. ألصِق الرمز التالي في الملف:

   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. صدِّر متغير البيئة التالي بالقيمة "1":

   export EDGEMICRO_LOCAL=1

4. نفِّذ الأمر start التالي، مع تقديم قيم لإنشاء مثيل للوكيل المحلي:

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

   المكان:

   • ‫$ORG هو اسم "المؤسسة" الذي استخدمته في اسم ملف الإعداد.
   • $ENV هو اسم "env" الذي استخدمته في اسم ملف الإعدادات.
   • $LOCAL_PROXY_NAME هو اسم الخادم الوكيل المحلي الذي سيتم إنشاؤه. يمكنك استخدام أي اسم تريده.
   • ‫$LOCAL_PROXY_VERSION هو رقم إصدار الخادم الوكيل.
   • ‫$TARGET_URL هو عنوان URL الخاص بالهدف من الخادم الوكيل. (الهدف هو الخدمة التي يستدعيها الخادم الوكيل).
   • ‫$BASE_PATH هو المسار الأساسي للخادم الوكيل. يجب أن تبدأ هذه القيمة بشرطة مائلة للأمام. بالنسبة إلى مسار أساسي جذر، حدِّد شرطة مائلة للأمام فقط، مثل "/".

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

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

5. اختبِر الإعدادات.

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

   بما أنّ المكوّن الإضافي extauth موجود في الملف foo-bar-config.yaml، سيظهر لك الخطأ "missing_authorization". يتحقّق هذا المكوّن الإضافي من صحة رمز JWT يجب أن يكون مضمّنًا في عنوان Authorization لطلب البيانات من واجهة برمجة التطبيقات. في القسم التالي، ستحصل على رمز JWT يتيح إجراء طلبات إلى واجهة برمجة التطبيقات بدون حدوث الخطأ.

مثال: الحصول على رمز مميَّز للتفويض

يوضّح المثال التالي كيفية الحصول على رمز JWT من نقطة نهاية JWT في Edge Microgateway على Apigee Edge (edgemicro-auth/jwkPublicKeys). يتم نشر نقطة النهاية هذه عند إجراء عملية إعداد وضبط عادية لـ Edge Microgateway. للحصول على رمز JWT من نقطة نهاية Apigee، يجب أولاً إكمال عملية الإعداد العادية لـ Edge Microgateway، والتأكّد من أنّ الجهاز متصل بالإنترنت. يتم استخدام نقطة نهاية Apigee هنا لأغراض توضيحية فقط، وهي ليست مطلوبة. يمكنك استخدام نقطة نهاية أخرى لرمز JWT المميز إذا أردت ذلك. في حال إجراء ذلك، عليك الحصول على رمز JWT باستخدام واجهة برمجة التطبيقات المتوفّرة لنقطة النهاية هذه.

توضّح الخطوات التالية كيفية الحصول على رمز مميّز باستخدام نقطة النهاية edgemicro-auth/jwkPublicKeys:

1. يجب إجراء عملية إعداد وتكوين عادية لـ Edge Microgateway من أجل نشر الخادم الوكيل edgemicro-auth في مؤسستك أو بيئتك على Apigee Edge. إذا سبق لك إجراء هذه الخطوة، ليس عليك تكرارها.
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 كما فعلت سابقًا، باستخدام أسماء المؤسسة/البيئة التي استخدمتها في اسم ملف الإعداد. على سبيل المثال:

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

6. احصل على رمز JWT المميز من نقطة نهاية التفويض. بما أنّك تستخدم نقطة النهاية edgemicro-auth/jwkPublicKeys، يمكنك استخدام أمر واجهة سطر الأوامر التالي:

يمكنك إنشاء رمز JWT لـ Edge Microgateway باستخدام الأمر edgemicro token أو واجهة برمجة تطبيقات. على سبيل المثال:

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

المكان:

• your_org هو اسم مؤسستك على Apigee التي سبق لك ضبط إعدادات Edge Microgateway لها.
• your_env هي بيئة في المؤسسة.
• يحدّد الخيار i مفتاح المستهلك من تطبيق مطوّر يتضمّن منتجًا يتضمّن وكيل edgemicro-auth.
• يحدّد الخيار s Consumer Secret من تطبيق مطوّر يتضمّن منتجًا يتضمّن الخادم الوكيل edgemicro-auth.

يطلب هذا الأمر من Apigee Edge إنشاء رمز JWT يمكن استخدامه بعد ذلك للتحقّق من صحة طلبات واجهة برمجة التطبيقات.

اختبار الإعداد المستقل

لاختبار الإعدادات، يمكنك طلب البيانات من واجهة برمجة التطبيقات مع إضافة الرمز المميز في عنوان Authorization على النحو التالي:

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 على Apigee Edge. بدلاً من ذلك، يمكنك ضبط "خادم وكيل محلي" من خلال تقديم اسم خادم وكيل محلي ومسار أساسي وعنوان URL مستهدف عند بدء تشغيل البوابة المصغّرة. بعد ذلك، يتم إرسال طلبات البيانات من واجهة برمجة التطبيقات إلى البوابة المصغّرة إلى عنوان URL المستهدف للوكيل المحلي. وفي جميع الجوانب الأخرى، يعمل وضع الخادم الوكيل المحلي بالطريقة نفسها تمامًا التي يعمل بها Edge Microgateway في وضعه العادي. تعمل المصادقة بالطريقة نفسها، وكذلك عمليات منع الارتفاع المفاجئ في عدد الطلبات وفرض الحصص والمكوّنات الإضافية المخصّصة وما إلى ذلك.

حالة الاستخدام والمثال

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

من مزايا هذا النوع من البنية أنّ Edge Microgateway توفّر إدارة واجهات برمجة التطبيقات للخدمات الفردية التي يتم نشرها في بيئة حاوية، مثل مجموعة Kubernetes.

ضبط وضع الخادم الوكيل المحلي

لضبط Edge Microgateway للتشغيل في وضع الخادم الوكيل المحلي، اتّبِع الخطوات التالية:

1. نفِّذ الأمر edgemicro init لإعداد بيئة الإعدادات المحلية، تمامًا كما تفعل في عملية إعداد Edge Microgateway العادية. اطّلِع أيضًا على ضبط Edge Microgateway.
2. نفِّذ الأمر edgemicro configure، كما تفعل في إجراءات إعداد Edge Microgateway العادية. على سبيل المثال:

   edgemicro configure -o your_org -e your_env -u your_apigee_username

   ينشر هذا الأمر سياسة edgemicro-auth إلى Edge ويعرض مفتاحًا وسرًا ستحتاج إليهما لبدء تشغيل البوابة المصغّرة. إذا كنت بحاجة إلى مساعدة، اطّلِع على ضبط Edge Microgateway.

3. في Apigee Edge، أنشئ منتجًا من منتجات واجهة برمجة التطبيقات مع متطلبات الإعداد الإلزامي التالية (يمكنك إدارة جميع الإعدادات الأخرى كما تريد):
   • يجب إضافة وكيل edgemicro-auth إلى المنتج. تم نشر هذا الخادم الوكيل تلقائيًا عند تشغيل edgemicro configure.
   • يجب تقديم مسار مورد. تنصح Apigee بإضافة هذا المسار إلى المنتج: /**. لمزيد من المعلومات، اطّلِع على ضبط سلوك مسار المورد. يمكنك أيضًا الاطّلاع على إنشاء منتجات API في مستندات Edge.

4. في Apigee Edge، أنشئ حساب مطوّر أو يمكنك استخدام حساب مطوّر حالي إذا أردت ذلك. للحصول على المساعدة، يُرجى الاطّلاع على إضافة مطوّرين باستخدام واجهة مستخدم إدارة Edge.

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

   export EDGEMICRO_LOCAL_PROXY=1

7. نفِّذ الأمر 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 هو عنوان 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"
}

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

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

استخدام أداة المزامنة

يوضّح هذا القسم كيفية استخدام أداة المزامنة، وهي ميزة اختيارية تعمل على تحسين مرونة Edge Microgateway من خلال السماح لها باسترداد بيانات الإعداد من Apigee Edge وكتابتها في قاعدة بيانات Redis محلية. عند تشغيل مثيل مزامنة، يمكن لمثيلات Edge Microgateway الأخرى التي تعمل على عُقد مختلفة استرداد إعداداتها مباشرةً من قاعدة البيانات هذه.

تتوافق ميزة المزامنة حاليًا مع Redis 5.0.x.

ما هو أداة المزامنة؟

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

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

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

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

ضبط مثيل أداة المزامنة

أضِف الإعداد التالي إلى ملف org-env/config.yaml لعملية تثبيت Edge Microgateway التي تريد استخدامها كمزامِن:

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

أخيرًا، احفظ ملف الإعداد وابدأ مثيل Edge Microgateway. سيبدأ في طلب البيانات من Apigee Edge وتخزين بيانات الإعداد التي تم تنزيلها في قاعدة بيانات Redis.

ضبط مثيلات Edge Microgateway العادية

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

أضِف الإعداد التالي إلى ملف org-env/config.yaml لكل عقدة إضافية من Edge Microgateway. يُرجى العِلم أنّ السمة synchronizerMode مضبوطة على 0. يضبط هذا الموقع المثيل ليعمل كمثيل عادي من Edge Microgateway يعالج حركة مرور خادم وكيل لواجهة برمجة التطبيقات، وسيحصل المثيل على بيانات الإعداد من قاعدة بيانات Redis.

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

خصائص الإعداد

تمت إضافة خصائص الإعداد التالية لإتاحة استخدام أداة المزامنة: