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

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

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

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

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

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

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

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

   npm upgrade edgemicro -g

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

   npm install edgemicro@3.2.3 -g

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

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

3. أخيرًا، عليك الترقية إلى أحدث إصدار من الخادم الوكيل edgemicro-auth:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1. أعِد تحميل إعدادات Edge Microgateway:

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

   المكان:

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

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

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

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

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

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

   المكان:

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

شاهِد الفيديوهات التالية للتعرّف على كيفية ضبط بروتوكول أمان طبقة النقل (TLS) في Apigee 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

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

استخدام خيارات طبقة المقابس الآمنة (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

في حال أردت تطبيق إعدادات بروتوكول أمان طبقة النقل (TLS)/طبقة المقابس الآمنة (SSL) على أهداف محدّدة متعددة، عليك تحديد المضيف الأول في الإعدادات على أنّه "فارغ"، ما يتيح الطلبات العامة، ثم تحديد مضيفين معيّنين بأي ترتيب. في هذا المثال، يتم تطبيق الإعدادات على عدة مضيفين محدّدين:

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

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

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

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

يمكنك تحديد مستوى السجلّ الذي تريد استخدامه في إعدادات 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

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

تاريخ الإضافة: الإصدار 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: مستوى التسجيل تعتمد هذه القيمة على سياق المعاملة ومستوى التسجيل الذي تم ضبطه في إعدادات edgemicro. يُرجى الاطّلاع على كيفية ضبط مستوى التسجيل. بالنسبة إلى سجلّات الإحصاءات، يتم ضبط المستوى على stats. يتم تسجيل سجلّات الإحصاءات على فترات منتظمة يتم ضبطها باستخدام الإعداد stats_log_interval. يُرجى الاطّلاع أيضًا على كيفية تغيير فواصل سجلّ التغييرات.
• ‫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: مستوى التسجيل تعتمد هذه القيمة على سياق المعاملة ومستوى التسجيل الذي تم ضبطه في إعدادات 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، يتلقّى معرّفًا فريدًا جديدًا وينشئ مجموعة جديدة من ملفات السجلّات باستخدام هذا المعرّف الفريد. يُرجى الاطّلاع أيضًا على الممارسات الجيدة لصيانة ملفات السجلّ.

رسائل الخطأ

ستحتوي بعض الإدخالات في السجلّ على رسائل خطأ. للمساعدة في تحديد مكان حدوث الأخطاء وسببها، يُرجى الاطّلاع على مرجع أخطاء 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 وضبطه لمزيد من التفاصيل.
• 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.
• logging:
  • level: (الإعداد التلقائي: error)
    • info: (يُنصح به) يسجّل جميع الطلبات والردود التي تتدفق من خلال مثيل Edge Microgateway.
    • warn: لتسجيل رسائل التحذير فقط
    • error: لتسجيل رسائل الخطأ فقط
    • debug: يسجّل رسائل تصحيح الأخطاء مع رسائل المعلومات والتحذير والخطأ.
    • trace: يسجّل معلومات التتبّع للأخطاء بالإضافة إلى رسائل المعلومات والتحذيرات والأخطاء.
    • none: لا يتم إنشاء ملف سجلّ.
  • 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)
• 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. في حال ضبط السمة على صحيح أو عدم تقديمها، سيعمل المكوّن الإضافي للإحصاءات كالمعتاد. لمزيد من التفاصيل، يُرجى الاطّلاع على سمات 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) يتم ضبطها على 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:

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

فلترة المنتجات حسب الاسم

استخدِم الإعدادات التالية لتحديد عدد منتجات واجهة برمجة التطبيقات التي يتم تنزيلها ومعالجتها من خلال Edge Microgateway. لفلترة المنتجات التي تم تنزيلها، أضِف مَعلمة طلب البحث productnamefilter إلى واجهة برمجة التطبيقات /products المدرَجة في ملف *.config.yaml Edge Microgateway. على سبيل المثال:

edge_config:
  bootstrap: >-
    https://edgemicroservices.apigee.net/edgemicro/bootstrap/organization/willwitman/environment/test
  jwt_public_key: 'https://myorg-test.apigee.net/edgemicro-auth/publicKey'
  managementUri: 'https://api.enterprise.apigee.com'
  vaultName: microgateway
  authUri: 'https://%s-%s.apigee.net/edgemicro-auth'
  baseUri: >-
    https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s
  bootstrapMessage: Please copy the following property to the edge micro agent config
  keySecretMessage: The following credentials are required to start edge micro
  products: 'https://myorg-test.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24'

