يتم الآن عرض مستندات Apigee Edge.
انتقِل إلى مستندات
Apigee X. المعلومات
Edge Microgateway، الإصدار 2.5.x
يناقش هذا الموضوع كيفية إدارة وتهيئة Edge Microgateway.
ترقية Edge Microgateway إذا كان لديك اتصال بالإنترنت
- نفِّذ الأمر
npm
التالي للترقية إلى أحدث إصدار من Edge Microgateway:npm upgrade edgemicro -g
للترقية إلى إصدار معيّن من Edge Microgateway، يجب تحديد رقم الإصدار في أمر الترقية. إذا لم تحدّد رقم الإصدار، سيتم تثبيت أحدث إصدار. على سبيل المثال، للترقية إلى الإصدار 2.5.26، استخدِم الأمر التالي:
npm upgrade edgemicro@2.5.26 -g
- تحقَّق من رقم الإصدار. على سبيل المثال، في حال تثبيت الإصدار 2.5.26:
edgemicro --version current nodejs version is v8.9.0 current edgemicro version is 2.5.26
- وأخيرًا، عليك الترقية إلى أحدث إصدار من الخادم الوكيل edgemicro-auth:
edgemicro upgradeauth -o org_name -e env_name -u username
إجراء تغييرات على الإعدادات
تتضمن ملفات الضبط التي تحتاج إلى معرفتها ما يلي:
- ملف إعداد النظام التلقائي
- ملف الإعداد التلقائي لمثيل Edge Microgateway الذي تم إعداده حديثًا
- ملف الإعداد الديناميكي لمثيلات التشغيل
يناقش هذا القسم هذه الملفات وما تحتاج إلى معرفته حول تغييرها.
ملف إعداد النظام التلقائي
عند تثبيت Edge Microgateway، يتم وضع ملف إعداد نظام تلقائي هنا:
prefix/lib/node_modules/edgemicro/config/default.yaml
حيث يكون prefix هو دليل البادئة npm
. يمكنك الاطّلاع على القسم
أين يتم تثبيت Edge Microgateway إذا لم تتمكن من تحديد موقع هذا الدليل.
إذا غيّرت ملف إعداد النظام، يجب إعادة ضبط إعدادات متصفّح Edge Microgateway وإعادة ضبطه:
edgemicro initedgemicro configure [params]
edgemicro start [params]
ملف الإعداد التلقائي لمثيلات Edge Microgateway التي تم إعدادها حديثًا
عند تشغيل edgemicro init
، يتم وضع ملف إعداد النظام (الموضّح
أعلاه)، default.yaml
، في دليل ~/.edgemicro
.
إذا غيّرت ملف الإعداد في ~/.edgemicro
، يجب إعادة ضبط
Edge Microgateway وإعادة تشغيله:
edgemicro stopedgemicro configure [params]
edgemicro start [params]
ملف الإعداد الديناميكي لمثيلات التشغيل
عند تشغيل edgemicro configure [params]
، يتم إنشاء ملف إعداد ديناميكي في ~/.edgemicro
. تتم تسمية الملف وفقًا للنمط التالي: org-env-config.yaml
، حيث يشير org وenv إلى اسم مؤسستك والبيئة في Apigee Edge. يمكنك استخدام هذا الملف لإجراء تغييرات على الإعدادات، ثم إعادة تحميلها بدون أي وقت استراحة. على سبيل المثال، إذا أضفت مكونًا إضافيًا وقمت بإعداده، يمكنك إعادة تحميل التهيئة بدون التعرض لأي فترة توقف، كما هو موضح أدناه.
إذا كان Edge Microgateway قيد التشغيل (خيار وقت الاستراحة صفر):
- أعِد تحميل إعدادات Edge Microgateway:
edgemicro reload -o org_name -e env_name -k key -s secret
المكان:
- org_name هو اسم مؤسستك في Edge (يجب أن تكون مشرف مؤسسة).
- env_name هي بيئة في مؤسستك (مثل "test" أو "prod").
- key هو المفتاح الذي يعرضه أمر الضبط سابقًا.
- secret هو المفتاح الذي يعرضه أمر الضبط سابقًا.
على سبيل المثال:
edgemicro reload -o docs -e test -k 701e70ee718ce6dc188...78b6181d000723 \ -s 05c14356e42ed1...4e34ab0cc824
إذا تم إيقاف Edge Microgateway:
- أعِد تشغيل Edge Microgateway:
edgemicro start -o org_name -e env_name -k key -s secret
المكان:
- org_name هو اسم مؤسستك في Edge (يجب أن تكون مشرف مؤسسة).
- env_name هي بيئة في مؤسستك (مثل "test" أو "prod").
- key هو المفتاح الذي يعرضه أمر الضبط سابقًا.
- secret هو المفتاح الذي يعرضه أمر الضبط سابقًا.
مثال:
edgemicro start -o docs -e test -k 701e70ee718ce...b6181d000723 \ -s 05c1435...e34ab0cc824
وإليك مثال على ملف الإعداد. لمعرفة تفاصيل عن إعدادات ملف الإعداد، يُرجى الاطّلاع على مرجع ضبط Edge Microgateway.
edge_config: bootstrap: >- https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/docs/environment/test jwt_public_key: 'https://docs-test.apigee.net/edgemicro-auth/publicKey' managementUri: 'https://api.enterprise.apigee.com' vaultName: microgateway authUri: 'https://%s-%s.apigee.net/edgemicro-auth' baseUri: >- https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s bootstrapMessage: Please copy the following property to the edge micro agent config keySecretMessage: The following credentials are required to start edge micro products: 'https://docs-test.apigee.net/edgemicro-auth/products' edgemicro: port: 8000 max_connections: 1000 max_connections_hard: 5000 config_change_poll_interval: 600 logging: level: error dir: /var/tmp stats_log_interval: 60 rotate_interval: 24 plugins: sequence: - oauth headers: x-forwarded-for: true x-forwarded-host: true x-request-id: true x-response-time: true via: true oauth: allowNoAuthorization: false allowInvalidAuthorization: false verify_api_key_url: 'https://docs-test.apigee.net/edgemicro-auth/verifyApiKey' analytics: uri: >- https://edgemicroservices-us-east-1.apigee.net/edgemicro/axpublisher/organization/docs/environment/test
إعداد متغيرات البيئة
يمكن تخزين أوامر واجهة سطر الأوامر التي تتطلب قيمًا لتنظيم وإدارة Edge، والمفتاح والسر اللازمين لبدء تشغيل Edge Microgateway في متغيرات البيئة التالية:
EDGEMICRO_ORG
EDGEMICRO_ENV
EDGEMICRO_KEY
EDGEMICRO_SECRET
إنّ ضبط هذه المتغيّرات هو إجراء اختياري. وفي حال ضبطها، لن تضطر إلى تحديد قيمها عند استخدام واجهة سطر الأوامر (CLI) لضبط إعدادات Edge Microgateway وبدء تشغيلها.
ضبط طبقة المقابس الآمنة على خادم Edge Microgateway
يمكنك تهيئة خادم Microgateway لاستخدام طبقة المقابس الآمنة. على سبيل المثال، عند ضبط طبقة المقابس الآمنة، يمكنك استدعاء واجهات برمجة التطبيقات من خلال Edge Microgateway باستخدام بروتوكول "https" على النحو التالي:
https://localhost:8000/myapi
لتهيئة طبقة المقابس الآمنة على خادم Microgateway، اتبع الخطوات التالية:
- أنشئ شهادة ومفتاح طبقة المقابس الآمنة (SSL) أو احصل عليها باستخدام الأداة المساعدة openssl أو بأي طريقة تفضلها.
- أضِف السمة
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
- أعِد تشغيل 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
في ما يلي قائمة بجميع خيارات الخادم المتوافقة:
Option | الوصف |
---|---|
key |
المسار إلى ملف ca.key (بتنسيق PEM) |
cert |
المسار إلى ملف ca.cert (بتنسيق PEM) |
pfx |
مسار إلى ملف pfx يحتوي على المفتاح الخاص والشهادة وشهادات CA للعميل بتنسيق PFX. |
passphrase |
سلسلة تحتوي على عبارة المرور للمفتاح الخاص أو PFX. |
ca |
مسار إلى ملف يحتوي على قائمة بالشهادات الموثوق بها بتنسيق PEM. |
ciphers |
سلسلة تصف الرموز المطلوب استخدامها مفصولة بعلامة ":". |
rejectUnauthorized |
إذا كانت true، يتم التحقق من شهادة الخادم من خلال قائمة مراجع التصديق المُدخلة. وإذا تعذّر إثبات الملكية، سيظهر خطأ. |
secureProtocol |
طريقة طبقة المقابس الآمنة (SSL) المستخدمة. على سبيل المثال، SSLv3_method لفرض طبقة المقابس الآمنة على الإصدار 3. |
servername |
اسم الخادم لإضافة بروتوكول أمان طبقة النقل (SNI) لطبقة النقل الآمنة. |
requestCert |
صحيح بالنسبة لطبقة المقابس الآمنة ثنائية الاتجاه، وخطأ لطبقة المقابس الآمنة أحادية الاتجاه |
استخدام خيارات طبقة المقابس الآمنة/بروتوكول أمان طبقة النقل (TLS) للعميل
يمكنك إعداد Edge Microgateway ليكون برنامج بروتوكول أمان طبقة النقل (TLS) أو طبقة المقابس الآمنة عند الاتصال بنقاط النهاية المستهدفة. في ملف إعداد Microgateway، استخدِم عنصر الاستهداف لضبط خيارات طبقة المقابس الآمنة/بروتوكول أمان طبقة النقل (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
في ما يلي قائمة بجميع خيارات البرامج المتوافقة:
Option | الوصف |
---|---|
pfx |
مسار إلى ملف pfx يحتوي على المفتاح الخاص والشهادة وشهادات CA للعميل بتنسيق PFX. |
key |
المسار إلى ملف ca.key (بتنسيق PEM) |
passphrase |
سلسلة تحتوي على عبارة المرور للمفتاح الخاص أو PFX. |
cert |
المسار إلى ملف ca.cert (بتنسيق PEM) |
ca |
مسار إلى ملف يحتوي على قائمة بالشهادات الموثوق بها بتنسيق PEM. |
ciphers |
سلسلة تصف الرموز المطلوب استخدامها مفصولة بعلامة ":". |
rejectUnauthorized |
إذا كانت true، يتم التحقق من شهادة الخادم من خلال قائمة مراجع التصديق المُدخلة. وإذا تعذّر إثبات الملكية، سيظهر خطأ. |
secureProtocol |
طريقة طبقة المقابس الآمنة (SSL) المستخدمة. على سبيل المثال، SSLv3_method لفرض طبقة المقابس الآمنة على الإصدار 3. |
servername |
اسم الخادم لإضافة بروتوكول أمان طبقة النقل (SNI) لطبقة النقل الآمنة. |
تخصيص الخادم الوكيل للمصادقة الصغيرة
بشكل تلقائي، يستخدم 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. يُنصح باستخدام مستوى المعلومات. وهو يسجّل جميع طلبات واستجابات واجهة برمجة التطبيقات، وهو الإعداد التلقائي.
كيفية تغيير الفواصل الزمنية للسجلات
يمكنك تهيئة هذه الفواصل الزمنية في ملف تهيئة 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. يتم أيضًا تسجيل عدّادات واجهة برمجة التطبيقات (stats) والأخطاء في هذا الملف.
- 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
لمحة عن محتوى ملف السجلّ
تمت الإضافة في: v2.3.3
تحذف خدمة التسجيل تلقائيًا ملف JSON للخوادم الوكيلة التي تم تنزيلها والمنتجات ورمز JSON
للويب المميّز (JWT). إذا كنت تريد إخراج هذه العناصر إلى ملفات السجلّ، اضبط
DEBUG=*
عند بدء تشغيل Edge Microgateway. مثال:
DEBUG=* edgemicro start -o docs -e test -k abc123 -s xyz456
محتويات ملف سجل "واجهة برمجة التطبيقات"
يحتوي ملف سجلّ "واجهة برمجة التطبيقات" على معلومات مفصّلة حول تدفق الطلبات والردود من خلال Edge Microgateway. تتم تسمية ملفات سجل "واجهة برمجة التطبيقات" على النحو التالي:
edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log
لكل طلب يتم إجراؤه على Edge Microgateway، يتم تسجيل أربعة أحداث في ملف سجلّ "واجهة برمجة التطبيقات":
- طلب وارد من العميل
- تم إرسال طلب صادر إلى الهدف
- ردّ وارد من المستخدِم المستهدَف
- رد صادر إلى العميل
ويتم تمثيل كل من هذه الإدخالات المنفصلة في شكل اختصار للمساعدة في جعل ملفات السجل أكثر دقّة. فيما يلي أربعة نماذج إدخالات تمثل كل من الأحداث الأربعة. في ملف السجلّ، تظهر على النحو التالي (تكون أرقام الأسطر كمرجع في المستند فقط، ولا تظهر في ملف السجلّ).
(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 - طابع تاريخ Unix
- info: يعتمد على السياق. يمكن أن تكون معلومات أو تحذير أو خطأ، بناءً على مستوى السجلّ. يمكن أن تكون إحصاءات لسجلّ الإحصاءات، أو تحذير في حال توفّر تحذيرات، أو عند رصد أخطاء.
- req - لتحديد الحدث. في هذه الحالة، يمكنك الطلب من العميل.
- m - فعل HTTP المستخدَم في الطلب.
- u - الجزء الذي يلي المسار الأساسي في عنوان URL.
- 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 - طابع تاريخ Unix
- info: يعتمد على السياق. يمكن أن تكون معلومات أو تحذير أو خطأ، بناءً على مستوى السجلّ. يمكن أن تكون إحصاءات لسجلّ الإحصاءات، أو تحذير في حال توفّر تحذيرات، أو عند رصد أخطاء.
- treq - لتحديد الحدث. وفي هذه الحالة، يمكنك استهداف الطلب.
- m - فعل HTTP المستخدَم في الطلب المستهدف.
- u - الجزء الذي يلي المسار الأساسي في عنوان URL.
- h - المضيف ورقم المنفذ لهدف الخلفية.
- i - رقم تعريف إدخال السجلّ وستشارك جميع إدخالات الفعاليات الأربعة هذا المعرّف.
3. نموذج للردود الواردة من المجموعة المستهدَفة
1436403888672 info tres s=200, d=7, i=0
1436403888651 - طابع تاريخ Unix
- info: يعتمد على السياق. يمكن أن تكون معلومات أو تحذير أو خطأ، بناءً على مستوى السجلّ. يمكن أن تكون إحصاءات لسجلّ الإحصاءات، أو تحذير في حال توفّر تحذيرات، أو عند رصد أخطاء.
- tres - لتحديد الحدث. في هذه الحالة، الاستجابة المستهدفة.
- s - حالة استجابة HTTP
- d - المدة بالميلي ثانية الوقت المستغرَق في طلب البيانات من واجهة برمجة التطبيقات حسب الهدف.
- i - رقم تعريف إدخال السجلّ وستشارك جميع إدخالات الفعاليات الأربعة هذا المعرّف.
4. نموذج رد صادر للعميل
1436403888676 info res s=200, d=11, i=0
1436403888651 - طابع تاريخ Unix
- info: يعتمد على السياق. يمكن أن تكون معلومات أو تحذير أو خطأ، بناءً على مستوى السجلّ. يمكن أن تكون إحصاءات لسجلّ الإحصاءات، أو تحذير في حال توفّر تحذيرات، أو عند رصد أخطاء.
- res - لتحديد الحدث. في هذه الحالة، الردّ على العميل.
- s - حالة استجابة HTTP
- d - المدة بالميلي ثانية هذا هو إجمالي الوقت الذي يستغرقه طلب البيانات من واجهة برمجة التطبيقات، بما في ذلك الوقت الذي تستغرقه واجهة برمجة التطبيقات المستهدَفة والوقت الذي يستغرقه برنامج Edge Microgateway.
- i - رقم تعريف إدخال السجلّ وستشارك جميع إدخالات الفعاليات الأربعة هذا المعرّف.
الجدول الزمني لملف السجلّ
يتم تدوير ملفات السجلّ حسب الفاصل الزمني الذي تحدّده سمة الإعدادات rotate_interval. ستستمر إضافة الإدخالات إلى ملف السجلّ نفسه إلى أن تنتهي صلاحية الفاصل الزمني للتناوب. ومع ذلك، في كل مرة تتم فيها إعادة تشغيل Edge Microgateway، يتلقى النظام معرِّفًا فريدًا (UID) جديدًا وينشئ مجموعة جديدة من ملفات السجل باستخدام المعرِّف الفريد هذا. راجِع أيضًا الممارسات الجيدة لصيانة ملفات السجلّ.
رسائل الخطأ
ستحتوي بعض إدخالات السجلّ على رسائل خطأ. للمساعدة في تحديد مكان حدوث الأخطاء وسبب حدوثها، يمكنك الاطّلاع على مرجع أخطاء 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 setup. راجِع إعداد Edge Microgateway وضبطه للحصول على التفاصيل.
سمات Edgemicro
تعمل هذه الإعدادات على تهيئة عملية 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.
-
تسجيل الدخول:
-
level: (تلقائي: خطأ)
- info: لتسجيل جميع الطلبات والردود التي تتدفق من خلال مثيل Edge Microgateway.
- warn - لتسجيل رسائل التحذير فقط.
- error - لتسجيل رسائل الخطأ فقط.
- dir: (تلقائي: /var/tmp) الدليل الذي يتم تخزين ملفات السجل فيه.
- stats_log_interval: (الإعداد التلقائي: 60) الفاصل الزمني بالثواني، عندما تتم كتابة سجلّ الإحصاءات في ملف سجلّ واجهة برمجة التطبيقات.
- rotate_interval: (الإعداد التلقائي: 24) الفاصل الزمني بالساعات عندما يتم تدوير ملفات السجلّ.
-
level: (تلقائي: خطأ)
- المكوّنات الإضافية: تضيف المكوّنات الإضافية وظائف إلى Edge Microgateway. للحصول على تفاصيل حول تطوير المكوّنات الإضافية، يُرجى الاطّلاع على تطوير المكوّنات الإضافية المخصّصة.
- dir: مسار نسبي من دليل ./gateway إلى الدليل ./Plugins أو مسار مطلق.
- التسلسل: قائمة بوحدات المكوّنات الإضافية لإضافتها إلى مثيل Edge Microgateway. سيتم تنفيذ الوحدات بالترتيب المحدَّد هنا.
-
تصحيح الأخطاء: لإضافة تصحيح الأخطاء عن بُعد إلى عملية Edge Microgateway.
- port: رقم المنفذ المطلوب الاستماع إليه على سبيل المثال، يمكنك ضبط برنامج تصحيح أخطاء IDE للاستماع عبر هذا المنفذ.
- args: الوسيطات لعملية تصحيح الأخطاء. مثلاً:
args --nolazy
- config_change_poll_interval: (الإعداد التلقائي: 600 ثانية) تُحمِّل Edge Microgateway إعدادات جديدة بشكل دوري وتنفِّذ عملية إعادة تحميل في حال حدوث أي تغيير. يرصد الاستطلاع أي تغييرات تم إجراؤها على Edge (التغييرات على المنتجات، والخوادم الوكيلة الواعية للبوابة الصغيرة، وغير ذلك)، بالإضافة إلى
التغييرات التي يتم إجراؤها على ملف الإعداد على الجهاز.
- disable_config_poll_interval: (تلقائي: خطأ) اضبط القيمة على true على إيقاف الاستطلاع التلقائي للتغييرات.
- request_timeout: لضبط مهلة للطلبات المستهدفة. يتم ضبط المهلة بالثواني. في حالة انتهاء المهلة، يستجيب Edge Microgateway برمز الحالة 504. (تمت إضافة الإصدار 2.4.x)
سمات العناوين
تحدد هذه الإعدادات كيفية التعامل مع عناوين HTTP معينة.
- x-forwarded-for: (تلقائي: true) يتم الضبط على "خطأ" لمنع تمرير العناوين x-forwarded-for إلى الهدف. تجدر الإشارة إلى أنّه إذا تضمّن الطلب عنوان x-مُعاد توجيهه، سيتم ضبط قيمته على قيمة client-ip في إحصاءات Edge.
- x-forwarded-host: (تلقائي: true) يتم ضبطها على "خطأ" لمنع تمرير عناوين x-forwarded-host إلى الهدف.
- x-request-id: (تلقائي: true) يتم الضبط على "خطأ" لمنع تمرير عناوين x-request-id إلى الهدف.
- x-response-time: (تلقائي: true) يتم ضبطه على "خطأ" لمنع تمرير عناوين x-response-time إلى الهدف.
- via: (default: true) يتم الضبط على "خطأ" لمنع تمرير العناوين إلى الهدف.
سمات OAuth
تضبط هذه الإعدادات كيفية فرض مصادقة العميل من خلال Edge Microgateway.
- allowNoAuthorization: (تلقائي: خطأ) في حال ضبط هذه السياسة على "صحيح"، سيتم السماح بتمرير طلبات البيانات من واجهة برمجة التطبيقات عبر Edge Microgateway بدون أي عنوان تفويض على الإطلاق. ويمكنك ضبط هذا الإعداد على "خطأ" لطلب عنوان تفويض (تلقائي).
- allowInvalidAuthorization: (تلقائي: false) في حال ضبطها على "صحيح"، يتم السماح بتمرير طلبات البيانات من واجهة برمجة التطبيقات إذا كان الرمز المميّز الذي تم تمريره في عنوان التفويض غير صالح أو منتهي الصلاحية. اضبط هذه السمة على "خطأ" لطلب رموز مميزة صالحة (الخيار التلقائي).
- Authorize-header: (الإعداد التلقائي: التفويض: الحامل) هو العنوان المستخدَم لإرسال رمز الدخول إلى Edge Microgateway. وقد تحتاج إلى تغيير الإعداد التلقائي في الحالات التي يحتاج فيها الهدف إلى استخدام عنوان التفويض لغرض آخر.
- api-key-header: (تلقائي: x-api-key) اسم العنوان أو مَعلمة طلب البحث المستخدَمة لتمرير مفتاح واجهة برمجة تطبيقات إلى Edge Microgateway. راجِع أيضًا استخدام مفتاح واجهة برمجة التطبيقات.
- keep-تفويض-header: (الإعداد التلقائي: خطأ) في حال ضبط هذه السياسة على "صحيح"، يتم تمرير رأس التفويض المُرسَل في الطلب إلى الهدف (يتم الاحتفاظ به).
- allowOAuthOnly -- في حال ضبط هذه السياسة على "true"، يجب أن تتضمن كل واجهة برمجة تطبيقات عنوان تفويض مع رمز دخول الحامل المميز. يسمح لك هذا الخيار بالسماح بنموذج أمان OAuth فقط (مع الحفاظ على التوافق مع الأنظمة القديمة). (تمت إضافة 2.4.x)
- allowAPIKeyOnly: في حال ضبط السياسة على "صحيح"، يجب أن تتضمّن كل واجهة برمجة تطبيقات عنوان x-api-key (أو موقعًا مخصّصًا) مع مفتاح واجهة برمجة التطبيقات.ويسمح لك هذا الإجراء بالسماح بنموذج أمان مفتاح واجهة برمجة التطبيقات فقط (مع الحفاظ على التوافق مع الأنظمة القديمة). (تمت إضافة الإصدار 2.4.x)
- gracePeriod: تساعد هذه المَعلمة في منع الأخطاء الناتجة عن الاختلافات الطفيفة بين ساعة النظام ووقتَي "لم قبل" (nbf) أو "تم الإصدار في" (iat) المحدّد في الرمز المميّز لتفويض JWT. اضبط هذه المَعلمة على عدد الثواني للسماح بظهور هذا النوع من الاختلافات. (تمت إضافة 2.5.7)
السمات الخاصة بالمكوِّن الإضافي
راجِع استخدام المكوّنات الإضافية للحصول على تفاصيل عن السمات القابلة للضبط لكل مكوِّن إضافي.
فلترة الخوادم الوكيلة
يمكنك تصفية أي الخوادم الوكيلة الواعية ببوابة صغيرة سيعالجها مثيل Edge Microgateway.
عند بدء تشغيل Edge Microgateway، نزِّل جميع الخوادم الوكيلة الواعية للبوابة الصغيرة في المؤسسة
المرتبطة بها. استخدِم الإعدادات التالية لتحديد الخوادم الوكيلة التي ستتم معالجتها من خلال البوابة الصغيرة. على سبيل المثال، تفرض هذه الإعدادات قيودًا على الخوادم الوكيلة التي ستعالجها البوابة المصغّرة إلى ثلاثة: edgemicro_proxy-1
وedgemicro_proxy-2
وedgemicro_proxy-3
:
proxies: - edgemicro_proxy-1 - edgemicro_proxy-2 - edgemicro_proxy-3
ضبط معدل تكرار إرسال البيانات في "إحصاءات Google"
استخدِم مَعلمات الإعداد هذه للتحكّم في معدّل تكرار إرسال Edge Microgateway لبيانات الإحصاءات إلى Apigee:
- bufferSize (اختياري): الحد الأقصى لعدد سجلات التحليلات التي يمكن أن يحتفظ بها المخزن المؤقت قبل البدء في إسقاط السجلات الأقدم. القيمة التلقائية: 10,000
- batchSize (اختيارية): الحد الأقصى لحجم دفعة سجلات الإحصاءات المرسلة إلى Apigee. القيمة التلقائية: 500
- flushInterval (اختياري): عدد المللي ثانية بين كل دفعة من سجلات التحليلات المرسلة إلى Apigee. القيمة التلقائية: 5,000
مثال:
analytics: bufferSize: 15000 batchSize: 1000 flushInterval: 6000
إخفاء بيانات الإحصاءات
تمنع الإعدادات التالية ظهور معلومات مسار الطلب في إحصاءات Edge. أضِف ما يلي إلى إعدادات البوابة المصغّرة لإخفاء معرّف الموارد المنتظم (URI) للطلب و/أو مسار الطلب. تجدر الإشارة إلى أنّ معرّف الموارد المنتظم (URI) يتكون من اسم المضيف وأجزاء المسار للطلب.
analytics: mask_request_uri: 'string_to_mask' mask_request_path: 'string_to_mask'
تقسيم طلبات البيانات من واجهة برمجة التطبيقات في "إحصاءات Edge"
يمكنك إعداد المكوّن الإضافي للإحصاءات لفصل مسار محدّد لواجهة برمجة التطبيقات بحيث يظهر كخادم وكيل منفصل في لوحات بيانات Edge Analytics. على سبيل المثال، يمكنك فصل واجهة برمجة تطبيقات التحقّق من الصحة في لوحة البيانات لتجنّب الخلط بينها وبين الطلبات الفعلية للخادم الوكيل لواجهة برمجة التطبيقات. في لوحة بيانات "إحصاءات Google"، تتّبع الخوادم الوكيلة المجزّأة نمط التسمية التالي:
edgemicro_proxyname-health
تعرض الصورة التالية خادمَين وكيلَين منفصلَين في لوحة بيانات "إحصاءات Google": edgemicro_hello-health
وedgemicro_mock-health
:
استخدِم هذه المَعلمات لفصل المسارات النسبية والمطلقة في لوحة بيانات "إحصاءات Google" كخوادم وكيلة منفصلة:
- relativePath (اختيارية): تحدّد مسارًا نسبيًا للفصل بينها في لوحة بيانات "إحصاءات Google". على سبيل المثال، إذا حددت
/healthcheck
، ستظهر جميع طلبات البيانات من واجهة برمجة التطبيقات التي تحتوي على المسار/healthcheck
في لوحة البيانات على أنّهاedgemicro_proxyname-health
. لاحظ أن هذه العلامة تتجاهل المسار الأساسي للخادم الوكيل. للفصل بينها استنادًا إلى مسار كامل، بما في ذلك المسار الأساسي، استخدِم العلامةproxyPath
. - proxyPath (اختياري): يحدّد مسار الخادم الوكيل لواجهة برمجة التطبيقات الكامل، بما في ذلك المسار الأساسي للخادم الوكيل، للفصل بينه في لوحة بيانات الإحصاءات. على سبيل المثال، إذا حدّدت
/mocktarget/healthcheck
، حيث يكون/mocktarget
هو المسار الأساسي للخادم الوكيل، ستظهر جميع طلبات البيانات من واجهة برمجة التطبيقات التي تتضمّن المسار/mocktarget/healthcheck
في لوحة البيانات على أنّهاedgemicro_proxyname-health
.
على سبيل المثال، في الإعدادات التالية، سيتم فصل أي مسار لواجهة برمجة التطبيقات يحتوي على /healthcheck
بواسطة المكوّن الإضافي لخدمة "إحصاءات Google". وهذا يعني أنّه سيتم الفصل بين /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 وراء جدار حماية للشركة
الإصدار 2.4.x المتوافق
في حال تثبيت Edge Microgateway خلف جدار حماية، قد لا يتمكّن البوابة من الاتصال بـ Apigee Edge. في هذه الحالة، هناك خياران يمكنك وضعهما في الاعتبار:
الخيار 1:
الخيار الأول هو ضبط خيار Edgemicro: Proxy_tunnel على "صحيح" في ملف الإعداد microgateway:
edge_config: proxy: http://10.224.16.85:3128 proxy_tunnel: true
عندما تكون قيمة proxy_tunnel صحيحة، يستخدم Edge Microgateway طريقة HTTP CONNECT لتطبيق طلبات HTTP عبر اتصال TCP واحد. (وينطبق الأمر نفسه إذا تم تفعيل بروتوكول أمان طبقة النقل (TLS) في متغيرات البيئة لإعداد الخادم الوكيل).
الخيار 2:
الخيار الثاني هو تحديد خادم وكيل وضبط client_tunnel على "خطأ" في ملف إعداد microgateway. مثال:
edge_config: proxy: http://10.224.16.85:3128 proxy_tunnel: false
في هذه الحالة، يمكنك ضبط المتغيرات التالية للتحكم في المضيفين لكل خادم وكيل HTTP تريد استخدامه، أو المضيفين الذين يجب ألا يتعاملوا مع الخوادم الوكيلة لـ Edge Microgateway: HTTP_PROXY وHTTPS_PROXY وNO_PROXY.
يمكنك ضبط NO_PROXY كقائمة بالنطاقات المفصولة بفواصل من النطاقات التي يجب ألا يستخدمها Edge Microgateway. مثال:
export NO_PROXY='localhost,localhost:8080'
يمكنك ضبط HTTP_PROXY وHTTPS_PROXY على بروتوكول HTTP الوكيل لنقطة النهاية للسماح باستخدام Microgateway لإرسال رسائل إليه. مثال:
export HTTP_PROXY='http://localhost:3786' export HTTPS_PROXY='https://localhost:3786'
لمزيد من المعلومات عن هذه المتغيّرات، يُرجى الاطّلاع على https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables
يمكن أيضًا مراجعة
كيفية إعداد Edge Microgateway وراء جدار حماية للشركة على منتدى Apigee
استخدام أحرف البدل في الخوادم الوكيلة الواعية بـ Microgateway
يمكنك استخدام حرف بدل "*" واحد أو أكثر في المسار الأساسي للخادم الوكيل edgemicro_* (Microgateway-aware). على سبيل المثال، يتيح المسار الأساسي
/team/*/members للعملاء الاتصال
https://[host]/team/blue/members
وhttps://[host]/team/green/members بدون الحاجة إلى إنشاء خوادم وكيلة جديدة لواجهة برمجة التطبيقات
لدعم الفِرق الجديدة. يُرجى العلم أنّ "/**/
" غير متاحة.
ملاحظة مهمّة: لا تتيح Apigee استخدام حرف بدل "*"
كعنصر أوّل في مسار أساسي. على سبيل المثال، هذه السمة غير متاحة: بحث /*/
.
تدوير مفاتيح JWT
في بعض الأحيان بعد إنشاء JWT من البداية، قد تحتاج إلى تغيير زوج المفاتيح العام/الخاص المُخزَّن في KVM المشفّر في Edge. وتُعرف عملية إنشاء مفتاحَي تشفير جديدَين باسم "تدوير المفاتيح".
كيفية استخدام Edge Microgateway لتقنية JWT
رمز JSON المميّز للويب (JWT) هو معيار للرمز المميز الموضح في RFC7519. يوفّر JWT طريقة لتوقيع مجموعة من المطالبات التي يمكن أن يتحقّق منها مستلِم JWT بشكل موثوق.
يستخدم Edge Microgateway رموز JWT كرموز مميزة للحامل للحفاظ على أمان OAuth. عند إنشاء رمز OAuth مميز لتطبيق Edge Microgateway، ستحصل على JWT مرة أخرى. يمكنك بعد ذلك استخدام JWT في عنوان التفويض لاستدعاءات واجهة برمجة التطبيقات. مثال:
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 باستخدام واجهة برمجة تطبيقات الإدارة:
curl -i -X POST "http://org-env.apigee.net/edgemicro-auth/token" \ -H "Content-Type: application/json" \ -d '{ "client_id": "your consumer key", "client_secret": "your consumer secret", "grant_type": "client_credentials" }'
المكان:
- org هو اسم مؤسستك في Edge (يجب أن تكون مشرف مؤسسة).
- env هي بيئة في مؤسستك (مثل "test" أو "prod").
- client_id هو رقم تعريف المستهلك في تطبيق المطوّر الذي أنشأته سابقًا.
- client_secret هو سر العميل في تطبيق المطوّر الذي أنشأته سابقًا.
ما هو تدوير المفتاح؟
في بعض الأحيان بعد إنشاء JWT من البداية، قد تحتاج إلى تغيير زوج المفاتيح العام/الخاص المُخزَّن في KVM المشفّر في Edge. وتُعرف عملية إنشاء مفتاحَي تشفير جديدَين باسم "تدوير المفاتيح". عند تدوير المفاتيح، يتم إنشاء زوج مفاتيح خاص/عام جديد وتخزينه في KVM "microgateway" في بيئة أو مؤسسة Apigee Edge. بالإضافة إلى ذلك، يتم الاحتفاظ بالمفتاح العام القديم مع قيمة رقم تعريف المفتاح الأصلي.
لإنشاء JWT، يستخدم Edge المعلومات المخزنة في KVM المشفّر. وتم إنشاء آلة KVM تسمى microgateway
وتعبئتها باستخدام المفاتيح عند ضبط إعدادات Edge Microgateway في البداية. تُستخدم المفاتيح الموجودة في KVM لتوقيع أداة JWT وتشفيرها.
تتضمن مفاتيح KVM ما يلي:
-
private_key: أحدث مفتاح خاص RSA تم إنشاؤه (تم إنشاؤه مؤخرًا) ويُستخدم لتوقيع مفاتيح JWT.
-
public_key - أحدث شهادة (تم إنشاؤها مؤخرًا) تُستخدم لإثبات صحة مفاتيح JWT الموقَّعة باستخدام special_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 v6.9.1 current edgemicro version is 2.5.7 password: Checking if private key exists in the KVM... Checking for certificate... Found Certificate Generating New key/cert pair... Extract new public key Key Rotation successfully completed!
تحدّد المعلَمة -k
رقم تعريف مفتاح (kid). ويُستخدم هذا المعرّف لمطابقة مفتاح محدّد.
تستخدم Edge Microgateway هذه القيمة للاختيار من بين مجموعة من المفاتيح أثناء تدوير المفاتيح. لمزيد من المعلومات، يمكنك الاطّلاع على القسم 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_". يمكنك تغيير هذا الخيار التلقائي لتنزيل الخوادم الوكيلة التي تتطابق أسماؤها مع نمط معيّن.
- افتح ملف إعداد Edge Micro:
~/.edgemicro/org-env-config.yaml
- أضِف عنصر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. ويكون هذا مفيدًا في تحديد المشاكل وحلّها وتصحيح الأخطاء في المكوّنات الإضافية المخصّصة.
- أعِد تشغيل Edge Microgateway في وضع تصحيح الأخطاء. لإجراء ذلك، أضِف
DEBUG=*
إلى بداية الأمرstart
. مثلاً:DEBUG=* edgemicro start -o myorg -e test -k db4e9e8a95aa7fabfdeacbb1169d0a8cbe42bec19c6b98129e02 -s 6e56af7c1b26dfe93dae78a735c8afc9796b077d105ae5618ce7ed
. - ابدأ تشغيل برنامج تصحيح الأخطاء واضبطه للاستجابة إلى رقم المنفذ في عملية تصحيح الأخطاء.
- يمكنك الآن التنقّل بين رمز Edge Microgateway وضبط نقاط الإيقاف وتعبيرات المشاهدة وغير ذلك.
يمكنك تحديد علامات Node.js القياسية المرتبطة بوضع تصحيح الأخطاء. على سبيل المثال، يساعد --nolazy
في تصحيح أخطاء الرمز غير المتزامن.
جارٍ فحص ملفات السجلّ
إذا كنت تواجه مشاكل، يُرجى فحص ملفات السجلّ للحصول على تفاصيل التنفيذ ومعلومات الخطأ. لمعرفة التفاصيل، يُرجى الاطّلاع على إدارة ملفات السجلّ.
استخدام أمان مفتاح واجهة برمجة التطبيقات
توفر مفاتيح واجهة برمجة التطبيقات آلية بسيطة لمصادقة العملاء الذين يرسلون طلبات إلى Edge Microgateway. يمكنك الحصول على مفتاح واجهة برمجة التطبيقات من خلال نسخ قيمة مفتاح العميل (يسمى أيضًا Client ID) من منتج 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.
استخدام أمان الرمز المميز لبروتوكول OAuth2
يشرح هذا القسم كيفية الحصول على رموز الدخول عبر بروتوكول OAuth2 والرموز المميزة لإعادة التحميل. تُستخدم رموز الدخول لإجراء طلبات بيانات آمنة من واجهة برمجة التطبيقات عبر البوابة الصغيرة. تُستخدم الرموز المميّزة لإعادة التحميل للحصول على رموز دخول جديدة.
كيفية الحصول على رمز الدخول
يوضِّح هذا القسم كيفية استخدام الخادم الوكيل edgemicro-auth
للحصول على رمز دخول.
ويمكنك أيضًا الحصول على رمز دخول باستخدام أمر واجهة سطر الأوامر edgemicro token
(CLI).
لمعرفة التفاصيل حول واجهة سطر الأوامر، يُرجى الاطّلاع على إدارة الرموز المميّزة.
واجهة برمجة التطبيقات 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
(تمت الإضافة في الإصدار 2.5.31) أرسِل بيانات اعتماد العميل كعنوان مصادقة أساسية وgrant_type
كمَعلمة نموذج. وتتم أيضًا مناقشة نموذج الأمر هذا في RFC 6749: إطار عمل تفويض OAuth 2.0.
http://<org>-<test>.apigee.net/edgemicro-auth/token -v -u your_client_id:your_client_secret \ -d 'grant_type=client_credentials' -H "Content-Type: application/x-www-form-urlencoded"
نموذج المخرجات
تعرض واجهة برمجة التطبيقات استجابة JSON. يُرجى العِلم أنّه ما مِن فرق بين السمتَينtoken
وaccess_token
. يمكنك استخدام أي منهما.
{ "token": "eyJraWQiOiIxIiwidHlwIjoi", "access_token": "eyJraWQiOiIxIiwid", "token_type": "bearer", "expires_in": "108000" }
كيفية الحصول على الرمز المميز لإعادة التحميل
للحصول على الرمز المميّز لإعادة التحميل، يمكنك طلب بيانات من واجهة برمجة التطبيقات إلى نقطة النهاية /token
في الخادم الوكيل edgemicro-auth
. يجب إجراء طلب البيانات من واجهة برمجة التطبيقات هذا باستخدام
نوع المنحة password
. تخطَّ الخطوات التالية بالتفصيل.
- يمكنك الحصول على رمز الدخول وإعادة التحميل باستخدام واجهة برمجة التطبيقات
/token
API. يُرجى العلم بأنّ نوع المنحة هو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" }
- يمكنك الآن استخدام الرمز المميّز لإعادة التحميل للحصول على رمز دخول جديد عن طريق طلب نقطة النهاية
/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. للحصول على تفاصيل حول خيارات الضبط، يُرجى الرجوع إلى مستندات ميزة "المراقبة الدائمة".
يتضمّن الأمر 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
لإيقاف التخزين المؤقت للبيانات في اتصالات بروتوكول التحكم بالنقل التي يستخدمها 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 وواجهة برمجة التطبيقات
- الحصة
- الإحصاءات
من ناحية أخرى، تعمل المكوّنات الإضافية المخصّصة وعمليات إيقاف التشغيل المفاجئ بشكل طبيعي، لأنّها لا
تتطلّب الاتصال بخدمة Apigee Edge. بالإضافة إلى ذلك، يتيح لك مكوّن إضافي جديد يُسمى extauth
السماح باستدعاءات واجهة برمجة التطبيقات إلى البوابة الصغيرة باستخدام JWT في الوضع المستقل.
تهيئة المدخل وبدء تشغيله
لتشغيل Edge Microgateway في الوضع المستقل:
- تأكَّد من تثبيت الإصدار 2.5.25 من Edge Microgateway أو إصدار أحدث. وإذا لم يكن الأمر كذلك، عليك تنفيذ الأمر التالي للترقية إلى أحدث إصدار:
npm install -g edgemicro
إذا كنت بحاجة إلى مساعدة، يُرجى الاطّلاع على تثبيت Edge Microgateway.
- أنشئ ملف إعداد باسم على النحو التالي:
$HOME/.edgemicro/
org_name-
env_name-config.yaml
مثال:
vi $HOME/.edgemicro/foo-bar-config.yaml
- الصِق الرمز التالي في الملف:
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
- تصدير متغيّر البيئة التالي بالقيمة "1":
export EDGEMICRO_LOCAL=1
- نفِّذ الأمر
start
التالي الذي توفّر فيه قيم لإنشاء مثيل للخادم الوكيل المحلي:edgemicro start -o org_name -e environment_name -a local_proxy_name \ -v local_proxy_version -t target_url -b base_path
المكان:
- your_org هو اسم "org" الذي استخدمته في اسم ملف الإعداد.
- your_environment هو اسم "env" الذي استخدمته في اسم ملف الإعداد.
- local_proxy_name هو اسم الخادم الوكيل المحلي الذي سيتم إنشاؤه. يمكنك استخدام أي اسم تريده.
- local_proxy_version هو رقم إصدار الخادم الوكيل.
- target_url هو عنوان URL لهدف الخادم الوكيل. (target هي الخدمة التي يطلبها الخادم الوكيل.)
- base_path هو المسار الأساسي للخادم الوكيل. ويجب أن تبدأ هذه القيمة بشرطة مائلة للأمام. بالنسبة إلى المسار الأساسي الجذر، حدِّد شرطة مائلة للأمام فقط، على سبيل المثال "/".
مثال:
edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
- اختبِر الإعدادات.
curl http://localhost:8000/echo { "error" : "missing_authorization" }
بما أنّ المكوِّن الإضافي
extauth
متوفّر في الملفfoo-bar-config.yaml
، ستظهر لك رسالة الخطأ "missing_authorized". يتحقّق هذا المكوّن الإضافي من صحة JWT التي يجب أن تكون متوفّرة في عنوان التفويض لطلب بيانات من واجهة برمجة التطبيقات. في القسم التالي، ستحصل على رمز JWT يسمح بمرور طلبات البيانات من واجهة برمجة التطبيقات بدون حدوث خطأ.
مثال: الحصول على رمز مميز للتفويض
يوضح المثال التالي كيفية الحصول على JWT من نقطة نهاية Edge Microgateway JWT على Apigee Edge (edgemicro-auth/jwkPublicKeys
).
يتم نشر نقطة النهاية هذه عند تنفيذ إعداد وإعداد عاديَين على Edge Microgateway.
للحصول على JWT من نقطة نهاية Apigee، يجب أولاً إجراء إعداد Edge Microgateway القياسي، وأن تكون متصلاً بالإنترنت. تستخدم نقطة نهاية Apigee هنا لأغراض خاصة فقط
وهي غير مطلوبة. إذا أردت، يمكنك استخدام نقطة نهاية أخرى لرمز JWT. في حال إجراء ذلك، سيكون عليك الحصول على اختبار JWT باستخدام واجهة برمجة التطبيقات المتوفّرة لنقطة النهاية هذه.
توضّح الخطوات التالية كيفية الحصول على رمز مميّز باستخدام نقطة نهاية edgemicro-auth/jwkPublicKeys
:
- يجب تنفيذ إعداد
وإعداد عادي من Edge Microgateway لنشر الخادم الوكيل
edgemicro-auth
في مؤسستك/بيئة عملك على Apigee Edge. إذا سبق لك تنفيذ هذه الخطوة، لن تحتاج إلى تكرارها. - إذا نشرت Edge Microgateway إلى Apigee Cloud، يجب أن تكون متصلاً بالإنترنت حتى تتمكن من الحصول على JWT من نقطة النهاية هذه.
-
إيقاف Edge Microgateway:
edgemicro stop
- في ملف الإعداد الذي أنشأته سابقًا (
$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'
-
أعِد تشغيل Edge Microgateway كما فعلت سابقًا، باستخدام أسماء org/env التي استخدمتها في اسم ملف الإعداد. مثلاً:
edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
-
احصل على رمز JWT من نقطة نهاية التفويض. بما أنّك تستخدم نقطة نهاية
edgemicro-auth/jwkPublicKeys
، يمكنك استخدام أمر CLI هذا:
يمكنك إنشاء 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
سر المستهلك من تطبيق مطوِّر برامج يتضمّن منتجًا يتضمّن الخادم الوكيلedgemicro-auth
.
يطلب هذا الأمر من Apigee Edge إنشاء رمز JWT يمكن استخدامه بعد ذلك للتحقّق من طلبات البيانات من واجهة برمجة التطبيقات.
راجِع أيضًا إنشاء رمز مميّز.اختبار الإعداد المستقل
لاختبار الإعدادات، يمكنك طلب واجهة برمجة التطبيقات مع إضافة الرمز المميّز في عنوان التفويض على النحو التالي:
curl http://localhost:8000/echo -H "Authorization: Bearer your_token
مثال:
curl http://localhost:8000/echo -H "Authorization: Bearer eyJraWQiOiIxIiwidHlwIjo...iryF3kwcDWNv7OQ"
مثال على الإخراج:
{ "headers":{ "user-agent":"curl/7.54.0", "accept":"*/*", "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP", "client_received_start_timestamp":"1535134472699", "x-authorization-claims":"eyJhdDbiO...M1OTE5MTA1NDkifQ==", "target_sent_start_timestamp":"1535134472702", "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896", "x-forwarded-proto":"http", "x-forwarded-host":"localhost:8000", "host":"mocktarget.apigee.net", "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513", "via":"1.1 localhost, 1.1 google", "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212", "connection":"Keep-Alive" }, "method":"GET", "url":"/", "body":"" }
استخدام وضع الخادم الوكيل المحلي
في وضع الخادم الوكيل المحلي، لا يتطلب Edge Microgateway تفعيل خادم وكيل microgateway-aware على Apigee Edge. بدلاً من ذلك، يمكنك ضبط "خادم وكيل محلي" من خلال توفير اسم خادم وكيل محلي ومسار أساسي وعنوان URL مستهدف عند بدء تشغيل البوابة الصغيرة. ثم يتم إرسال استدعاءات واجهة برمجة التطبيقات إلى البوابة الصغيرة إلى عنوان URL المستهدف للخادم الوكيل المحلي. من جميع الجوانب الأخرى، يعمل وضع الخادم الوكيل المحلي تمامًا مثل تشغيل Edge Microgateway في الوضع العادي. تعمل المصادقة بالطريقة نفسها، تمامًا مثل الإيقاف المؤقت وفرض الحصص والمكوّنات الإضافية المخصّصة، وما إلى ذلك.
حالة الاستخدام والمثال
يكون وضع الخادم الوكيل المحلي مفيدًا عندما تحتاج فقط إلى ربط خادم وكيل واحد بمثيل Edge Microgateway. على سبيل المثال، يمكنك إدخال Edge Microgateway في Kubernetes كخادم وكيل جانبي، حيث يتم تشغيل كل من طريق مصغّر وخدمة في مجموعة واحدة، وحيث تدير البوابة الصغيرة حركة المرور من وإلى الخدمة التابعة لها. يوضِّح الشكل التالي هذه البنية حيث يعمل برنامج Edge Microgateway كوكيل جانبي في مجموعة Kubernetes. يتحدث كل مثيل بوابة صغيرة فقط إلى نقطة نهاية واحدة على الخدمة المصاحبة له:
تتمثل إحدى فوائد هذا النمط من التصاميم في أنّ Edge Microgateway يوفّر إدارة واجهة برمجة التطبيقات للخدمات الفردية التي يتم نشرها في بيئة حاوية، مثل مجموعة Kubernetes.
تكوين وضع الخادم الوكيل المحلي
لتكوين إعدادات Edge Microgateway للتشغيل في وضع الخادم الوكيل المحلي، اتبع الخطوات التالية:
- تأكَّد من تثبيت الإصدار 2.5.25 من Edge Microgateway أو إصدار أحدث. وإذا لم يكن الأمر كذلك، عليك تنفيذ الأمر التالي للترقية إلى أحدث إصدار:
npm install -g edgemicro
إذا كنت بحاجة إلى مساعدة، يُرجى الاطّلاع على تثبيت Edge Microgateway.
- شغِّل
edgemicro init
لإعداد بيئة الإعداد المحلية، تمامًا كما تفعل في إعداد Edge Microgateway العادي. راجِع أيضًا ضبط إعدادات Edge Microgateway. - شغِّل
edgemicro configure
، كما تفعل في أي إجراء إعداد Edge Microgateway العادي. مثلاً:edgemicro configure -o your_org -e your_env -u your_apigee_username
ينشر هذا الأمر سياسة edgemicro-auth على Edge ويعرض مفتاحًا ومفتاحًا سريًا ستحتاج إليهما لبدء تشغيل البوابة الصغيرة. إذا كنت بحاجة إلى مساعدة، يُرجى الاطّلاع على ضبط Edge Microgateway.
- في Apigee Edge، أنشِئ منتجًا لواجهة برمجة تطبيقات يتضمّن متطلبات الضبط الإلزامية التالية (يمكنك إدارة جميع الإعدادات الأخرى كما تريد):
- عليك إضافة الخادم الوكيل edgemicro-auth إلى المنتج. تم تفعيل هذا الخادم الوكيل تلقائيًا عند تشغيل
edgemicro configure
. - عليك توفير مسار للمورد. تنصح Apigee بإضافة هذا المسار إلى
المنتج:
/**
. لمعرفة المزيد من المعلومات، راجِع ضبط سلوك مسار المورد. اطّلِع أيضًا على إنشاء منتجات واجهة برمجة التطبيقات في مستندات Edge.
- عليك إضافة الخادم الوكيل edgemicro-auth إلى المنتج. تم تفعيل هذا الخادم الوكيل تلقائيًا عند تشغيل
في Apigee Edge، يمكنك إنشاء مطوّر برامج أو يمكنك استخدام مطوّر حالي إذا أردت ذلك. للحصول على المساعدة، اطلع على إضافة مطوّري البرامج باستخدام واجهة مستخدم إدارة Edge.
- في Apigee Edge، أنشئ تطبيقًا لمطوّر البرامج. عليك إضافة منتج واجهة برمجة التطبيقات الذي أنشأته للتو إلى التطبيق. للحصول على المساعدة، راجع تسجيل تطبيق في واجهة مستخدم إدارة Edge.
- على الجهاز الذي تم تثبيت Edge Microgateway عليه، يمكنك تصدير متغيّر البيئة التالي بالقيمة "1".
export EDGEMICRO_LOCAL_PROXY=1
- نفِّذ أمر
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":"" }