أداة رصد التغييرات في Edge for Private Cloud 4.54.00

أداة رصد التغييرات

تم إنشاء أداة لرصد التغييرات بهدف تحديد خوادم Apigee الوكيلة والسياسات والتدفقات المشترَكة وملفات JAR للموارد (على مستوى الخادم الوكيل أو البيئة أو المؤسسة) التي قد تتأثر أثناء عملية الانتقال إلى Edge for Private Cloud 4.54.00 وبعدها. تُنشئ هذه الأداة تقريرًا يوضّح الخوادم الوكيلة والتدفقات المشترَكة وملفات JAR للموارد التي تم نشرها والمتأثرة بالتغييرات، وتوفّر إرشادات إلى أدلة واستراتيجيات محدّدة ذات صلة بالخوادم الوكيلة أو التدفقات المشترَكة التي تم تحديدها.

المتطلبات الأساسية

  1. يلزم توفّر جهاز يستند إلى RHEL أو Rocky Linux لتشغيل هذه الأداة (راجِع متطلبات تثبيت Edge).
  2. يجب تثبيت JRE 8 أو إصدار أحدث وضبطه بشكلٍ صحيح على الجهاز المضيف للسماح بتشغيل النصوص البرمجية للأداة.
  3. تتطلّب الأداة الوصول إلى الشبكة لنقطة النهاية (عنوان URL) الخاصة بـ Management Server وبيانات اعتماد إدارية صالحة للمصادقة واسترداد البيانات.
  4. تتطلّب الأداة الوصول إلى دليل عمل محدّد (مثل /tmp) يتضمّن مساحة كافية على القرص وأذونات مناسبة للقراءة وإذن التعديل من أجل تنزيل الحِزم وإنشاء السجلات وتخزين الناتج.
  5. (اختياري) عند الترقية من الإصدار 4.53.00، تتطلّب الأداة ملف LDIF تم إنشاؤه باستخدام الأمر ldapsearch في قسم تغيير OpenLDAP - استخراج بيانات LDAP لرصد أسماء RDN الطويلة التي تتجاوز 241 حرفًا/بايت.

تشغيل الأداة

بعد استيفاء جميع المتطلبات الأساسية، نزِّل الأداة من مستودع Apigee باستخدام بيانات اعتماد Apigee، واستخرِج الأرشيف الذي تم تنزيله:

curl -u uName:pWord https://software.apigee.com/apigee/change-detector/change-detector-for-4.54.00_1.0.0.zip -o /tmp/change-detector-for-4.54.00_1.0.0.zip
 
unzip /tmp/change-detector-for-4.54.00_1.0.0.zip

بعد اكتمال التنزيل، يمكنك تشغيل الأمر التالي للاطّلاع على جميع الخيارات المتاحة للأداة:

./change-detector --help

لتشغيل الأداة، استخدِم الأمر التالي واستبدِل العناصر النائبة بمعلوماتك:

export APIGEE_PASSWORD=YOUR_PASSWORD
./change-detector --username YOUR_USERNAME --mgmt-url MGMT_URL --source-version SOURCE_VERSION

حدِّد --source-version 4.53.01 عند الترقية مباشرةً من Edge for Private Cloud 4.53.01 للبحث عن تغييرات Java 21. في حال الترقية من الإصدار 4.53.00، حدِّد --source-version 4.53.00 لإجراء فحص تراكمي يشمل عمليات إيقاف السياسات في الإصدار 4.53.01 وتغييرات Java 21.

تُنشئ الأداة ناتجًا بتنسيق CSV أو JSON يمكن مراجعته مباشرةً أو استيراده إلى تطبيقات جداول البيانات، مثل "جداول بيانات Google".

فهم ناتج الأداة

يحتوي التقرير على الأعمدة التالية:

المؤسسة

اسم المؤسسة التي يتوفّر فيها العنصر. بالنسبة إلى تغييرات OpenLDAP، تكون القيمة None.

البيئة

البيئة المحدّدة (مثل dev أو test أو prod) ضمن المؤسسة. بالنسبة إلى ملفات JAR على مستوى المؤسسة، يكون هذا الحقل N/A. بالنسبة إلى تغييرات OpenLDAP، تكون القيمة None.

اسم الخادم الوكيل