يُرجى العِلم أنّه يجب تحديد قيمة مَعلمة طلب البحث بتنسيق تعبير عادي وأن تكون مرمّزة بعنوان URL. على سبيل المثال، يرصد التعبير النمطي ^[Ee]dgemicro.*$ أسماء مثل: "edgemicro-test-1" و"edgemicro_demo" و "Edgemicro_New_Demo". القيمة المرمّزة لعنوان URL، والمناسبة للاستخدام في مَعلمة طلب البحث، هي: %5E%5BEe%5Ddgemicro.%2A%24.

يعرض ناتج تصحيح الأخطاء التالي أنّه تم تنزيل المنتجات التي تمت فلترتها فقط:

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

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

         ]
      },
      {
         "apiResources":[

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

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

         ]
      }
   ]
}

فلترة المنتجات حسب السمات المخصّصة

لفلترة المنتجات استنادًا إلى سمات مخصّصة:

1. في واجهة مستخدم Edge، اختَر الخادم الوكيل edgemicro_auth في المؤسسة أو البيئة التي تم ضبط Edge Microgateway فيها.
2. في علامة التبويب "تطوير" (Develop)، افتح سياسة JavaCallout في المحرِّر.
3. أضِف سمة مخصّصة باستخدام المفتاح products.filter.attributes مع قائمة مفصولة بفواصل لأسماء السمات. سيتم عرض المنتجات التي تحتوي على أي من أسماء السمات المخصصة فقط إلى Edge Microgateway.
4. يمكنك اختياريًا إيقاف عملية التحقّق لمعرفة ما إذا كان المنتج مفعَّلاً للبيئة الحالية من خلال ضبط السمة المخصّصة products.filter.env.enable على false. (القيمة التلقائية هي true).
5. (السحابة الإلكترونية الخاصة فقط) إذا كنت تستخدم Edge للسحابة الإلكترونية الخاصة، اضبط السمة 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>

فلترة المنتجات حسب حالة الإبطال

تتضمّن منتجات واجهة برمجة التطبيقات ثلاثة رموز حالة: "في انتظار المراجعة" و"موافَق عليه" و"مُلغى". تمت إضافة سمة جديدة باسم allowProductStatus إلى سياسة ضبط متغيّرات JWT في الخادم الوكيل edgemicro-auth. لاستخدام هذه السمة لفلترة منتجات واجهة برمجة التطبيقات المدرَجة في رمز JWT:

1. افتح الخادم الوكيل edgemicro-auth في محرِّر الخادم الوكيل في Apigee.
2. أضِف السمة allowProductStatus إلى ملف تنسيق XML الخاص بسياسة SetJWTVariables وحدِّد قائمة قيم مفصولة بفاصلة لرموز الحالة التي تريد الفلترة حسبها. على سبيل المثال، للفلترة حسب الحالة في انتظار المراجعة ومُلغى:

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <Javascript timeLimit="20000" async="false" continueOnError="false"
       enabled="true" name="Set-JWT-Variables">
       <DisplayName>Set JWT Variables</DisplayName>
       <FaultRules/>
       <Properties>
           <Property name="allowProductStatus">Pending,Revoked</Property>
       </Properties>
       <ResourceURL>jsc://set-jwt-variables.js</ResourceURL>
   </Javascript>

   إذا أردت إدراج المنتجات الموافَق عليها فقط، اضبط السمة على النحو التالي:

   <Property name="allowProductStatus">Approved</Property>

3. احفظ الخادم الوكيل.

   في حال عدم توفّر علامة Property، سيتم إدراج المنتجات التي تتضمّن جميع رموز الحالة في رمز JWT.

   لاستخدام هذه السمة الجديدة، يجب ترقية الخادم الوكيل edgemicro-auth.

ضبط معدّل تكرار إرسال الإشعارات الفورية في "إحصاءات 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

تعرض الصورة التالية خادمَي وكيل منفصلَين في لوحة بيانات "إحصاءات 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 بواسطة المكوّن الإضافي للإحصاءات. يعني ذلك أنّه سيتم فصل /foo/healthcheck و/foo/bar/healthcheck كخادم وكيل منفصل باسم edgemicro_proxyname-health في لوحة بيانات الإحصاءات.

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

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

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

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

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

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

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

1. اضبط متغيّرات البيئة HTTP_PROXY وHTTPS_PROXY وNO_PROXY. تتحكّم هذه المتغيّرات في المضيفين لكل خادم وكيل HTTP تريد استخدامه للتواصل مع Apigee Edge، أو المضيفين الذين يجب ألا يتعاملوا مع الاتصال مع Apigee Edge. على سبيل المثال:

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

   يُرجى العِلم أنّ NO_PROXY يمكن أن يكون قائمة نطاقات مفصولة بفواصل لا يجب أن يوجّه Edge Microgateway الخادم الوكيل إليها.

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

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

