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

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

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

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

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

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

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

    npm upgrade edgemicro@2.5.26 -g
  2. تحقَّق من رقم الإصدار. على سبيل المثال، إذا ثبّت الإصدار 2.5.26: 
    edgemicro --version
current nodejs version is v8.9.0
current edgemicro version is 2.5.26
  3. أخيرًا، عليك الترقية إلى أحدث إصدار من الخادم الوكيل edgemicro-auth: 
    edgemicro upgradeauth -o org_name -e env_name -u username

إجراء تغييرات على الإعدادات

تشمل ملفات الإعداد التي تحتاج إلى معرفتها ما يلي:

  • ملف إعداد النظام التلقائي
  • ملف الإعداد التلقائي لمثيل Edge Microgateway الذي تم إعداده حديثًا
  • ملف الإعداد الديناميكي للمثيلات قيد التشغيل

يتناول هذا القسم هذه الملفات وما تحتاج إلى معرفته حول تغييرها.

ملف الإعدادات التلقائية للنظام

عند تثبيت Edge Microgateway، يتم وضع ملف إعداد النظام التلقائي هنا:

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

حيث يمثّل prefix دليل البادئة npm. يُرجى الاطّلاع على مكان تثبيت Edge Microgateway إذا لم تتمكّن من تحديد موقع هذا الدليل.

في حال تغيير ملف إعداد النظام، يجب إعادة إعداد Edge Microgateway وإعادة ضبطه وإعادة تشغيله:

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

ملف الإعداد التلقائي لمثيلات Edge Microgateway التي تم إعدادها حديثًا

عند تشغيل edgemicro init، يتم وضع ملف إعداد النظام (الموضّح أعلاه)، default.yaml، في دليل ~/.edgemicro.

في حال تغيير ملف الإعداد في ~/.edgemicro، يجب إعادة ضبط Edge Microgateway وإعادة تشغيله:

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

ملف إعداد ديناميكي لتشغيل المثيلات

عند تشغيل edgemicro configure [params]، يتم إنشاء ملف إعداد ديناميكي في ~/.edgemicro. تتم تسمية الملف وفقًا لهذا النمط: org-env-config.yaml، حيث org وenv هما اسما مؤسستك وبيئتك في Apigee Edge. يمكنك استخدام هذا الملف لإجراء تغييرات في الإعدادات، ثم إعادة تحميلها بدون أي وقت توقّف. على سبيل المثال، إذا أضفت مكوّنًا إضافيًا وضبطته، يمكنك إعادة تحميل الإعدادات بدون أي فترة توقّف، كما هو موضّح أدناه.

إذا كان Edge Microgateway قيد التشغيل (خيار عدم التوقف عن العمل):

  1. أعِد تحميل إعدادات Edge Microgateway: 
    edgemicro reload -o org_name -e env_name -k key -s secret

    المكان:

    • ‫org_name هو اسم مؤسسة Edge (يجب أن تكون مشرفًا في المؤسسة).
    • ‫env_name هي بيئة في مؤسستك (مثل "test" أو "prod").
    • ‫key هو المفتاح الذي تم عرضه سابقًا من خلال أمر الضبط.
    • ‫secret هو المفتاح الذي تم عرضه سابقًا من خلال أمر الضبط.

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

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

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

  1. أعِد تشغيل Edge Microgateway: 
    edgemicro start -o org_name -e env_name -k key -s secret

    المكان:

    • ‫org_name هو اسم مؤسسة Edge (يجب أن تكون مشرفًا في المؤسسة).
    • ‫env_name هي بيئة في مؤسستك (مثل "اختبار" أو "إنتاج").
    • ‫key هو المفتاح الذي تم عرضه سابقًا من خلال أمر الضبط.
    • ‫secret هو المفتاح الذي تم عرضه سابقًا من خلال أمر الضبط.

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

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

في ما يلي مثال على ملف إعداد. للحصول على تفاصيل حول إعدادات ملف الإعداد، يُرجى الاطّلاع على مرجع إعدادات Edge Microgateway.

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

ضبط متغيرات البيئة

يمكن تخزين أوامر واجهة سطر الأوامر التي تتطلّب قيمًا لمؤسسة Edge وبيئتها، والمفتاح والرمز السري اللازمَين لبدء Edge Microgateway في متغيرات البيئة التالية:

  • EDGEMICRO_ORG
  • EDGEMICRO_ENV
  • EDGEMICRO_KEY
  • EDGEMICRO_SECRET

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

ضبط طبقة المقابس الآمنة (SSL) على خادم Edge Microgateway

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

https://localhost:8000/myapi

