يتم الآن عرض مستندات Apigee Edge.
انتقِل إلى مستندات
Apigee X. المعلومات
Edge Microgateway، الإصدار 3.2.x
يناقش هذا الموضوع كيفية إدارة وتهيئة Edge Microgateway.
ترقية Edge Microgateway إذا كان لديك اتصال بالإنترنت
يوضّح هذا القسم كيفية ترقية تثبيت حالي لـ Edge Microgateway. إذا كان الجهاز يعمل بدون اتصال بالإنترنت، يُرجى الاطّلاع على المقالة هل يمكنني تثبيت Edge Microgateway بدون الاتصال بالإنترنت؟.
تنصح Apigee باختبار الإعدادات الحالية باستخدام الإصدار الجديد قبل ترقية بيئة الإنتاج.
- نفِّذ الأمر
npm
التالي للترقية إلى أحدث إصدار من Edge Microgateway:npm upgrade edgemicro -g
لتثبيت إصدار معيّن من Edge Microgateway، عليك تحديد رقم الإصدار في أمر التثبيت. على سبيل المثال، لتثبيت الإصدار 3.2.3، استخدِم الأمر التالي:
npm install edgemicro@3.2.3 -g
- تحقَّق من رقم الإصدار. على سبيل المثال، في حال تثبيت الإصدار 3.2.3:
edgemicro --version current nodejs version is v12.5.0 current edgemicro version is 3.2.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 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 -e $ENV -k $KEY -s $SECRET
المكان:
- $ORG هو اسم مؤسستك في Edge (يجب أن تكون مشرف مؤسسة).
- $ENV هي بيئة في مؤسستك (مثل "test" أو "prod").
- $KEY هو المفتاح الذي يعرضه أمر الضبط سابقًا.
- $SECRET هو المفتاح الذي يعرضه أمر الضبط سابقًا.
على سبيل المثال:
edgemicro reload -o docs -e test -k 701e70ee718ce6dc188...78b6181d000723 \ -s 05c14356e42ed1...4e34ab0cc824
إذا تم إيقاف Edge Microgateway:
- أعِد تشغيل Edge Microgateway:
edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET
المكان:
- $ORG هو اسم مؤسستك في Edge (يجب أن تكون مشرف مؤسسة).
- $ENV هي بيئة في مؤسستك (مثل "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
شاهِد الفيديوهات التالية لمعرفة المزيد عن ضبط بروتوكول أمان طبقة النقل (TLS) في Apigee Edge Microgateway:
حملة فيديو | الوصف |
---|---|
إعداد بروتوكول أمان طبقة النقل (TLS) شمال الاتجاه باتجاه واحد | تعرَّف على كيفية ضبط بروتوكول أمان طبقة النقل (TLS) في Apigee Edge Microgateway. يقدّم هذا الفيديو نظرة عامة على بروتوكول أمان طبقة النقل (TLS) وأهميته، ويشرح بروتوكول أمان طبقة النقل (TLS) في Edge Microgateway، ويوضِّح كيفية ضبط بروتوكول أمان طبقة النقل (TLS) أحادي الاتجاه. |
إعداد بروتوكول أمان طبقة النقل (TLS) الثنائي الاتجاه نحو الشمال | هذا هو الفيديو الثاني حول ضبط بروتوكول أمان طبقة النقل (TLS) في Apigee Edge Microgateway. يوضّح هذا الفيديو كيفية ضبط بروتوكول أمان طبقة النقل (TLS) ثنائي الاتجاه باتجاه الشمال. |
ضبط بروتوكول أمان طبقة النقل (TLS) ثنائي الاتجاه والثنائي الاتجاه إلى الجنوب | يوضّح هذا الفيديو الثالث حول ضبط بروتوكول أمان طبقة النقل (TLS) في Apigee Edge Microgateway طريقة ضبط بروتوكول أمان طبقة النقل (TLS) الأحادي الاتجاه والاتجاهَين باتجاه الجنوب. |
يمكنك تهيئة خادم 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
إذا أردت تطبيق إعدادات بروتوكول أمان طبقة النقل أو طبقة المقابس الآمنة على عدة أهداف محدّدة، يجب تحديد المضيف الأول في الإعدادات على "فارغ"، ما يتيح الطلبات العامة، ثم تحديد مضيفات معيّنة بأي ترتيب. في هذا المثال، يتم تطبيق الإعدادات على عدة مضيفين محددين:
targets: - host: ## Note that this value must be "empty" ssl: client: key: /Users/myname/twowayssl/ssl/client.key cert: /Users/myname/twowayssl/ssl/ca.crt passphrase: admin123 rejectUnauthorized: true - host: 'myserver1.example.com' ssl: client: key: /Users/myname/twowayssl/ssl/client.key cert: /Users/myname/twowayssl/ssl/ca.crt rejectUnauthorized: true - host: 'myserver2.example.com' ssl: client: key: /Users/myname/twowayssl/ssl/client.key cert: /Users/myname/twowayssl/ssl/ca.crt 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 وملف السجلّ.
كيفية ضبط مستوى التسجيل
عليك تحديد مستوى السجلّ المطلوب استخدامه في إعدادات edgemicro
. للحصول على
قائمة كاملة بمستويات السجلّ وأوصافها، يمكنك الاطّلاع على سمات edgemicro.
على سبيل المثال، تضبط عملية الضبط التالية مستوى التسجيل على debug
:
edgemicro: home: ../gateway port: 8000 max_connections: -1 max_connections_hard: -1 logging: level: debug dir: /var/tmp stats_log_interval: 60 rotate_interval: 24
كيفية تغيير الفواصل الزمنية للسجلات
يمكنك تهيئة هذه الفواصل الزمنية في ملف تهيئة 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
كيفية تخفيف الأذونات الصارمة لملف السجلّ
ينشئ Edge Microgateway تلقائيًا ملف سجلّ التطبيق (api-log.log
) مع ضبط مستوى إذن الملف
على 0600. لا يسمح مستوى الإذن هذا للتطبيقات أو المستخدمين الخارجيين بقراءة ملف السجلّ. لتخفيف مستوى الأذونات الصارمة هذا، يجب ضبط logging:disableStrictLogFile
على true
. عندما تكون هذه السمة true
، يتم إنشاء ملف السجلّ مع ضبط إذن الملف على 0755. إذا false
أو إذا لم يتم توفير السمة، يتم ضبط الإذن تلقائيًا على 0600.
تمت إضافتها في الإصدار 3.2.3.
مثال:
edgemicro: logging: disableStrictLogFile: true
ممارسات جيدة لصيانة ملفات السجلات
مع تراكم بيانات ملف السجلّ بمرور الوقت، تنصح Apigee باتّباع الممارسات التالية:
- بما أنّ حجم ملفات السجلّ يمكن أن يصبح كبيرًا جدًا، تأكَّد من توفّر مساحة كافية في دليل ملف السجلّ. راجِع القسمَين التاليَين مكان تخزين ملفات السجلّ وكيفية تغيير الدليل التلقائي لملف السجلّ.
- احذف ملفات السجلّ أو انقلها إلى دليل أرشيف منفصل مرة واحدة على الأقل في الأسبوع.
- إذا كانت سياستك تنص على حذف السجلات، يمكنك استخدام أمر واجهة سطر الأوامر
edgemicro log -c
لإزالة السجلات القديمة (تنظيف).
اصطلاح تسمية ملف السجل
ينتج عن كل مثيل Edge Microgateway ملف سجلّ بامتداد .log
. ويكون اصطلاح تسمية ملفات السجل كما يلي:
edgemicro-HOST_NAME-INSTANCE_ID-api.log
مثال:
edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.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 - مستوى التسجيل. تعتمد هذه القيمة على سياق المعاملة ومستوى التسجيل المضبوط في إعدادات
edgemicro
. راجِع كيفية ضبط مستوى التسجيل. بالنسبة إلى سجلّات الإحصاءات، يتم ضبط المستوى علىstats
. يتم إعداد تقارير الإحصاءات على فترات زمنية منتظمة يتم ضبطها وفقًا لإعداداتstats_log_interval
. يمكنك الاطّلاع أيضًا على كيفية تغيير الفواصل الزمنية للسجلات. - 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 - مستوى التسجيل. تعتمد هذه القيمة على سياق المعاملة ومستوى التسجيل المضبوط في إعدادات
edgemicro
. راجِع كيفية ضبط مستوى التسجيل. بالنسبة إلى سجلّات الإحصاءات، يتم ضبط المستوى علىstats
. يتم إعداد تقارير الإحصاءات على فترات زمنية منتظمة يتم ضبطها وفقًا لإعداداتstats_log_interval
. يمكنك الاطّلاع أيضًا على كيفية تغيير الفواصل الزمنية للسجلات. - treq - لتحديد الحدث. وفي هذه الحالة، يمكنك استهداف الطلب.
- m - فعل HTTP المستخدَم في الطلب المستهدف.
- u - الجزء الذي يلي المسار الأساسي في عنوان URL.
- h - المضيف ورقم المنفذ لهدف الخلفية.
- i - رقم تعريف إدخال السجلّ وستشارك جميع إدخالات الفعاليات الأربعة هذا المعرّف.
3. نموذج للردود الواردة من المجموعة المستهدَفة
1436403888672 info tres s=200, d=7, i=0
1436403888651 - طابع تاريخ Unix
- info - مستوى التسجيل. تعتمد هذه القيمة على سياق المعاملة ومستوى التسجيل المضبوط في إعدادات
edgemicro
. راجِع كيفية ضبط مستوى التسجيل. بالنسبة إلى سجلّات الإحصاءات، يتم ضبط المستوى علىstats
. يتم إعداد تقارير الإحصاءات على فترات زمنية منتظمة يتم ضبطها وفقًا لإعداداتstats_log_interval
. يمكنك الاطّلاع أيضًا على كيفية تغيير الفواصل الزمنية للسجلات. - tres - لتحديد الحدث. في هذه الحالة، الاستجابة المستهدفة.
- s - حالة استجابة HTTP
- d - المدة بالميلي ثانية الوقت المستغرَق في طلب البيانات من واجهة برمجة التطبيقات حسب الهدف.
- i - رقم تعريف إدخال السجلّ وستشارك جميع إدخالات الفعاليات الأربعة هذا المعرّف.
4. نموذج رد صادر للعميل
1436403888676 info res s=200, d=11, i=0
1436403888651 - طابع تاريخ Unix
- info - مستوى التسجيل. تعتمد هذه القيمة على سياق المعاملة ومستوى التسجيل المضبوط في إعدادات
edgemicro
. راجِع كيفية ضبط مستوى التسجيل. بالنسبة إلى سجلّات الإحصاءات، يتم ضبط المستوى علىstats
. يتم إعداد تقارير الإحصاءات على فترات زمنية منتظمة يتم ضبطها وفقًا لإعداداتstats_log_interval
. يمكنك الاطّلاع أيضًا على كيفية تغيير الفواصل الزمنية للسجلات. - 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 وضبطه للحصول على التفاصيل.
- quotaUri: يجب ضبط سمة
الضبط هذه إذا كنت تريد إدارة الحصص من خلال الخادم الوكيل
edgemicro-auth
الذي تم نشره في مؤسستك. وإذا لم يتم ضبط هذه السمة، يتم ضبط نقطة نهاية الحصة تلقائيًا على نقطة نهاية Edge Microgateway الداخلية.edge_config: quotaUri: https://your_org-your_env.apigee.net/edgemicro-auth
سمات 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 - لتسجيل رسائل الخطأ فقط.
- debug - سجلات تصحيح الأخطاء مع المعلومات، والتحذير، ورسائل الخطأ.
- trace - لتسجيل معلومات تتبّع الأخطاء مع المعلومات والتحذير ورسائل الخطأ.
- none - لا تنشئ ملف سجلّ.
- 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)
- keep_alive_timeout: تتيح لك هذه السمة ضبط مهلة Edge Microgateway (بالمللي ثانية). (الإعداد التلقائي: 5 ثوانٍ) (تمت إضافة الإصدار 3.0.6)
- headers_timeout: تحدِّد هذه السمة مقدار الوقت (بالمللي ثانية)
الذي سينتظره محلّل HTTP لكي يتلقّى
عناوين HTTP الكاملة.
مثال:
edgemicro: keep_alive_timeout: 6000 headers_timeout: 12000
داخليًا، تضبط المَعلمة سمة Node.js
Server.headersTimeout
في الطلبات. (القيمة التلقائية: 5 ثوانٍ أكثر من الوقت الذي تم ضبطه فيedgemicro.keep_alive_timeout
. يمنع هذا الإعداد التلقائي أجهزة موازنة التحميل أو الخوادم الوكيلة من إنهاء الاتصال عن طريق الخطأ). (تمت إضافة الإصدار 3.1.1) - noRuleMatchAction: (سلسلة) الإجراء المطلوب اتخاذه (السماح بالوصول أو رفضه) إذا
لم يتم حل قاعدة المطابقة المحددة في المكون الإضافي
accesscontrol
(غير متطابق). القيم الصالحة:ALLOW
أوDENY
القيمة التلقائية:ALLOW
(تمت الإضافة: الإصدار 3.1.7) - enableAnalytics: (تلقائي: true) اضبط السمة على false لمنع
تحميل المكوّن الإضافي الخاص بالإحصاءات. في هذه الحالة، لن يتم طلب إحصاءات Apigee Edge. في حال ضبط هذه السمة على true أو عدم توفير هذه السمة، سيعمل المكوّن الإضافي للإحصاءات على النحو المعتاد. يمكنك الاطّلاع على سمات edgemicro لمعرفة التفاصيل. (تمت إضافة الإصدار 3.1.8).
مثال:
edgemicro enableAnalytics=false|true
- on_target_response_abort: تتيح لك هذه السمة التحكّم في طريقة عمل Edge Microgateway في حال إغلاق الاتصال بين العميل (Edge Microgateway) والخادم الهدف قبل أوانه.
القيمة الوصف تلقائي وإذا لم يتم تحديد السمة on_target_response_abort
، يكون السلوك التلقائي هو اقتطاع الاستجابة بدون عرض أي خطأ. في ملفات السجلّ، يتم عرض رسالة تحذير معtargetResponse aborted
ورمز الاستجابة 502.appendErrorToClientResponseBody
يتم عرض الخطأ المخصّص TargetResponseAborted
إلى العميل. في ملفات السجلّ، يتم عرض رسالة تحذير معtargetResponse aborted
ورمز الاستجابة 502. بالإضافة إلى ذلك، يتم تسجيل الخطأTargetResponseAborted
مع الرسالةTarget response ended prematurely.
abortClientRequest
يؤدي استخدام Edge Microgateway إلى إلغاء الطلب، وتتم كتابة تحذير في ملفات السجلّ: TargetResponseAborted
برمز حالة الطلب 502.
مثال:
edgemicro: on_target_response_abort: appendErrorToClientResponseBody | abortClientRequest
سمات العناوين
تحدد هذه الإعدادات كيفية التعامل مع عناوين 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
:
edgemicro: proxies: - edgemicro_proxy-1 - edgemicro_proxy-2 - edgemicro_proxy-3
فلترة المنتجات حسب الاسم
استخدِم الإعدادات التالية للحدّ من عدد منتجات واجهة برمجة التطبيقات التي ينزّلها Edge Microgateway ويعالجها. لفلترة المنتجات التي تم تنزيلها، أضِف مَعلمة طلب البحث productnamefilter
إلى واجهة برمجة التطبيقات /products
المدرَجة في ملف Edge Microgateway *.config.yaml
. مثال:
edge_config: bootstrap: >- https://edgemicroservices.apigee.net/edgemicro/bootstrap/organization/willwitman/environment/test jwt_public_key: 'https://myorg-test.apigee.net/edgemicro-auth/publicKey' managementUri: 'https://api.enterprise.apigee.com' vaultName: microgateway authUri: 'https://%s-%s.apigee.net/edgemicro-auth' baseUri: >- https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s bootstrapMessage: Please copy the following property to the edge micro agent config keySecretMessage: The following credentials are required to start edge micro products: 'https://myorg-test.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24'
يُرجى العِلم أنّه يجب تحديد قيمة معلَمة طلب البحث بتنسيق التعبير العادي
ويجب ترميزها في عنوان URL. على سبيل المثال، يلتقط التعبير العادي ^[Ee]dgemicro.*$
أسماءً مثل:
"edgemicro-test-1" و"edgemicro_demo" و "Edgemicro_New_Demo". قيمة عنوان URL المرمّزة، والمناسبة للاستخدام في مَعلمة طلب البحث، هي: %5E%5BEe%5Ddgemicro.%2A%24
.
توضِّح نتيجة تصحيح الأخطاء التالية أنّه تمّ تنزيل المنتجات التي تمّت فلترتها فقط:
... 2020-05-27T03:13:50.087Z [76060] [microgateway-config network] products download from https://gsc-demo-prod.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24 returned 200 OK ... .... .... { "apiProduct":[ { "apiResources":[ ], "approvalType":"auto", "attributes":[ { "name":"access", "value":"public" } ], "createdAt":1590549037549, "createdBy":"k***@g********m", "displayName":"test upper case in name", "environments":[ "prod", "test" ], "lastModifiedAt":1590549037549, "lastModifiedBy":"k***@g********m", "name":"Edgemicro_New_Demo", "proxies":[ "catchall" ], "quota":"null", "quotaInterval":"null", "quotaTimeUnit":"null", "scopes":[ ] }, { "apiResources":[ ], "approvalType":"auto", "attributes":[ { "name":"access", "value":"public" } ], "createdAt":1590548328998, "createdBy":"k***@g********m", "displayName":"edgemicro test 1", "environments":[ "prod", "test" ], "lastModifiedAt":1590548328998, "lastModifiedBy":"k***@g********m", "name":"edgemicro-test-1", "proxies":[ "Lets-Encrypt-Validation-DoNotDelete" ], "quota":"null", "quotaInterval":"null", "quotaTimeUnit":"null", "scopes":[ ] }, { "apiResources":[ "/", "/**" ], "approvalType":"auto", "attributes":[ { "name":"access", "value":"public" } ], "createdAt":1558182193472, "createdBy":"m*********@g********m", "displayName":"Edge microgateway demo product", "environments":[ "prod", "test" ], "lastModifiedAt":1569077897465, "lastModifiedBy":"m*********@g********m", "name":"edgemicro_demo", "proxies":[ "edgemicro-auth", "edgemicro_hello" ], "quota":"600", "quotaInterval":"1", "quotaTimeUnit":"minute", "scopes":[ ] } ] }
فلترة المنتجات حسب السمات المخصّصة
لفلترة المنتجات استنادًا إلى السمات المخصّصة:
- في واجهة مستخدم Edge، اختَر الخادم الوكيل edgemicro_auth في المؤسسة أو البيئة التي ضبطت فيها Edge Microgateway.
- ضمن النقر على "تطوير"، افتح سياسة JavaCallout في المحرِّر.
- أضِف سمة مخصّصة باستخدام المفتاح
products.filter.attributes
مع قائمة بأسماء السمات مفصولة بفواصل. ولن يتم إرجاع سوى المنتجات التي تحتوي على أي من أسماء السمات المخصّصة إلى Edge Microgateway. - يمكنك اختياريًا إيقاف علامة الاختيار
لمعرفة ما إذا كان المنتج مفعّلاً في البيئة الحالية من خلال ضبط
السمة المخصّصة
products.filter.env.enable
علىfalse
. (القيمة التلقائية هي true.) - (السحابة الإلكترونية الخاصة فقط) إذا كنت تستخدم Edge لخدمة Private Cloud، اضبط السمة
org.noncps
علىtrue
لسحب المنتجات لبيئات غير مستندة إلى CPS.
مثال:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout"> <DisplayName>JavaCallout</DisplayName> <FaultRules/> <Properties> <Property name="products.filter.attributes">attrib.one, attrib.two</Property> <Property name="products.filter.env.enable">false</Property> <Property name="org.noncps">true</Property> </Properties> <ClassName>io.apigee.microgateway.javacallout.Callout</ClassName> <ResourceURL>java://micro-gateway-products-javacallout-2.0.0.jar</ResourceURL> </JavaCallout>
ضبط معدل تكرار إرسال البيانات في "إحصاءات 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 وراء جدار حماية للشركة
استخدام خادم وكيل HTTP للاتصال بخدمة Apigee Edge
تمت إضافتها في الإصدار 3.1.2.
لاستخدام وكيل HTTP للاتصال بين Edge Microgateway وApigee Edge، اتّبِع الخطوات التالية:
- اضبط متغيّرات البيئة
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
- أعِد تشغيل Edge Microgateway.
استخدام وكيل HTTP للاتصال المستهدف
تمت إضافتها في الإصدار 3.1.2.
لاستخدام وكيل HTTP للاتصال بين Edge Microgateway وأهداف الخلفية، يمكنك تنفيذ ما يلي:
- أضِف الإعدادات التالية إلى ملف الإعداد microgateway:
edgemicro: proxy: tunnel: true | false url: proxy_url bypass: target_host # target hosts to bypass the proxy. enabled: true | false
المكان:
- نفق: (اختياري) عند اختيار القيمة "true"، يستخدم Edge Microgateway طريقة HTTP CONNECT لتنفيذ طلبات HTTP عبر اتصال TCP واحد. (وينطبق ذلك أيضًا إذا تم تفعيل بروتوكول أمان طبقة النقل (TLS) في متغيرات البيئة كما هو موضّح أدناه. اللغة التلقائية:
false
- url: عنوان URL لخادم وكيل HTTP.
- bypass: (اختياري) تحدد هذه السمة عنوان URL واحدًا أو أكثر من عناوين URL للمضيف الهدف المفصول بفواصل والتي يجب أن تتجاوز الخادم الوكيل HTTP. في حال عدم ضبط هذه السمة، يمكنك استخدام متغيّر بيئة "NO_PROXY" لتحديد عناوين URL المستهدفة المطلوب استبعادها.
- مفعَّلة: في حال ضبط القيمة على "صحيح" وضبط
proxy.url
، استخدِم القيمةproxy.url
للخادم الوكيل HTTP. إذا كانت القيمة true ولم يتم ضبطproxy.url
، استخدِم الخوادم الوكيلة المحدّدة في متغيّرَي بيئة الخادم الوكيل HTTPHTTP_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
- نفق: (اختياري) عند اختيار القيمة "true"، يستخدم Edge Microgateway طريقة HTTP CONNECT لتنفيذ طلبات HTTP عبر اتصال TCP واحد. (وينطبق ذلك أيضًا إذا تم تفعيل بروتوكول أمان طبقة النقل (TLS) في متغيرات البيئة كما هو موضّح أدناه. اللغة التلقائية:
- أعِد تشغيل Edge Microgateway.
استخدام أحرف البدل في الخوادم الوكيلة الواعية بـ 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 بشكل موثوق.
يمكنك إنشاء JWT باستخدام واجهة سطر الأوامر واستخدامه في عنوان التفويض لاستدعاءات واجهة برمجة التطبيقات بدلاً من مفتاح واجهة برمجة التطبيقات. مثال:
curl -i http://localhost:8000/hello -H "Authorization: Bearer eyJhbGciOiJ..dXDefZEA"
لمزيد من المعلومات حول إنشاء نماذج JWT باستخدام واجهة سطر الأوامر، يمكنك الاطّلاع على مقالة إنشاء رمز مميّز.
ما هو تدوير المفتاح؟
في بعض الأحيان بعد إنشاء 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 المقدمة لإثبات الملكية باستخدام المفتاح العام الجديد. وفي حال تعذُّر عملية إثبات الملكية، سيتم استخدام المفتاح العام القديم إلى أن تنتهي صلاحية JWT (بعد الفاصل الزمني icon_expiry*، وهو الإعداد التلقائي لمدة 30 دقيقة). وبهذه الطريقة، يمكنك "تدوير" المفاتيح بدون التأثير فورًا في عدد زيارات واجهة برمجة التطبيقات.
كيفية تغيير المفاتيح
يوضّح هذا القسم كيفية تغيير المفاتيح.
- لترقية KVM، استخدِم الأمر
edgemicro upgradekvm
. ولمزيد من التفاصيل حول تشغيل هذا الأمر، راجِع ترقية KVM. ما عليك سوى تنفيذ هذه الخطوة مرة واحدة فقط. - لترقية الخادم الوكيل edgemicro-oauth، استخدِم الأمر
edgemicro upgradeauth
. للحصول على تفاصيل حول تشغيل هذا الأمر، يمكنك الاطّلاع على ترقية الخادم الوكيل Edgemicro-auth. ما عليك سوى تنفيذ هذه الخطوة مرة واحدة فقط. - أضِف السطر التالي إلى ملف
~/.edgemicro/org-env-config.yaml
، حيث يجب تحديد المؤسسة والبيئة نفسيهما اللتين تم ضبطهما لاستخدام البوابة الصغيرة:jwk_public_keys: 'https://$ORG-$ENV.apigee.net/edgemicro-auth/jwkPublicKeys'
نفِّذ أمر تدوير المفاتيح لتدوير المفاتيح. لمعرفة التفاصيل حول هذا الطلب، راجِع تدوير المفاتيح.
edgemicro rotatekey -o $ORG -e $ENV -k $KEY -s $SECRET
مثال:
edgemicro rotatekey -o docs -e test \ -k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \ -s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47
بعد تدوير المفاتيح، يُرجع 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" } ] }
تهيئة مهلة "ليس قبل"
بالنسبة إلى الإصدارات 3.1.5 والإصدارات الأقدم، أصبح المفتاح الخاص الجديد الذي أنشأه الأمر rotatekey
ساريًا على الفور وتم توقيع الرموز المميّزة الجديدة التي تم إنشاؤها باستخدام المفتاح الخاص الجديد. ومع ذلك،
كان المفتاح العام الجديد متاحًا فقط لمثيلات Edge Microgateway كل 10 دقائق (تلقائيًا)
عندما تمت إعادة تحميل إعدادات البوابة الصغيرة. وبسبب هذه الفجوة بين توقيع الرمز المميّز وإعادة تحميل مثيل البوابة المصغَّرة، سيتم رفض الرموز المميّزة الموقَّعة بأحدث مفتاح إلى أن تتلقّى جميع الحالات الأخرى أحدث مفتاح علني.
وفي الحالات التي تتضمّن عدة مثيلات للمدخل الصغير، يؤدي تأخُّر المفتاح العام أحيانًا إلى حدوث أخطاء متقطّعة في وقت التشغيل بالحالة 403، وذلك لأنّ عملية التحقق من الرمز المميّز تتم في مثيل واحد ولكنها تفشل في مثيل آخر إلى أن تتم إعادة تحميل جميع المثيلات.
بدءًا من الإصدار 3.1.6، تسمح لك علامة جديدة في الأمر rotatekey
بتحديد مهلة لكي يصبح المفتاح الخاص الجديد فعّالاً، ما يمنح وقتًا حتى تتم إعادة تحميل جميع مثيلات البوابة الصغيرة
وتتلقّى المفتاح العام الجديد. العلم الجديد هو --nbf
، ويعني ذلك أنه "لم يسبق له مثيل".
وتتطلّب هذه العلامة قيمة عدد صحيح، وهي عدد الدقائق المطلوب تأخيرها.
وفي المثال التالي، يتم تعيين التأخير على 15 دقيقة:
edgemicro rotatekey -o docs -e test \ -k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \ -s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47 \ --nbf 15
يُرجى العِلم أنّه من الممارسات الجيدة ضبط مدة التأخير لتكون أكبر من إعدادات ضبط config_change_poll_internal
، التي تكون 10 دقائق تلقائيًا. اطّلِع أيضًا على سمات edgemicro.
فلترة الخوادم الوكيلة التي تم تنزيلها
ينزّل 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 $ORG -e $ENV -k $KEY -s $SECRET
في نظام التشغيل Windows.لتوجيه نتائج تصحيح الأخطاء إلى ملف، يمكنك استخدام الأمر التالي:
export DEBUG=* nohup edgemicro start \ -o $ORG -e $ENV -k $KEY -s $SECRET 2>&1 | tee /tmp/file.log
- ابدأ تشغيل برنامج تصحيح الأخطاء واضبطه للاستجابة إلى رقم المنفذ في عملية تصحيح الأخطاء.
- يمكنك الآن التنقّل بين رمز 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.
تفعيل رموز الاستجابة قبل استلام البيانات
لا يعرض المكوِّن الإضافي 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
(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: إرسال بيانات الاعتماد في عنوان مصادقة أساسي
أرسِل بيانات اعتماد العميل كعنوان للمصادقة الأساسية
و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
. يمكنك استخدام أي منهما. تجدر الإشارة إلى أنّ expires_in
هي قيمة عدد صحيح محدّدة بالثواني.
{ "token": "eyJraWQiOiIxIiwidHlwIjoi", "access_token": "eyJraWQiOiIxIiwid", "token_type": "bearer", "expires_in": 1799 }
كيفية الحصول على الرمز المميز لإعادة التحميل
للحصول على الرمز المميّز لإعادة التحميل، يمكنك طلب بيانات من واجهة برمجة التطبيقات إلى نقطة النهاية /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" }'
تعرض واجهة برمجة التطبيقات رمز الدخول ورمزًا مميزًا لإعادة التحميل. يكون الردّ شبيهًا بهذا. تجدر الإشارة إلى أنّ السمة
expires_in
تقدِّر الأعداد الصحيحة ويتم تحديدها بالثواني.{ "token": "your-access-token", "access_token": "your-access-token", "token_type": "bearer", "expires_in": 108, "refresh_token": "your-refresh-token", "refresh_token_expires_in": 431, "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 في الوضع المستقل:
- أنشئ ملف إعداد بالاسم التالي:
$HOME/.edgemicro/$ORG
-
$ENV-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 -e $ENV -a $LOCAL_PROXY_NAME \ -v $LOCAL_PROXY_VERSION -t $TARGET_URL -b $BASE_PATH
المكان:
- $ORG هو اسم "org" الذي استخدمته في اسم ملف الإعداد.
- $ENV هو اسم "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 للتشغيل في وضع الخادم الوكيل المحلي، اتبع الخطوات التالية:
- شغِّل
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":"" }
استخدام المزامنة
يشرح هذا القسم طريقة استخدام أداة المزامنة، وهي ميزة اختيارية تحسّن مرونة برنامج Edge Microgteway من خلال السماح لها باسترداد بيانات الإعدادات من Apigee Edge وكتابتها في قاعدة بيانات Redis المحلية. أثناء تشغيل مثيل المزامنة، يمكن لمثيلات Edge Microgateway الأخرى التي تعمل على عُقد مختلفة استرداد الإعدادات مباشرةً من قاعدة البيانات هذه.
ميزة المزامنة متوافقة حاليًا للعمل مع Redis 5.0.x.
ما المقصود بالمزامنة؟
يوفر المتزامن مستوى من المرونة لـ Edge Microgateway. يساعد هذا النظام في ضمان استخدام الإعدادات نفسها في كل مثيل من Edge Microgateway، وأنه في حال انقطاع الاتصال بالإنترنت، يمكن بدء تشغيل مثيلات Edge Microgateway وتشغيلها بشكل صحيح.
بشكل تلقائي، يجب أن تتمكّن مثيلات Edge Microgateway من الاتصال بخدمة Apigee Edge لاسترداد بيانات الإعدادات وإعادة تحميلها، مثل الخادم الوكيل لواجهة برمجة التطبيقات وإعدادات منتجات واجهة برمجة التطبيقات. إذا انقطع اتصال الإنترنت مع Edge، يمكن أن تستمر أمثلة البوابة المصغّرة في العمل، لأنّ أحدث بيانات الإعدادات يتم تخزينها مؤقتًا. في المقابل، لا يمكن أن تبدأ مثيلات البوابة الصغيرة الجديدة بدون اتصال واضح. بالإضافة إلى ذلك، من الممكن أن يؤدي انقطاع الإنترنت إلى تشغيل مثيل واحد أو أكثر من أمثلة البوابة المصغّرة بمعلومات إعداد غير متزامنة مع الحالات الأخرى.
وتوفّر أداة مزامنة Edge Microgateway آلية بديلة عن مثيلات Edge Microgateway
لاسترداد بيانات الضبط المطلوبة لبدء ومعالجة عدد زيارات الخادم الوكيل لواجهة برمجة التطبيقات.
تشمل بيانات الإعدادات التي تم استردادها من الطلبات إلى Apigee Edge ما يلي: طلب jwk_public_keys
، وطلب jwt_public_key
، وطلب بدء تشغيل المنتج، وطلب منتجات واجهة برمجة التطبيقات.
ومن خلال المزامِن، يمكن تشغيل جميع مثيلات 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
Option | الوصف |
---|---|
redisHost |
المضيف الذي يتم تشغيل مثيل Redis عليه. الإعدادات التلقائية: 127.0.0.1 |
redisPort |
منفذ مثيل Redis القيمة التلقائية: 6379 |
redisDb |
Redis DB المراد استخدامها. القيمة التلقائية: 0 |
redisPassword |
كلمة مرور قاعدة البيانات |
وأخيرًا، احفظ ملف الإعداد وابدأ تشغيل مثيل 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
خصائص الإعداد
تمت إضافة خصائص الإعداد التالية لإتاحة استخدام المزامن:
السمة | القيم | الوصف |
---|---|---|
edge_config.synchronizerMode |
0 أو 1 | إذا كان 0 (الطريقة التلقائية) تعمل Edge Microgateway في الوضع العادي. إذا كانت القيمة 1، ابدأ تشغيل مثيل Edge Microgateway للعمل كمتزامن. في هذا الوضع، سيسحب المثيل بيانات الإعدادات من Apigee Edge ويخزّنها في قاعدة بيانات Redis المحلية. يتعذّر على هذا المثيل معالجة طلبات الخادم الوكيل لواجهة برمجة التطبيقات، والغرض منه الوحيد هو استطلاع Apigee Edge لبيانات الإعداد وكتابتها في قاعدة البيانات المحلية. يجب عليك بعد ذلك تكوين مثيلات أخرى للبوابة المصغرة لقراءتها من قاعدة البيانات. |
edge_config.redisBasedConfigCache |
صواب أم خطأ | إذا كانت القيمة "true"، يجلب مثيل Edge Microgateway بيانات الضبط الخاصة به من
قاعدة بيانات Redis بدلاً من Apigee Edge. ويجب أن تكون قاعدة بيانات Redis هي نفسها التي تم ضبط المزامنة فيها للكتابة إليها. إذا كانت قاعدة بيانات Redis غير متاحة أو
إذا كانت قاعدة البيانات فارغة، تبحث البوابة المصغّرة عن ملف cache-config.yaml
حالي لضبطها.
إذا كانت القيمة "خطأ" (الخيار التلقائي)، يجلب مثيل Edge Microgateway بيانات الإعدادات من Apigee Edge كالمعتاد. |
edgemicro.config_change_poll_interval |
الفاصل الزمني، بالثواني | تحدِّد هذه السياسة الفاصل الزمني للاستطلاع لسحب البيانات من Apigee Edge. |
ضبط استبعاد عناوين URL للمكوّنات الإضافية
يمكنك ضبط البوابة الصغيرة لتخطّي معالجة المكوّنات الإضافية لعناوين URL محدّدة. ويمكنك ضبط عناوين URL "لاستبعاد" عناوين URL هذه على مستوى العالم (لجميع المكوّنات الإضافية) أو لمكوِّنات إضافية محدّدة.
مثال:
... edgemicro: ... plugins: excludeUrls: '/hello,/proxy_one' # global exclude urls sequence: - oauth - json2xml - quota json2xml: excludeUrls: '/hello/xml' # plugin level exclude urls ...
في هذا المثال، لن تعالج المكوّنات الإضافية الطلبات الواردة من الخادم الوكيل لواجهة برمجة التطبيقات مع المسار /hello
أو /proxy_one
. بالإضافة إلى ذلك، سيتم تخطّي المكوّن الإضافي json2xml
لواجهات برمجة التطبيقات التي تتضمّن /hello/xml
في مسارها.
إعداد سمات الضبط باستخدام قيم متغيرات البيئة
يمكنك تحديد متغيرات البيئة باستخدام علامات في ملف الإعداد. ويتم استبدال علامات متغير البيئة المحدّدة بقيم متغير البيئة الفعلية. يتم تخزين البدائل في الذاكرة فقط، ولا يتم تخزينها في الإعدادات الأصلية أو ملفات ذاكرة التخزين المؤقت.
في هذا المثال، يتم استبدال السمة key
بقيمة
متغيّر بيئة TARGETS_SSL_CLIENT_KEY
، وهكذا.
targets: - ssl: client: key: <E>TARGETS_SSL_CLIENT_KEY</E> cert: <E>TARGETS_SSL_CLIENT_CERT</E> passphrase: <E>TARGETS_SSL_CLIENT_PASSPHRASE</E>
في هذا المثال، يتم استخدام العلامة <n>
للإشارة إلى قيمة عدد صحيح. يُسمح فقط
بالأرقام الصحيحة الموجبة.
edgemicro: port: <E><n>EMG_PORT</n></E>
في هذا المثال، يتم استخدام العلامة <b>
للإشارة إلى قيمة منطقية (أي صواب أو خطأ).
quotas: useRedis: <E><b>EMG_USE_REDIS</b></E>