استخدام خادم وكيل HTTP للاتصال بالهدف

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

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

1. أضِف الإعدادات التالية إلى ملف إعدادات microgateway:

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

   المكان:

   • tunnel: (اختياري) عند ضبط هذه السمة على true، يستخدم Edge Microgateway طريقة HTTP CONNECT لإنشاء نفق لطلبات HTTP عبر اتصال TCP واحد. (ينطبق ذلك أيضًا إذا كانت متغيرات البيئة، كما هو مذكور أدناه، لإعداد الخادم الوكيل مفعَّلة لبروتوكول أمان طبقة النقل (TLS)). القيمة التلقائية: false
   • ‫url: عنوان URL لخادم وكيل HTTP.
   • bypass: (اختياري) يحدّد عنوان URL واحدًا أو أكثر من عناوين URL للمضيف المستهدف المفصولة بفواصل والتي يجب أن تتجاوز خادم وكيل HTTP. في حال عدم ضبط هذه السمة، استخدِم متغيّر البيئة NO_PROXY لتحديد عناوين URL المستهدَفة التي يجب تجاوزها.
   • enabled: إذا كانت القيمة صحيحة وتم ضبط proxy.url، يتم استخدام قيمة proxy.url للخادم الوكيل HTTP. إذا كانت القيمة "صحيح" ولم يتم ضبط proxy.url، استخدِم الخوادم الوكيلة المحدّدة في متغيّرات بيئة الخادم الوكيل لبروتوكول HTTP‏ HTTP_PROXY وHTTPS_PROXY، كما هو موضّح في استخدام خادم وكيل لبروتوكول HTTP للتواصل مع Apigee Edge.

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

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

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

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

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

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

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

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

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

رمز الويب المميّز JSON‏ (JWT) هو معيار للرموز المميّزة موضّح في RFC7519. يوفّر JWT طريقة لتوقيع مجموعة من المطالبات، والتي يمكن التحقّق منها بشكل موثوق من قِبل مستلِم 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 الموقَّعة باستخدام private_key.

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

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

• ‫public_key1: المفتاح العام الأحدث (الذي تم إنشاؤه مؤخرًا)

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

• ‫public_key2_kid: معرّف المفتاح العام القديم هذا المفتاح مرتبط بالقيمة public_key2 ويُستخدَم لإتاحة تدوير المفاتيح.

• ‫public_key2: المفتاح العام القديم

سيتم التحقّق من رموز JWT المقدَّمة للتحقّق باستخدام المفتاح العام الجديد. في حال تعذّر التحقّق، سيتم استخدام المفتاح العام القديم إلى أن تنتهي صلاحية رمز JWT (بعد فترة token_expiry*، وهي 30 دقيقة تلقائيًا). بهذه الطريقة، يمكنك "تبديل" المفاتيح بدون تعطيل زيارات واجهة برمجة التطبيقات على الفور.

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

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

1. لترقية KVM، استخدِم الأمر edgemicro upgradekvm. لمعرفة التفاصيل حول تشغيل هذا الأمر، يُرجى الاطّلاع على ترقية KVM. يجب تنفيذ هذه الخطوة مرة واحدة فقط.
2. لترقية الخادم الوكيل edgemicro-oauth، استخدِم الأمر edgemicro upgradeauth. لمعرفة تفاصيل حول تشغيل هذا الأمر، يُرجى الاطّلاع على ترقية الخادم الوكيل edgemicro-auth. يجب تنفيذ هذه الخطوة مرة واحدة فقط.
3. أضِف السطر التالي إلى ملف ~/.edgemicro/org-env-config.yaml، حيث يجب تحديد المؤسسة والبيئة نفسها التي تم ضبط البوابة الصغيرة لاستخدامها:

   jwk_public_keys: 'https://$ORG-$ENV.apigee.net/edgemicro-auth/jwkPublicKeys'

4. شغِّل أمر تغيير المفاتيح لتغييرها. للحصول على تفاصيل حول هذا الأمر، يُرجى الاطّلاع على تدوير المفاتيح.

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

ضبط تأخير "ليس قبل"

