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

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

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

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

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

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

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

استخدِم الإعدادات التالية للحد من عدد منتجات واجهات برمجة التطبيقات التي تنزيلها ومعالجتها من خلال Edge Microgateway. لفلترة المنتجات التي تم تنزيلها، أضِف مَعلمة طلب البحث productnamefilter إلى واجهة برمجة التطبيقات /products المُدرَجة في ملف *.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. في قسم "التطوير"، افتح سياسة JavaCallout في المحرِّر.
3. أضِف سمة مخصّصة بالمفتاح products.filter.attributes مع قائمة مفصولة بفواصل لأسماء السمات. لن يتم عرض سوى المنتجات التي تحتوي على أي من أسماء السمات المخصّصة في Edge Microgateway.
4. يمكنك اختياريًا إيقاف عملية التحقّق من أجل معرفة ما إذا كان المنتج مفعّلاً للبيئة الحالية من خلال ضبط السمة المخصّصة products.filter.env.enable على false. (القيمة التلقائية هي true).
5. (السحابة الإلكترونية الخاصة فقط) إذا كنت تستخدم Edge for Private Cloud، اضبط القيمة org.noncps على true لسحب المنتجات لإعدادات غير "الاستضافة في خدمات السحابة الإلكترونية".

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

<?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.

ضبط معدّل تكرار إرسال الإحصاءات

استخدِم مَعلمات الضبط هذه للتحكّم في معدّل تكرار إرسال Edge Microgateway لข้อมูล الإحصاءات إلى Apigee:

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

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

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

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

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

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

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

يمكنك ضبط المكوّن الإضافي للإحصاءات لتقسيم مسار واجهة برمجة التطبيقات المحدّد بحيث يظهر على أنّه خادم وكيل منفصل في لوحات بيانات "إحصاءات Edge". على سبيل المثال، يمكنك فصل واجهة برمجة تطبيقات التحقّق من الصحة في لوحة البيانات لتجنُّب الخلط بينها وبين طلبات البيانات الفعلية من واجهة برمجة التطبيقات الوكيلة. في لوحة بيانات "إحصاءات 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. أضِف الإعدادات التالية إلى ملف إعدادات بوابة التطبيقات الصغيرة:

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

استخدام أحرف البدل في الخوادم الوكيلة المتوافقة مع بوابة التطبيقات المصغّرة

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

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

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

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

كيفية استخدام Edge Microgateway لبيانات JWT

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

يمكنك إنشاء ملف JWT باستخدام سطر الأوامر واستخدامه في ملف عنوان التفويض لطلبات البيانات من واجهة برمجة التطبيقات بدلاً من مفتاح واجهة برمجة التطبيقات. على سبيل المثال:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

سيتم التحقّق من صحة شهادات JWT المقدَّمة لإثبات الهوية باستخدام المفتاح العام الجديد. إذا تعذّر إثبات صحة التوقيع، سيتم استخدام المفتاح العام القديم إلى أن تنتهي صلاحية 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 على الويب (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. بسبب هذا التأخير بين توقيع الرمز المميّز وإعادة تحميل مثيل بوابة الميكرو، سيتم رفض الرموز المميّزة الموقَّعة باستخدام المفتاح الأخير إلى أنتلقّى جميع المثيلات المفتاح العام الأخير.

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

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

في المثال التالي، تم ضبط المدة الزمنية للانتظار على 15 دقيقة:

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

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

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

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

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

   edge_config:
   …
   proxyPattern: edgemicro_f*

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

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

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

الاتصال ببرنامج تصحيح الأخطاء

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

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

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

   .

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

استخدام أمان الرموز المميّزة في OAuth2

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

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

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

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

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

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

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

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

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

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

نموذج للناتج

{
"token": "eyJraWQiOiIxIiwidHlwIjoi",
"access_token": "eyJraWQiOiIxIiwid",
"token_type": "bearer",
"expires_in": 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"
       }

المراقبة الدائمة

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

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

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

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

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

إيقاف ميزة التخزين المؤقت لبيانات اتصال بروتوكول النقل المتعدّد (TCP)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   export EDGEMICRO_LOCAL=1

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

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

   المكان:

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

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

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

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

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

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

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

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

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

1. يجب إجراء إعداد وضبط عاديينلـ Edge Microgateway من أجل نشر edgemicro-auth proxy في مؤسستك/بيئتك على Apigee Edge. إذا سبق لك تنفيذ هذه الخطوة، ليس عليك تكرارها.
2. إذا كنت قد نشرت Edge Microgateway في Apigee Cloud، يجب أن تكون متصلاً بالإنترنت حتى تتمكّن من الحصول على JWT من نقطة النهاية هذه.
3. أوقِف بوابة Edge المصغّرة:

   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 كما فعلت سابقًا، باستخدام أسماء org/env التي استخدمتها في اسم ملف الإعدادات. على سبيل المثال:

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

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

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

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

المكان:

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

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

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

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

ضبط وضع الخادم الوكيل على الجهاز

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

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

   edgemicro configure -o your_org -e your_env -u your_apigee_username

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

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

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

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

   export EDGEMICRO_LOCAL_PROXY=1

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

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

   المكان:

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

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

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

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

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

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

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

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

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

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

مثال على الإخراج:

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

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

يوضّح هذا القسم كيفية استخدام أداة المزامنة، وهي ميزة اختيارية تؤدي إلى تحسين مرونة Edge Microgateway من خلال السماح لها باسترداد بيانات الضبط من Apigee Edge وكتابتها في قاعدة بيانات Redis المحلية. عند تشغيل مثيل المُزامِن، يمكن لمثيل Edge Microgateway الآخر الذي يعمل على عقد مختلفة retrieving their configuration directly from this database.

يمكن حاليًا استخدام ميزة "مزامنة البيانات" مع Redis 5.0.x.

ما هو المُزامِن؟

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

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

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

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

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

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

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

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

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

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

ضبط نُسخ Edge Microgateway العادية

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

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

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

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

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

سمات الضبط

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

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