لضبط طبقة المقابس الآمنة على خادم Microgateway، اتّبِع الخطوات التالية:

  1. أنشئ شهادة ومفتاح طبقة المقابس الآمنة (SSL) أو احصل عليهما باستخدام أداة openssl أو أي طريقة تفضّلها.
  2. أضِف السمة edgemicro:ssl إلى ملف إعداد Edge Microgateway. للحصول على قائمة كاملة بالخيارات، يُرجى الاطّلاع على الجدول أدناه. مثال:
    edgemicro:
  ssl:
   key: <absolute path to the SSL key file>
   cert: <absolute path to the SSL cert file>
   passphrase: admin123 #option added in v2.2.2
   rejectUnauthorized: true #option added in v2.2.2
   requestCert: true
  3. أعِد تشغيل Edge Microgateway. اتّبِع الخطوات الموضّحة في مقالة إجراء تغييرات على الإعدادات استنادًا إلى ملف الإعدادات الذي عدّلته: الملف التلقائي أو ملف إعدادات وقت التشغيل.

في ما يلي مثال على قسم edgemicro في ملف الإعداد، مع ضبط طبقة المقابس الآمنة (SSL):

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

في ما يلي قائمة بجميع خيارات الخوادم المتوافقة:

Option الوصف
key المسار إلى ملف ca.key (بتنسيق PEM)
cert المسار إلى ملف ca.cert (بتنسيق PEM)
pfx المسار إلى ملف pfx يحتوي على المفتاح الخاص والشهادة وشهادات CA للعميل بتنسيق PFX
passphrase سلسلة تحتوي على عبارة المرور للمفتاح الخاص أو PFX.
ca يشير هذا الإعداد إلى المسار المؤدي إلى ملف يحتوي على قائمة بالشهادات الموثوق بها بتنسيق PEM.
ciphers سلسلة تصف الشفرات التي سيتم استخدامها مفصولة بـ ":".
rejectUnauthorized إذا تم ضبطها على "صحيح"، يتم التحقّق من شهادة الخادم من خلال مقارنتها بقائمة مراجع التصديق المقدَّمة. إذا تعذّر إثبات الهوية، سيتم عرض رسالة خطأ.
secureProtocol طريقة طبقة المقابس الآمنة (SSL) التي يجب استخدامها على سبيل المثال، SSLv3_method لفرض الإصدار 3 من طبقة المقابس الآمنة.
servername اسم الخادم لإضافة TLS الخاصة بـ SNI (إشارة اسم الخادم).
requestCert ‫true لطبقة المقابس الآمنة (SSL) الثنائية الاتجاه، وfalse لطبقة المقابس الآمنة (SSL) الأحادية الاتجاه

استخدام خيارات طبقة المقابس الآمنة (SSL)/بروتوكول أمان طبقة النقل (TLS) للعميل

يمكنك ضبط Edge Microgateway ليكون عميل بروتوكول أمان طبقة النقل (TLS) أو طبقة المقابس الآمنة (SSL) عند الاتصال بنقاط النهاية المستهدَفة. في ملف إعداد Microgateway، استخدِم عنصر الأهداف لضبط خيارات SSL/TLS.

يوفّر هذا المثال الإعدادات التي سيتم تطبيقها على جميع المضيفين:

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

في هذا المثال، يتم تطبيق الإعدادات على المضيف المحدّد فقط:

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

في ما يلي مثال على بروتوكول أمان طبقة النقل (TLS):

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

في ما يلي قائمة بجميع خيارات برامج البريد الإلكتروني المتوافقة:

Option الوصف
pfx المسار إلى ملف pfx يحتوي على المفتاح الخاص والشهادة وشهادات CA للعميل بتنسيق PFX
key المسار إلى ملف ca.key (بتنسيق PEM)
passphrase سلسلة تحتوي على عبارة المرور للمفتاح الخاص أو PFX.
cert المسار إلى ملف ca.cert (بتنسيق PEM)
ca يشير هذا الإعداد إلى المسار المؤدي إلى ملف يحتوي على قائمة بالشهادات الموثوق بها بتنسيق PEM.
ciphers سلسلة تصف الشفرات التي سيتم استخدامها مفصولة بـ ":".
rejectUnauthorized إذا تم ضبطها على "صحيح"، يتم التحقّق من شهادة الخادم من خلال مقارنتها بقائمة مراجع التصديق المقدَّمة. إذا تعذّر إثبات الهوية، سيتم عرض رسالة خطأ.
secureProtocol طريقة طبقة المقابس الآمنة (SSL) التي يجب استخدامها على سبيل المثال، SSLv3_method لفرض الإصدار 3 من طبقة المقابس الآمنة.
servername اسم الخادم لإضافة TLS الخاصة بـ SNI (إشارة اسم الخادم).