بالنسبة إلى الإصدارات 3.1.5 والإصدارات الأقدم، كان المفتاح الخاص الجديد الذي تم إنشاؤه بواسطة الأمر rotatekey يسري مفعوله على الفور، وتم توقيع الرموز المميزة الجديدة التي تم إنشاؤها باستخدام المفتاح الخاص الجديد. ومع ذلك، لم يكن المفتاح العام الجديد متاحًا لمثيلات Edge Microgateway إلا كل 10 دقائق (بشكل تلقائي) عند إعادة تحميل إعدادات microgateway. بسبب هذا التأخير بين توقيع الرمز المميّز وإعادة تحميل مثيل microgateway، سيتم رفض الرموز المميّزة الموقَّعة باستخدام أحدث مفتاح إلى أن تتلقّى جميع المثيلات أحدث مفتاح عام.

في الحالات التي تتوفّر فيها عدة مثيلات من microgateway، كان تأخُّر المفتاح العام يؤدي أحيانًا إلى حدوث أخطاء أثناء التشغيل متقطّعة مع الحالة 403، لأنّ عملية التحقّق من صحة الرمز المميّز كانت تنجح في مثيل واحد، ولكنّها تفشل في مثيل آخر إلى أن يتم إعادة تحميل جميع المثيلات.

بدءًا من الإصدار 3.1.6، تتيح لك علامة جديدة في الأمر rotatekey تحديد مهلة زمنية ليصبح المفتاح الخاص الجديد ساريًا، ما يتيح الوقت لتحديث جميع مثيلات microgateway وتلقّي المفتاح العام الجديد. العلامة الجديدة هي --nbf، والتي تعني "ليس قبل". تأخذ هذه العلامة قيمة عدد صحيح، وهو عدد دقائق التأخير.

في المثال التالي، تم ضبط التأخير على 15 دقيقة:

edgemicro rotatekey -o docs -e test \
-k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \
-s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47 \
--nbf 15

يُرجى العِلم أنّ من أفضل الممارسات ضبط التأخير ليكون أكثر من إعدادات ضبط config_change_poll_internal، والتي تكون 10 دقائق تلقائيًا. اطّلِع أيضًا على سمات edgemicro.

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

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

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

   edge_config:
   …
   proxyPattern: edgemicro_f*

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

يتم تبادل مفاتيح واجهة برمجة التطبيقات برموز حامل مميزة يتم تخزينها مؤقتًا. يمكنك إيقاف التخزين المؤقت من خلال ضبط العنوان Cache-Control: no-cache في الطلبات الواردة إلى Edge Microgateway.

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

يمكنك تمرير مفتاح واجهة برمجة التطبيقات في طلب بيانات من واجهة برمجة التطبيقات إما كمَعلمة طلب بحث أو في عنوان. يكون اسم المَعلمة في العنوان وطلب البحث تلقائيًا هو x-api-key.

مثال على مَعلمة طلب البحث:

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

مثال على العنوان:

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

ضبط اسم مفتاح واجهة برمجة التطبيقات

يكون x-api-key تلقائيًا هو الاسم المستخدَم لكل من عنوان مفتاح واجهة برمجة التطبيقات ومعلمة طلب البحث. يمكنك تغيير هذا الإعداد التلقائي في ملف الإعداد، كما هو موضّح في إجراء تغييرات على الإعدادات. على سبيل المثال، لتغيير الاسم إلى apiKey:

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

في هذا المثال، يتم تغيير كل من مَعلمة طلب البحث واسم العنوان إلى apiKey. ولن يعمل الاسم x-api-key في أي من الحالتين. يمكنك أيضًا الاطّلاع على إجراء تغييرات على الإعدادات.

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

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

لمزيد من المعلومات حول استخدام مفاتيح واجهة برمجة التطبيقات مع طلبات الخادم الوكيل، يُرجى الاطّلاع على Secure Edge Microgateway.

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

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

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

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

استخدام أمان الرمز المميّز لبروتوكول OAuth2

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

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

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

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

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

استبدِل أسماء مؤسستك وبيئتك في عنوان URL، واستبدِل قيم رقم تعريف المستهلك وسر المستهلك التي تم الحصول عليها من تطبيق مطوّر على Apigee Edge لمَعلمتَي النص client_id وclient_secret:

curl -i -X POST "http://<org>-<test>.apigee.net/edgemicro-auth/token" \
-d '{"grant_type": "client_credentials", "client_id": "your_client_id", \
"client_secret": "your_client_secret"}' -H "Content-Type: application/json"

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

أرسِل بيانات اعتماد العميل كعنوان مصادقة أساسية وgrant_type كمَعلمة نموذج. تمت مناقشة نموذج الطلب هذا أيضًا في RFC 6749: إطار عمل تفويض OAuth 2.0.