اسم الخادم الوكيل لواجهة برمجة التطبيقات أو التدفق المشترَك. بالنسبة إلى ملفات JAR للموارد على مستوى المؤسسة، يعرض هذا الحقل اسم المؤسسة. بالنسبة إلى ملفات JAR للموارد على مستوى البيئة، يعرض هذا الحقل اسم البيئة. بالنسبة إلى تغييرات OpenLDAP، يعرض هذا الحقل كيان LDAP الخاص باسم RDN.

النطاق

يحدّد نطاق العنصر الذي تم فحصه ومستواه:

  • proxy-level-jar: ملف JAR للموارد تم تحميله على مستوى الخادم الوكيل (ضمن /resources/java)
  • env-level-jar: ملف JAR للموارد تم تحميله على مستوى البيئة (راجِع ملفات الموارد)
  • org-level-jar: ملف JAR للموارد تم تحميله على مستوى المؤسسة
  • proxy: سياسة أو إعداد ضمن مراجعة خادم وكيل لواجهة برمجة التطبيقات
  • sharedflow: سياسة أو إعداد ضمن مراجعة تدفق مشترَك
  • ldif: ملف OpenLDAP LDIF (لعمليات التحقّق من OpenLDAP)

التغيير

رقم المراجعة المحدّد للخادم الوكيل لواجهة برمجة التطبيقات أو التدفق المشترَك. بالنسبة إلى ملفات JAR على مستوى البيئة أو المؤسسة، يكون هذا الحقل N/A. بالنسبة إلى تغييرات OpenLDAP، تكون القيمة None.

اسم السياسة

اسم السياسة المحدّدة التي تم رصدها كمشكلة محتملة (مثل JavaCallout-ValidateAccount أو OASValidation-1). بالنسبة إلى الموارد على مستوى المؤسسة، يعرض هذا الحقل N/A (Organization Resource). بالنسبة إلى الموارد على مستوى البيئة، يعرض هذا الحقل N/A (Environment Resource). بالنسبة إلى تغييرات OpenLDAP، تكون القيمة None.

نوع السياسة

نوع السياسة (مثل java-callout أو OASValidation). بالنسبة إلى تغييرات OpenLDAP، تكون القيمة None.

الإصدار المصدر

إصدار OPDK المصدر الذي تم ضبطه للفحص (4.53.00 أو 4.53.01)

المورد المتأثر

يصف المورد أو المكتبة المحدّدة التي تم رصدها:

  • بالنسبة إلى عمليات رصد الاستدعاء إلى Java 21: الاسم الدقيق لملف JAR المتأثر (مثل order-transform.jar أو corba-callout.jar)
  • بالنسبة إلى عمليات إيقاف الإصدار 4.53 القديم: deprecated library detected for NAME_OF_THE_AFFECTED_JAVA_CALLOUT_JAR
  • بالنسبة إلى عمليات رصد OAS أو JSONPath أو OpenLDAP: عنصر السياسة أو المورد المحدّد (مثل oas content type handling أو wildcard expression أو LDAP RDN exceeds 241 characters)

سبب الرصد

توفّر معلومات تشخيصية مفصّلة حول سبب وضع علامة على العنصر:

  • بالنسبة إلى عمليات رصد الاستدعاء إلى Java 21: الفئة المحدّدة ومكتبة الاستبدال المستهدَفة (إن أمكن) والسبب الأساسي (مثل Class: javax.xml.bind.JAXBContext | Target Library: jakarta.xml.bind-api-2.3.3.jar | Root Cause: ClassNotFoundException: JAXB API was removed from Java SE in Java 11 (JEP 320)). إذا تم رصد مشاكل متعددة ضمن ملف JAR نفسه، يتم دمجها مع الفصل بينها باستخدام الرمز ;.
  • بالنسبة إلى عمليات إيقاف الإصدار 4.53 القديم: قائمة بالفئات التي تتم الإشارة إليها من المكتبات التي تم إيقافها (مثل ['Detected use of class CLASS_NAME from JAR_NAME'])
  • بالنسبة إلى عمليات التحقّق من صحة OAS: المتغيّر المحدّد في العلامة Source (مثل Source=response)
  • بالنسبة إلى JSONPath: التعبير الدقيق الذي تم وضع علامة عليه
  • بالنسبة إلى OpenLDAP: اسم RDN الخاص بكيان LDAP المحدّد الذي تجاوز 241 بايت أو حرفًا