تخصيص الخادم الوكيل edgemicro-auth

يستخدم Edge Microgateway تلقائيًا خادمًا وكيلاً يتم نشره على Apigee Edge لمصادقة OAuth2. يتم نشر هذا الخادم الوكيل عند تشغيل edgemicro configure في البداية. يمكنك تغيير الإعدادات التلقائية لهذا الخادم الوكيل لإضافة إمكانية استخدام المطالبات المخصّصة في رمز JSON Web Token‏ (JWT)، وضبط انتهاء صلاحية الرموز المميزة، وإنشاء رموز مميزة لإعادة التحميل. لمعرفة التفاصيل، يُرجى الاطّلاع على صفحة edgemicro-auth في GitHub.

استخدام خدمة مصادقة مخصّصة

يستخدم Edge Microgateway تلقائيًا خادمًا وكيلاً يتم نشره على Apigee Edge لمصادقة OAuth2. يتم نشر هذا الخادم الوكيل عند تشغيل edgemicro configure في البداية. يتم تحديد عنوان 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 ويتم أيضًا تسجيل عدّادات واجهة برمجة التطبيقات (الإحصاءات) والأخطاء في هذا الملف.
  • ‫err: يسجّل أي بيانات يتم إرسالها إلى stderr.
  • out: يسجّل أي بيانات يتم إرسالها إلى stdout.

في ما يلي اصطلاح التسمية:

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

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

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

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

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

بشكل تلقائي، تحذف خدمة التسجيل ملف JSON الخاص بالخوادم الوكيلة والمنتجات التي تم تنزيلها ورمز JSON Web Token (JWT). إذا أردت إخراج هذه العناصر إلى ملفات السجلّ، اضبط DEBUG=* عند بدء Edge Microgateway. على سبيل المثال:

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

محتوى ملف سجلّ "api"

يحتوي ملف سجلّ "api" على معلومات تفصيلية حول تدفق الطلبات والردود من خلال Edge Microgateway. تتم تسمية ملفات سجلّ "api" على النحو التالي:

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

لكل طلب يتم إرساله إلى Edge Microgateway، يتم تسجيل أربعة أحداث في ملف سجلّ "api":

  • طلب وارد من العميل
  • تم إرسال طلب صادر إلى الهدف
  • الردّ الوارد من الهدف
  • الردّ الصادر إلى العميل

يتم تمثيل كل إدخال من هذه الإدخالات المنفصلة في تدوين مختصر للمساعدة في جعل ملفات السجلّ أكثر إيجازًا. في ما يلي أربعة إدخالات نموذجية تمثّل كل حدث من الأحداث الأربعة. في ملف السجلّ، تظهر هذه الأخطاء على النحو التالي (أرقام الأسطر هي فقط كمرجع في المستند، ولا تظهر في ملف السجلّ).

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

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

1. نموذج لطلب وارد من العميل:

1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
  • ‫1436403888651: طابع تاريخ Unix
  • ‫info: يعتمد على السياق. يمكن أن تكون معلومات أو تحذيرًا أو خطأ، حسب مستوى السجلّ. يمكن أن تكون stats لسجلّ الإحصاءات أو warn للتحذيرات أو error للأخطاء.
  • ‫req: لتحديد الحدث في هذه الحالة، اطلب من العميل.
  • ‫m: فعل HTTP المستخدَم في الطلب
  • u: الجزء من عنوان URL الذي يلي المسار الأساسي.
  • h: المضيف ورقم المنفذ اللذان يستمع إليهما Edge Microgateway.
  • r: المضيف البعيد والمنفذ اللذان صدر منهما طلب العميل
  • i: معرّف الطلب ستشارك جميع إدخالات الأحداث الأربعة هذا المعرّف. يتم تخصيص معرّف فريد لكل طلب. يمكن أن يوفّر ربط سجلّات السجلّات حسب معرّف الطلب إحصاءات قيّمة حول وقت استجابة الهدف.
  • ‫d: المدة بالملي ثانية منذ تلقّي Edge Microgateway الطلب في المثال أعلاه، تم تلقّي ردّ الهدف على الطلب 0 بعد 7 ملي ثانية (السطر 3)، وتم إرسال الردّ إلى العميل بعد 4 ملي ثانية إضافية (السطر 4). In other words, the total request latency was 11 milliseconds, out of which 7 milliseconds were taken by the target and 4 milliseconds by Edge Microgateway itself.

2. نموذج لطلب صادر تم إرساله إلى الهدف:

1436403888665 info treq m=GET, u=/, h=127.0.0.1:8080, i=0
  • ‫1436403888651: طابع تاريخ Unix
  • ‫info: يعتمد على السياق. يمكن أن تكون معلومات أو تحذيرًا أو خطأ، حسب مستوى السجلّ. يمكن أن تكون stats لسجلّ الإحصاءات أو warn للتحذيرات أو error للأخطاء.
  • ‫treq: لتحديد الحدث في هذه الحالة، الطلب المستهدف.
  • ‫m: فعل HTTP المستخدَم في الطلب المستهدَف
  • u: الجزء من عنوان URL الذي يلي المسار الأساسي.
  • ‫h: المضيف ورقم المنفذ للوجهة الخلفية
  • ‫i: معرّف الإدخال في السجلّ وستشارك جميع إدخالات الأحداث الأربعة رقم التعريف هذا.

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

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

‫1436403888651: طابع تاريخ Unix

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

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

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

‫1436403888651: طابع تاريخ Unix

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

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

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

رسائل الخطأ

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

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

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

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

سمات edge_config

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

  • ‫bootstrap: (الإعداد التلقائي: none) عنوان URL يشير إلى خدمة Edge Microgateway معيّنة تعمل على Apigee Edge. تستخدم Edge Microgateway هذه الخدمة للتواصل مع Apigee Edge. يتم عرض عنوان URL هذا عند تنفيذ الأمر لإنشاء مفتاحَي التشفير العام والخاص: edgemicro genkeys. يُرجى الاطّلاع على إعداد Edge Microgateway وضبطه لمزيد من التفاصيل.
  • jwt_public_key: (تلقائي: لا شيء) عنوان URL يشير إلى الخادم الوكيل Edge Microgateway الذي تم نشره على Apigee Edge. يعمل هذا الخادم الوكيل كنقطة نهاية للمصادقة من أجل إصدار رموز مميزة موقَّعة لرمز الدخول إلى العملاء. يتم عرض عنوان URL هذا عند تنفيذ الأمر لنشر الخادم الوكيل: edgemicro configure. يُرجى الاطّلاع على إعداد 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.
  • logging:
    • level: (الإعداد التلقائي: error)
      • info: لتسجيل جميع الطلبات والردود التي تتدفق من خلال مثيل Edge Microgateway.
      • warn: لتسجيل رسائل التحذير فقط
      • error: لتسجيل رسائل الخطأ فقط
    • dir: (تلقائي: ‎/var/tmp) الدليل الذي يتم فيه تخزين ملفات السجلّ
    • ‫stats_log_interval: (القيمة التلقائية: 60) الفاصل الزمني بالثواني الذي يتم فيه تسجيل الإحصاءات في ملف سجلّ واجهة برمجة التطبيقات.
    • ‫rotate_interval: (القيمة التلقائية: 24) الفاصل الزمني، بالساعات، الذي يتم فيه تدوير ملفات السجلّ.
  • المكوّنات الإضافية: تضيف المكوّنات الإضافية وظائف إلى Edge Microgateway. لمعرفة التفاصيل حول تطوير الإضافات، يُرجى الاطّلاع على تطوير إضافات مخصّصة.
  • ‫dir: مسار نسبي من دليل ./gateway إلى دليل ./plugins، أو مسار مطلق.
  • sequence: قائمة بوحدات المكوّنات الإضافية التي تريد إضافتها إلى مثيل Edge Microgateway. سيتم تنفيذ الوحدات بالترتيب المحدّد هنا.
  • debug: لإضافة تصحيح الأخطاء عن بُعد إلى عملية Edge Microgateway.
    • port: رقم المنفذ الذي يتم الاستماع إليه. على سبيل المثال، يمكنك ضبط مصحّح أخطاء IDE للاستماع إلى هذا المنفذ.
    • ‫args: وسيطات لعملية تصحيح الأخطاء مثال: args --nolazy
  • config_change_poll_interval: (الإعداد التلقائي: 600 ثانية) يحمّل Edge Microgateway إعدادات جديدة بشكل دوري وينفّذ إعادة تحميل في حال حدوث أي تغيير. يرصد الاستطلاع أي تغييرات تم إجراؤها على Edge (تغييرات على المنتجات والوكلاء المتوافقين مع microgateway وما إلى ذلك) بالإضافة إلى التغييرات التي تم إجراؤها على ملف الإعداد المحلي.
  • ‫disable_config_poll_interval: (الإعداد التلقائي: false) اضبطه على true من أجل إيقاف ميزة الاستطلاع التلقائي للتغييرات.
  • ‫request_timeout: لضبط مهلة لطلبات الاستهداف. يتم ضبط المهلة بالثواني. في حال حدوث مهلة، يستجيب Edge Microgateway برمز الحالة 504. (تمت إضافة الإصدار 2.4.x)

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