http://<org>-<test>.apigee.net/edgemicro-auth/token -v -u your_client_id:your_client_secret \
-d 'grant_type=client_credentials' -H "Content-Type: application/x-www-form-urlencoded"

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

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

كيفية الحصول على رمز مميّز لإعادة التحميل

للحصول على رمز مميّز لإعادة التحميل، يمكنك إجراء طلب بيانات من واجهة برمجة التطبيقات إلى نقطة النهاية /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"
   }'

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

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. أنشئ ملف إعداد بالاسم التالي: $HOME/.edgemicro/$ORG-$ENV-config.yaml

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

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

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

   edgemicro:
     port: 8000
     max_connections: 1000
     config_change_poll_interval: 600
     logging:
       level: error
       dir: /var/tmp
       stats_log_interval: 60
       rotate_interval: 24
     plugins:
       sequence:
         - extauth
         - spikearrest
   headers:
     x-forwarded-for: true
     x-forwarded-host: true
     x-request-id: true
     x-response-time: true
     via: true
   extauth:
     publickey_url: https://www.googleapis.com/oauth2/v1/certs
   spikearrest:
     timeUnit: second
     allow: 10
     buffersize: 0

3. صدِّر متغيّر البيئة التالي بالقيمة "1":

   export EDGEMICRO_LOCAL=1

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

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

   المكان:

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

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

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

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

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

   بما أنّ المكوّن الإضافي extauth مضمَّن في ملف foo-bar-config.yaml، سيظهر لك الخطأ "missing_authorization". يتحقّق هذا المكوّن الإضافي من صحة رمز JWT الذي يجب أن يكون متوفّرًا في عنوان "التفويض" لطلب البيانات من واجهة برمجة التطبيقات. في القسم التالي، ستحصل على رمز 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. تتواصل كل نسخة من البوابة المصغّرة مع نقطة نهاية واحدة فقط في الخدمة المصاحبة لها:

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

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

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

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

   edgemicro configure -o your_org -e your_env -u your_apigee_username

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

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

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

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

   export EDGEMICRO_LOCAL_PROXY=1

7. نفِّذ أمر start التالي:

   edgemicro start -o your_org -e your_environment -k your_key -s your_secret \
       -a local_proxy_name -v local_proxy_version -t target_url -b base_path

   المكان:

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

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

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

اختبار الإعدادات

يمكنك اختبار إعدادات الخادم الوكيل المحلي من خلال طلب نقطة نهاية الخادم الوكيل. على سبيل المثال، إذا حدّدت مسارًا أساسيًا باسم /echo، يمكنك استدعاء الوكيل على النحو التالي:

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

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

curl  http://localhost:8000/echo -H 'x-api-key:your_api_key'

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

curl  http://localhost:8000/echo -H "x-api-key:DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP"

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

{
  "headers":{
    "user-agent":"curl/7.54.0",
    "accept":"*/*",
    "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
    "client_received_start_timestamp":"1535134472699",
    "x-authorization-claims":"eyJhdWQiOi...TQ0YmUtOWNlOS05YzM1OTE5MTA1NDkifQ==",
    "target_sent_start_timestamp":"1535134472702",
    "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
    "x-forwarded-proto":"http",
    "x-forwarded-host":"localhost:8000",
    "host":"mocktarget.apigee.net",
    "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
    "via":"1.1 localhost, 1.1 google",
    "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
    "connection":"Keep-Alive"
  },
  "method":"GET",
  "url":"/",
  "body":""
}

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

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

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

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

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

By default, Edge Microgateway instances must be able to communicate with Apigee Edge to retrieve and refresh their configuration data, such as API proxy and API product configurations. في حال انقطاع الاتصال بالإنترنت مع Edge، يمكن أن تستمر نُسخ microgateway في العمل لأنّه يتم تخزين أحدث بيانات الإعدادات مؤقتًا. ومع ذلك، لا يمكن بدء مثيلات microgateway الجديدة بدون اتصال واضح. بالإضافة إلى ذلك، من الممكن أن يؤدي انقطاع الاتصال بالإنترنت إلى تشغيل مثيل واحد أو أكثر من مثيلات البوابة المصغّرة باستخدام معلومات ضبط غير متزامنة مع المثيلات الأخرى.

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

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

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

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

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

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

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

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

With the synchronizer running, you can configure additional Edge Microgateway nodes to run regular microgateway instances that process API proxy traffic. ومع ذلك، يمكنك ضبط هذه المثيلات للحصول على بيانات الضبط من قاعدة بيانات 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

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

تمت إضافة سمات الضبط التالية لإتاحة استخدام أداة المزامنة:

ضبط عناوين 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>