مدى التأثير

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

  • HIGH: رصدت الأداة تغييرًا غير متوافق (مثل استدعاء فئة تمت إزالتها نهائيًا، مثل javax.xml.bind.JAXBContext أو sun.misc.BASE64Encoder، أو اسم RDN في OpenLDAP يتجاوز 241 بايت). هناك احتمال كبير جدًا لحدوث خطأ في وقت التشغيل (ClassNotFoundException أو NoClassDefFoundError) ما لم يتم إصلاحه.
  • MEDIUM: رصدت الأداة نمطًا يتطلب فحص المطوّر والتحقّق من الوظائف:
    • بالنسبة إلى عمليات الاستدعاء إلى Java: تم وضع علامة عليها ضمن METHOD_SIGNATURE_MODIFICATION (مثل org.w3c.dom.Document)، حيث تتوفّر الفئة في Java 21 ولكن قد تم تغيير طرق معيّنة أو إيقافها.
    • بالنسبة إلى سياسات OASValidation: تم وضع علامة عليها عند استخدام متغيّرات وقت التشغيل الديناميكية في العنصر <Source> (مثل Source=response)، ما يتطلب تسجيل عملية التتبُّع لمراقبة المتغيّرات التي تم حلّها أثناء تنفيذ الخادم الوكيل.

نماذج لتقارير الرصد

تقرير الفحص المستهدَف لـ Java 21 (--source-version 4.53.01)

يوضّح المثال التالي ناتج التقرير لعملية ترقية من OPDK 4.53.01 إلى 4.54.00:

المؤسسة البيئة اسم الخادم الوكيل النطاق التغيير اسم السياسة نوع السياسة الإصدار المصدر المورد المتأثر سبب الرصد مدى التأثير
my-org prod order-processing proxy-level-jar 12 JavaCallout-ParseXml java-callout 4.53.01 jaxb-callout.jar Class: javax.xml.bind.JAXBContext | Cause: ClassNotFoundException..... HIGH
my-org stage legacy-corba-bridge proxy-level-jar 1 JavaCallout-CorbaClient java-callout 4.53.01 corba-callout.jar Class: org.omg.CORBA.ORB | Cause: ClassNotFoundException..... HIGH
my-org prod prod env-level-jar N/A N/A (Environment Resource) java-callout 4.53.01 env-security-utils.jar Class: sun.misc.BASE64Encoder | Cause: ClassNotFoundException..... HIGH
my-org N/A my-org org-level-jar N/A N/A (Organization Resource) java-callout 4.53.01 cglib-nodep-2.2.jar Class: net.sf.cglib.proxy.Enhancer | Cause: IllegalArgumentException..... HIGH
my-org prod invoice-parser proxy-level-jar 5 JavaCallout-ParseInvoice java-callout 4.53.01 invoice-dom.jar Class: org.w3c.dom.Document | Cause: Modified methods in Java 21..... MEDIUM
my-org prod payment-gateway proxy-level-jar 3 JavaCallout-SignToken java-callout 4.53.01 payment-lib.jar Class: com.mycompany.crypto.OldProvider | Target: custom-crypto-3.0.jar..... HIGH

تقرير الفحص التراكمي (--source-version 4.53.00)

يوضّح المثال التالي ناتج التقرير لعملية ترقية من OPDK 4.53.00 إلى 4.54.00:

المؤسسة البيئة اسم الخادم الوكيل النطاق التغيير اسم السياسة نوع السياسة الإصدار المصدر المورد المتأثر سبب الرصد مدى التأثير
my-org prod customer-portal proxy 3 ValidateOpenAPISpec OASValidation 4.53.00 oas content type handling Source=response MEDIUM
my-org prod accounts-api proxy-level-jar 4 JavaCallout-ValidateAccount java-callout 4.53.00 deprecated: custom-validator.jar..... ['Detected use of class org.apache.commons.beanutils.....'] HIGH
my-org prod order-processing proxy-level-jar 12 JavaCallout-ParseXml java-callout 4.53.00 jaxb-callout.jar Class: javax.xml.bind.JAXBContext | Cause: ClassNotFoundException..... HIGH
my-org None None ldif None None None 4.53.00 LDAP RDN exceeds 241 characters cn=very-long-rdn-name-exceeding-limit..... HIGH

للحصول على إرشادات حول إصلاح المشاكل التي تم تحديدها، راجِع استراتيجيات الإصلاح.