تضبط هذه الإعدادات كيفية التعامل مع عناوين HTTP معيّنة.

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

سمات oauth

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

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

السمات الخاصة بالمكوّنات الإضافية

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

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

يمكنك فلترة الخوادم الوكيلة المتوافقة مع Edge Microgateway التي ستعالجها نسخة Edge Microgateway. عند بدء Edge Microgateway، يتم تنزيل جميع الخوادم الوكيلة المتوافقة مع Microgateway في المؤسسة المرتبطة بها. استخدِم الإعدادات التالية لتحديد الخوادم الوكيلة التي ستعالجها microgateway. على سبيل المثال، يحدّ هذا الإعداد من عدد الخوادم الوكيلة التي سيعالجها 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 (اختياري): الحد الأقصى لعدد سجلات الإحصاءات التي يمكن أن يحتفظ بها المخزن المؤقت قبل البدء في حذف أقدم السجلات. القيمة التلقائية: 10000
  • batchSize (اختياري): الحد الأقصى لحجم مجموعة من سجلات الإحصاءات التي يتم إرسالها إلى Apigee. القيمة التلقائية: 500
  • ‫flushInterval (اختيارية): عدد الملّي ثانية بين كل عملية تفريغ لمجموعة من سجلّات الإحصاءات المُرسَلة إلى Apigee. الإعداد التلقائي: 5000

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

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

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

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

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

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

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

edgemicro_proxyname-health

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

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

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

على سبيل المثال، في الإعدادات التالية، سيتم فصل أي مسار لواجهة برمجة التطبيقات يحتوي على /healthcheck بواسطة المكوّن الإضافي للإحصاءات. يعني ذلك أنّه سيتم فصل /foo/healthcheck و/foo/bar/healthcheck كخادم وكيل منفصل باسم edgemicro_proxyname-health في لوحة بيانات الإحصاءات.

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

في الإعدادات التالية، سيتم فصل أي واجهة برمجة تطبيقات تتضمّن مسار الخادم الوكيل /mocktarget/healthcheck كخادم وكيل منفصل باسم edgemicro_proxyname-health في لوحة بيانات الإحصاءات.

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

إعداد Edge Microgateway خلف جدار حماية الشركة

الإصدار 2.4.x المتوافق

إذا تم تثبيت Edge Microgateway خلف جدار حماية، قد لا تتمكّن البوابة من التواصل مع Apigee Edge. في هذه الحالة، يتوفّر خياران يمكنك استخدامهما:

الخيار 1:

الخيار الأول هو ضبط الخيار edgemicro: proxy_tunnel على true في ملف إعداد microgateway:

edge_config:

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

عندما تكون قيمة proxy_tunnel هي true، تستخدم Edge Microgateway طريقة CONNECT لبروتوكول HTTP من أجل توجيه طلبات HTTP عبر اتصال TCP واحد. (وينطبق ذلك أيضًا إذا كانت متغيرات البيئة لضبط الخادم الوكيل مفعَّلة لبروتوكول أمان طبقة النقل (TLS)).

الخيار 2:

الخيار الثاني هو تحديد خادم وكيل وضبط proxy_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 التي يمكن لـ Edge Microgateway إرسال الرسائل إليها. على سبيل المثال:

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

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

لمزيد من المعلومات حول هذه المتغيّرات، يُرجى الاطّلاع على https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables

انظر أيضًا

كيفية إعداد Edge Microgateway خلف جدار حماية الشركة في منتدى Apigee

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

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

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

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

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

كيفية استخدام Edge Microgateway لرموز JWT

رمز الويب المميّز JSON‏ (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 باستخدام Management API:

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

المكان:

  • ‫org هو اسم مؤسستك في Edge (يجب أن تكون مشرفًا في المؤسسة).
  • ‫env هي بيئة في مؤسستك (مثل "test" أو "prod").
  • ‫client_id هو رقم تعريف المستهلك في تطبيق المطوّر الذي أنشأته سابقًا.
  • client_secret هو "سر المستهلك" في تطبيق المطوّر الذي أنشأته سابقًا.

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

في وقت ما بعد إنشاء رمز JWT في البداية، قد تحتاج إلى تغيير مفتاحَي التشفير العام والخاص المخزَّنين في KVM المشفَّر في Edge. تُعرف عملية إنشاء مفتاحَي تشفير جديدين باسم "تدوير المفاتيح". عند تدوير المفاتيح، يتم إنشاء زوج مفاتيح خاص/عام جديد وتخزينه في KVM "microgateway" في مؤسسة/بيئة Apigee Edge. بالإضافة إلى ذلك، يتم الاحتفاظ بالمفتاح العام القديم مع قيمة معرّف المفتاح الأصلي.

لإنشاء رمز JWT، يستخدم Edge المعلومات المخزّنة في KVM المشفَّر. تم إنشاء مخزن مفاتيح وقيم (KVM) باسم microgateway وتعبئته بالمفاتيح عند إعداد (ضبط) Edge Microgateway في البداية. تُستخدَم المفاتيح في KVM لتوقيع رمز JWT وتشفيره.

تشمل مفاتيح KVM ما يلي:

  • ‫private_key: أحدث مفتاح RSA خاص (تم إنشاؤه مؤخرًا) يُستخدَم لتوقيع رموز JWT المميّزة.

  • ‫public_key: أحدث شهادة (تم إنشاؤها مؤخرًا) تُستخدَم للتحقّق من صحة رموز JWT الموقَّعة باستخدام private_key.

  • ‫private_key_kid: معرّف المفتاح الخاص الأحدث (الذي تم إنشاؤه مؤخرًا). يرتبط رقم تعريف المفتاح هذا بقيمة private_key ويُستخدَم لإتاحة تدوير المفتاح.

  • ‫public_key1_kid: معرّف المفتاح العام الأحدث (الذي تم إنشاؤه مؤخرًا). يرتبط هذا المفتاح بالقيمة public_key1 ويُستخدَم لإتاحة تدوير المفاتيح. هذه القيمة هي نفسها قيمة kid للمفتاح الخاص.

  • ‫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 Web Key (JWK). يمكنك الاطّلاع على مزيد من المعلومات حول هذا التنسيق في RFC 7517.

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

جارٍ فلترة الخوادم الوكيلة التي تم تنزيلها

تنزّل Edge Microgateway تلقائيًا جميع الخوادم الوكيلة في مؤسسة Edge التي تبدأ بالبادئة "edgemicro_‎". يمكنك تغيير هذا الإعداد التلقائي لتنزيل الخوادم الوكيلة التي تتطابق أسماؤها مع نمط معيّن.

  1. افتح ملف إعداد Edge Micro: ~/.edgemicro/org-env-config.yaml
  2. أضِف عنصر proxyPattern ضمن edge_config. على سبيل المثال، سيؤدي النمط التالي إلى تنزيل الخوادم الوكيلة، مثل edgemicro_foo وedgemicro_fast وedgemicro_first. 
    edge_config:
…
proxyPattern: edgemicro_f*

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

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

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

الاتصال بمصحِّح أخطاء

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

  1. أعِد تشغيل Edge Microgateway في وضع تصحيح الأخطاء. لإجراء ذلك، أضِف DEBUG=* إلى بداية الأمر start. على سبيل المثال: 
    DEBUG=* edgemicro start -o  myorg -e test -k
      db4e9e8a95aa7fabfdeacbb1169d0a8cbe42bec19c6b98129e02 -s
      6e56af7c1b26dfe93dae78a735c8afc9796b077d105ae5618ce7ed
  2. ابدأ برنامج تصحيح الأخطاء واضبطه على الاستماع إلى رقم المنفذ لعملية تصحيح الأخطاء.
  3. يمكنك الآن التنقّل في رمز Edge Microgateway البرمجي، وضبط نقاط التوقف، ومشاهدة التعبيرات، وما إلى ذلك.

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

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

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

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

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

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

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

واجهة برمجة التطبيقات 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. توضّح الخطوات التالية هذه العملية.

  1. احصل على رمز مميز للوصول ورمز مميز لإعادة التحميل باستخدام واجهة برمجة التطبيقات /token. يُرجى العِلم أنّ نوع إذن الوصول هو password: 
    curl -X POST \
  https://your_organization-your_environment.apigee.net/edgemicro-auth/token \
  -H 'Content-Type: application/json' \
  -d '{
   "client_id":"mpK6l1Bx9oE5zLdifoDbF931TDnDtLq",
   "client_secret":"bUdDcFgv3nXffnU",
   "grant_type":"password",
   "username":"mpK6lBx9RoE5LiffoDbpF931TDnDtLq",
   "password":"bUdD2FvnMsXffnU"
}'

    تعرض واجهة برمجة التطبيقات رمز دخول ورمزًا مميزًا لإعادة التحميل. تظهر الاستجابة على النحو التالي: 

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

    تعرض واجهة برمجة التطبيقات رمز دخول جديدًا. تظهر الاستجابة على النحو التالي: 

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

مراقبة مستمرة

Forever هي أداة Node.js تعيد تشغيل تطبيق Node.js تلقائيًا في حال توقّف العملية أو حدوث خطأ. يحتوي Edge Microgateway على ملف forever.json يمكنك ضبطه للتحكّم في عدد المرات والفواصل الزمنية التي يجب إعادة تشغيل Edge Microgateway فيها. يضبط هذا الملف خدمة Forever تُسمى forever-monitor، والتي تدير Forever آليًا.

يمكنك العثور على ملف forever.json في دليل التثبيت الجذري لـ Edge Microgateway. راجع أين يتم تثبيت Edge Microgateway. للحصول على تفاصيل حول خيارات الضبط، يُرجى الرجوع إلى مستندات forever-monitor.

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

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

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

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

إذا كنت تشغّل عدة مثيلات من Edge Microgateway، قد تحتاج إلى إدارة إعداداتها من مكان واحد. يمكنك إجراء ذلك من خلال تحديد نقطة نهاية HTTP حيث يمكن لـ Edge Micro تنزيل ملف الإعداد الخاص به. يمكنك تحديد نقطة النهاية هذه عند بدء Edge Micro باستخدام العلامة ‎-u.

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

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

حيث تعرض نقطة نهاية mgconfig محتوى ملف الإعداد. هذا هو الملف الذي يكون تلقائيًا في ~/.edgemicro ويتبع اصطلاح التسمية: org-env-config.yaml.

إيقاف التخزين المؤقت لبيانات اتصال TCP

يمكنك استخدام سمة الإعداد nodelay لإيقاف تخزين البيانات مؤقتًا لاتصالات TCP التي تستخدمها Edge Microgateway.

تستخدم اتصالات TCP تلقائيًا خوارزمية Nagle لتخزين البيانات مؤقتًا قبل إرسالها. يؤدي ضبط nodelay على true إلى إيقاف هذا السلوك (سيتم إرسال البيانات فورًا في كل مرة يتم فيها استدعاء socket.write()). يمكنك أيضًا الاطّلاع على مستندات Node.js لمزيد من التفاصيل.

لتفعيل nodelay، عدِّل ملف إعداد Edge Micro على النحو التالي:

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

تشغيل Edge Microgateway في الوضع المستقل

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

في الوضع المستقل، لا تعمل الميزات التالية لأنّها تتطلّب الاتصال بـ Apigee Edge:

  • ‫OAuth ومفتاح واجهة برمجة التطبيقات
  • الحصة
  • إحصاءات Google

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

ضبط البوابة وبدء تشغيلها

لتشغيل Edge Microgateway في الوضع المستقل:

  1. تأكَّد من تثبيت الإصدار 2.5.25 أو إصدار أحدث من Edge Microgateway. وإذا لم يكن الأمر كذلك، عليك تنفيذ الأمر التالي للترقية إلى أحدث إصدار: 
    npm install -g edgemicro

    إذا كنت بحاجة إلى مساعدة، يُرجى الاطّلاع على تثبيت Edge Microgateway.

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

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

    vi $HOME/.edgemicro/foo-bar-config.yaml
  3. الصِق الرمز التالي في الملف: 
    edgemicro:
  port: 8000
  max_connections: 1000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - extauth
      - spikearrest
headers:
  x-forwarded-for: true
  x-forwarded-host: true
  x-request-id: true
  x-response-time: true
  via: true
extauth:
  publickey_url: https://www.googleapis.com/oauth2/v1/certs
spikearrest:
  timeUnit: second
  allow: 10
  buffersize: 0
  4. صدِّر متغيّر البيئة التالي بالقيمة "1": 
    export EDGEMICRO_LOCAL=1
  5. نفِّذ الأمر start التالي، حيث تقدّم قيمًا لإنشاء مثيل للخادم الوكيل المحلي: 
    edgemicro start -o org_name -e environment_name -a local_proxy_name \
  -v local_proxy_version -t target_url -b base_path

    المكان:

    • ‫your_org هو اسم "المؤسسة" الذي استخدمته في اسم ملف الإعداد.
    • ‫your_environment هو اسم "env" الذي استخدمته في اسم ملف الإعداد.
    • ‫local_proxy_name هو اسم الخادم الوكيل المحلي الذي سيتم إنشاؤه. يمكنك استخدام أي اسم تريده.
    • ‫local_proxy_version هو رقم إصدار الخادم الوكيل.
    • ‫target_url هو عنوان URL الخاص بالهدف من الخادم الوكيل. (الهدف هو الخدمة التي يطلبها الخادم الوكيل).
    • ‫base_path هو المسار الأساسي للوكيل. يجب أن تبدأ هذه القيمة بشرطة مائلة للأمام. بالنسبة إلى مسار أساسي جذري، حدِّد شرطة مائلة للأمام فقط، على سبيل المثال، "/".

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

    edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
  6. اختبِر الإعدادات. 
    curl http://localhost:8000/echo  { "error" : "missing_authorization" }

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

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

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

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

  1. يجب إجراء إعداد وضبط عاديين لـ Edge Microgateway من أجل نشر الخادم الوكيل edgemicro-auth في مؤسستك أو بيئتك على Apigee Edge. إذا سبق لك تنفيذ هذه الخطوة، لن تحتاج إلى تكرارها.
  2. إذا نشرت Edge Microgateway على Apigee Cloud، يجب أن تكون متصلاً بالإنترنت لتتمكّن من الحصول على رمز JWT من نقطة النهاية هذه.
  3. إيقاف Edge Microgateway: 
    edgemicro stop
  4. في ملف الإعداد الذي أنشأته سابقًا ($HOME/.edgemicro/org-env-config.yaml)، وجِّه السمة extauth:publickey_url إلى نقطة النهاية edgemicro-auth/jwkPublicKeys في مؤسسة/بيئة Apigee Edge. على سبيل المثال: 
    extauth:
  publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'
  5. أعِد تشغيل Edge Microgateway كما فعلت سابقًا، باستخدام أسماء المؤسسات/البيئات التي استخدمتها في اسم ملف الإعداد. على سبيل المثال: 
    edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
  6. احصل على رمز JWT مميّز من نقطة نهاية التفويض. بما أنّك تستخدم نقطة النهاية edgemicro-auth/jwkPublicKeys، يمكنك استخدام أمر واجهة سطر الأوامر (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 على Apigee Edge. بدلاً من ذلك، يمكنك ضبط "خادم وكيل محلي" من خلال تقديم اسم الخادم الوكيل المحلي والمسار الأساسي وعنوان URL المستهدف عند بدء تشغيل microgateway. بعد ذلك، يتم إرسال طلبات البيانات من واجهة برمجة التطبيقات إلى البوابة المصغّرة إلى عنوان URL المستهدف للوكيل المحلي. In all other respects, local proxy mode works exactly the same as running Edge Microgateway in its normal mode. تعمل المصادقة بالطريقة نفسها، وكذلك إجراءات إيقاف الارتفاع المفاجئ في عدد الطلبات وفرض الحصص والمكوّنات الإضافية المخصّصة وما إلى ذلك.

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

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

‫Edgemicro كـ Sidecar

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

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

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

  1. تأكَّد من تثبيت الإصدار 2.5.25 أو إصدار أحدث من Edge Microgateway. وإذا لم يكن الأمر كذلك، عليك تنفيذ الأمر التالي للترقية إلى أحدث إصدار: 
    npm install -g edgemicro

    إذا كنت بحاجة إلى مساعدة، يُرجى الاطّلاع على تثبيت Edge Microgateway.

  2. شغِّل edgemicro init لإعداد بيئة الضبط المحلية، تمامًا كما تفعل في إعداد Edge Microgateway العادي. يمكنك أيضًا الاطّلاع على ضبط Edge Microgateway.
  3. شغِّل edgemicro configure، كما تفعل في إجراء إعداد Edge Microgateway النموذجي. على سبيل المثال: 
    edgemicro configure -o your_org -e your_env -u your_apigee_username

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

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

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

  6. في Apigee Edge، أنشئ تطبيقًا للمطوّرين. يجب إضافة منتج واجهة برمجة التطبيقات الذي أنشأته للتو إلى التطبيق. للحصول على المساعدة، يُرجى الاطّلاع على تسجيل تطبيق في واجهة مستخدم إدارة Edge.
  7. على الجهاز الذي تم تثبيت Edge Microgateway عليه، يمكنك تصدير متغير البيئة التالي بالقيمة "1". 
    export EDGEMICRO_LOCAL_PROXY=1
  8. نفِّذ أمر start التالي: 
    edgemicro start -o your_org -e your_environment -k your_key -s your_secret \
    -a local_proxy_name -v local_proxy_version -t target_url -b base_path

    المكان:

    • ‫your_org هي مؤسستك على Apigee.
    • ‫your_environment هي بيئة في مؤسستك.
    • ‫your_key هو المفتاح الذي تم عرضه عند تشغيل edgemicro configure.
    • your_secret هو الرمز السري الذي تم عرضه عند تشغيل edgemicro configure.
    • ‫local_proxy_name هو اسم الخادم الوكيل المحلي الذي سيتم إنشاؤه.
    • ‫local_proxy_version هو رقم إصدار الخادم الوكيل.
    • ‫target_url هو عنوان 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":""
}