التغييرات في الإصدار 4.54.00 من Edge for Private Cloud

نظرة عامة على التغييرات

يقدّم الإصدار 4.54.00 من Edge for Private Cloud تغييرات متعدّدة تعزّز مستوى أمان المنصة وتعدّل مكوّناتها لتعمل مع Java 21. يتناول قسمان أدناه هذه التغييرات:

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

هناك ثلاث إمكانات متاحة في الإصدار 4.53.01 غير متاحة في Edge for Private Cloud 4.54.00. قبل التخطيط للترقية، راجِع الميزات غير المتوافقة مع الإصدار 4.54.00.

الميزات غير المتاحة في الإصدار 4.54.00

لا يتيح الإصدار 4.54.00 من Edge for Private Cloud استخدام الإمكانات التالية المتوفّرة في الإصدار 4.53.01. إذا كان النشر يستخدم أيًا منها، لا ترقِّ إلى الإصدار 4.54.00. يُرجى البقاء على الإصدار 4.53.01 والتواصل مع فريق دعم Apigee.

  • التثبيت على Google Distributed Cloud (GDC)‎ المستقلة لا يتوافق الإصدار 4.54.00 من Edge for Private Cloud مع بيئات GDC المعزولة. للاطّلاع على إجراءات الإصدار 4.53.01، يُرجى مراجعة مقالة تثبيت Apigee على Google Distributed Cloud المعزول.
  • نظام التشغيل RHEL 8.X أو Rocky 8.X المتوافق مع معيار FIPS لا يتوافق الإصدار 4.54.00 من Edge for Private Cloud مع التثبيت على مضيف RHEL 8.X أو Rocky 8.X الذي تم تفعيل معيار FIPS عليه. تكون أنظمة التشغيل هذه متوافقة في حال عدم تفعيل وضع FIPS. تتجاهل مواضيع ضبط الإصدار 4.54.00 أيضًا الإرشادات الخاصة بمعيار FIPS التي يوفّرها الإصدار 4.53.01، بما في ذلك إعداد مخزن مفاتيح BCFKS، وسمة الضبط الصامت FIPS_OS، وضبط مخزن مفاتيح PKCS12. للحصول على إرشادات الإصدار 4.53.01، يُرجى الاطّلاع على Edge for Private Cloud على RHEL 8.X أو Rocky 8.X المتوافق مع معيار FIPS.
  • دمج وحدة أمان الأجهزة (HSM) في Southbound: لا يتيح الإصدار 4.54.00 من Edge for Private Cloud اتصالات TLS الصادرة من معالجات الرسائل إلى خدمات الاستهداف في الخلفية التي تستخدم وحدة أمان الأجهزة (HSM) لشبكة Entrust nShield. للاطّلاع على إجراءات الإصدار 4.53.01، يُرجى مراجعة دليل دمج وحدة أمان الأجهزة Southbound في Apigee Edge for Private Cloud.

التغييرات في سياسة Java Callout

في الإصدار 4.54.00 من Edge for Private Cloud، تم تحديث مكوّنات المنصة الأساسية، بما في ذلك معالج الرسائل وخادم الإدارة والموجّه، لتعمل على Java 21 LTS. يحدّث Java 21 منصة Java، ما يشمل إزالة وحدات Java EE وCORBA القديمة (JEP 320)، وإزالة فئات الأدوات المساعدة الداخلية القديمة، وفرض التغليف القوي للوحدات (JEP 403).

بسبب هذه التغييرات، قد تتعطّل الخوادم الوكيلة لواجهة برمجة التطبيقات التي تتضمّن سياسات JavaCallout مخصّصة أو ملفات JAR للموارد مخصّصة (مخزّنة على مستوى الخادم الوكيل أو البيئة أو المؤسسة) عند الترقية إلى الإصدار 4.54.00.

فئات التغييرات التي قد تؤثر في Java Callouts

  1. إزالة وحدات Java EE وCORBA نهائيًا (JEP 320): تمت إزالة الوحدات التي تم إنشاؤها سابقًا في وقت تشغيل Java 8 (بما في ذلك JAXB javax.xml.bind.* وJAF javax.activation.* وJAX-WS javax.xml.ws.* وCORBA org.omg.*) من Java SE. ستتعذّر عمليات الاستدعاء التي تشير إلى هذه الحِزم بدون تجميع البدائل المستقلة في وقت التشغيل مع ظهور الخطأ NoClassDefFoundError.
  2. تمت إزالة فئات الأدوات المساعدة الداخلية: تمت إزالة المساعدين الداخليين القدامى، مثل sun.misc.BASE64Encoder وsun.misc.BASE64Decoder. يتعذّر تنفيذ وسائل الشرح التي تستدعي هذه الفئات مع ظهور الخطأ NoClassDefFoundError.
  3. التغليف القوي لمكوّنات Java الداخلية (JEP 403): لا يمكن الوصول إلى الحزم الداخلية في java.base (مثل sun.security.* وsun.reflect.* وcom.sun.*) بشكل انعكاسي من وسائل الشرح المخصّصة. تتعذّر طلبات الانعكاس في وقت التشغيل مع InaccessibleObjectException.
  4. تعديلات وإزالات توقيعات الطرق في فئات Java المتبقية: في بعض وحدات Java، تظل الفئة متوفّرة في Java 21، ولكن تمت إزالة أو إيقاف نهائي أو تعديل توقيعات طرق أو منشئات معيّنة (مثل طرق تحليل DOM معيّنة في org.w3c.dom.Document وفئات تحليل XML ذات الصلة).

    رصد الأدوات: تضع أداة رصد التغييرات علامة على الإشارات إلى هذه الفئات ضمن فئة METHOD_SIGNATURE_MODIFICATION مع MEDIUM Impact Certainty، ما يطلب من المطوّرين فحص الرمز المصدر لوسائل الشرح بحثًا عن استدعاءات الطرق المعدَّلة.

استراتيجيات المعالجة

قبل الترقية، تأكَّد من أنّ سياسات Java Callout وموارد JAR المخصّصة متوافقة مع بيئة التشغيل Java 21. سيساعدك استخدام أداة رصد التغييرات في تحديد الخوادم الوكيلة المتأثرة لواجهة برمجة التطبيقات والمسارات المشتركة وموارد JAR للبيئة أو المؤسسة في جميع أنحاء المجموعة.

استراتيجيات المعالجة الموضحة في هذا القسم هي أدلة عامة وليست حصرية بشكل متبادل. بناءً على متطلباتك التشغيلية، يمكنك الجمع بين الاستراتيجيات، على سبيل المثال، تحديث الرمز المصدر لوسائل الشرح باستخدام الاستراتيجية 2 ونشر نُسخ الخادم الوكيل المعدَّلة باستخدام الاستراتيجية 3B لتحقيق عدم توقّف الخدمة أثناء ترقيات "معالج الرسائل".

الاستراتيجيات 3A و3B و3C هي ثلاث طرق لتنفيذ النهج التشغيلي نفسه: ترقية العقدة وإعادة نشر الخادم الوكيل في أوقات مختلفة، بدون تغيير حزمة الخادم الوكيل. يمكنك اختيار أحد هذه الخيارات أو مجموعة منها استنادًا إلى متطلبات توفّر واجهة برمجة التطبيقات.

راجِع دليل اتخاذ القرار التالي لاختيار الطريقة الأنسب لعملية النشر:

دليل اتخاذ القرار بشأن إجراءات الحدّ من مخاطر Java Callout:

هل يتطلّب ذلك تحديث حزمة الخادم الوكيل وإعادة نشرها؟ السيناريو أو المتطلبات الاستراتيجية المقترَحة المشكلة التي يحلّها القيود الرئيسية
نعم (تعديل الحزمة فقط) تتوفّر مكتبة متوافقة مع الإصدارَين، ولا حاجة إلى فترة توقّف الاستراتيجية 1: خادم وكيل متوافق مع الإصدارين من خلال حِزم JAR استعادة المكتبات المفقودة في جميع الإصدارات بدون أي فترة توقّف يجب توفّر مكتبة مستقلة متوافقة مع الوضعَين وتفعيل conf_system_java.21.enable.external.allowed.packages=true في الإصدار 4.54.00
نعم (تعديل الرمز المصدر) تمت صيانة الرمز المصدر، والمطلوب هو إصلاح دائم للمشكلة الاستراتيجية 2: التنفيذ البديل (تحديث الرموز البرمجية والتبعية) يحلّ بشكل دائم المشاكل المتعلّقة بالفئات التي تمت إزالتها والتبعيات الداخلية لواجهة برمجة التطبيقات يتطلّب ذلك إجراء تغييرات على الرمز المصدر وإعادة النشر (يجب إقران هذه الاستراتيجية بالاستراتيجية 3A أو 3B لطرح التغييرات)
لا (النهج التشغيلي) فترة الصيانة المُجدوَلة المسموح بها الاستراتيجية 3 (أ): فترة التوقّف المخطط لها للصيانة (إعادة النشر في الموقع) يسمح بترقية العقدة أولاً، ثم نشر الخادم الوكيل الذي تم تحديثه يتطلّب فترة توقّف مجدوَلة لمستخدمي واجهة برمجة التطبيقات
لا (النهج التشغيلي) لا يتطلب ذلك أي فترة توقّف، ولا يمكن تجميع ملفات JAR المزدوجة الاستراتيجية 3 (ب): إنشاء بيئة جديدة (نقل البيانات بدون توقّف) يعزل العُقد 4.53 و4.54 أثناء نقل البيانات بدون أي انقطاع في حركة البيانات يتطلّب ذلك الحصول على عُقد مؤقتة لمعالجة الرسائل
لا (النهج التشغيلي) لا يمكن تعديل حِزم الخوادم الوكيلة قبل الترقية * الاستراتيجية 3ج: وضع المكتبات الخارجية على مستوى العقدة توفير ملفات JAR للمكتبات المفقودة على مستوى العقدة بدون تعديل حِزم الخوادم الوكيلة تتم مشاركتها على جميع الخوادم الوكيلة على العقدة، ولا تحلّ مشكلة الانعكاس أو حزم java.*
لا (مكتبات تابعة لجهات خارجية ذات مصدر مغلق) مكتبات مزوّدي الخدمة الخارجيين التي تستخدم الانعكاس في العناصر الداخلية لـ Java * الاستراتيجية 4: علامات JVM‏ (--add-opens / --add-exports) يخفّف القيود المفروضة على الانعكاس لحزم Java الداخلية لا يمكن استعادة الفئات أو الطرق التي تمت إزالتها، وينطبق ذلك على مستوى العقدة

الاستراتيجية 1: خادم وكيل متوافق مع الإصدارين من خلال ملفات JAR المجمّعة (الاختبار قبل الترقية لضمان عدم توقّف الخدمة)

حالات الاستخدام: استخدِم هذه الاستراتيجية في الحالات التالية:

  • تتوفّر مكتبة بديلة مستقلة ومتوافقة مع الإصدارين: يتوفّر ملف JAR بديل ينفّذ الوظائف المطلوبة ويمكن تجميعه مباشرةً في الخادم الوكيل لواجهة برمجة التطبيقات بدون الحاجة إلى تعديل الرمز المصدر.
  • تريد أن تعمل واجهات برمجة التطبيقات الوكيلة الحالية وJava Callouts بسلاسة على كل من الإصدار الحالي (على سبيل المثال، Edge for Private Cloud 4.53.01) والإصدار الذي تمت ترقيته (Edge for Private Cloud 4.54.00).
  • يجب اختبار جميع التغييرات والتحقّق منها في بيئات الاختبار وبيئات التشغيل الفعلي قبل ترقية مجموعة Edge for Private Cloud، ما يضمن عدم حدوث أي مشاكل غير متوقّعة أو فترة التوقف عن العمل في الزيارات المباشرة.
  • تريد تجنُّب إعادة كتابة أو إعادة تصميم منطق عمل Java Callout.

طريقة العمل: في Java 8، تم إنشاء مكتبات معيّنة (مثل JAXB javax.xml.bind.* أو Activation javax.activation.*) مباشرةً في بيئة التشغيل Java 8. لهذا السبب، لم يكن المطوّرون بحاجة إلى تضمين ملفات JAR إضافية داخل حِزم الخوادم الوكيلة. في Java 21، تمت إزالة هذه المكتبات من بيئة التشغيل Java.

لجعل الخادم الوكيل "متوافقًا بشكل مزدوج" مع Edge for Private Cloud 4.53.x و4.54.00:

  1. حدِّد المكتبة المفقودة التي يتطلّبها وسيلة الشرح (على سبيل المثال، JAXB أو Activation).
  2. احصل على ملف JAR البديل المستقل والمفتوح المصدر (على سبيل المثال، jakarta.xml.bind-api-2.3.3.jar وjaxb-runtime-2.3.8.jar).
  3. يمكنك وضع ملف JAR البديل مباشرةً في حزمة الوكيل ضمن apiproxy/resources/java/، أو تحميله إلى نسخة الوكيل باستخدام واجهة برمجة التطبيقات لملفات الموارد على مستوى الوكيل، أو تحميله كملف موارد على مستوى البيئة أو مستوى المؤسسة. لمزيد من المعلومات حول إدارة ملفات الموارد، يُرجى الاطّلاع على مستندات ملفات موارد Apigee.
  4. النشر والاختبار قبل الترقية: تحمّل معالِجات الرسائل في كل من Edge for Private Cloud 4.53.x و4.54.00 الفئات من ملفات JAR المجمّعة هذه. يمكنك نشر حزمة الخادم الوكيل المحدَّثة هذه واختبارها باستخدام زيارات اصطناعية في مجموعة Edge for Private Cloud 4.53.x الحالية الآن.
  5. تفعيل تحميل الحِزم الخارجية المسموح بها على معالِجات الرسائل (مطلوب للإصدار 4.54.00): في الإصدار 4.54.00 من Edge for Private Cloud، يتم تلقائيًا إيقاف تحميل حِزم Java التي تمت إزالتها (مثل javax.xml.bind.* وjavax.activation.*) من ملفات JAR الخارجية أو المجمّعة (conf_system_java.21.enable.external.allowed.packages=false)، لذا لن يعمل تجميع ملفات JAR وحدها تلقائيًا. يجب تفعيل هذه السمة في /opt/apigee/customer/application/message-processor.properties باستخدام الرمز مع الإعدادات (CwC) (يمكنك ضبط هذه السمة قبل ترقية عقدة "معالج الرسائل" أو ضبطها بعد الترقية وإعادة تشغيل "معالج الرسائل"): 
    conf_system_java.21.enable.external.allowed.packages=true
  6. عدم حدوث مشاكل في الزيارات المباشرة بعد الترقية: عند ترقية المجموعة لاحقًا إلى الإصدار 4.54.00 من Edge for Private Cloud مع تفعيل conf_system_java.21.enable.external.allowed.packages=true، يتوفّر لدى "معالج الرسائل" ملف JAR المطلوب ويحمّل الفئات من ملف الموارد المجمّعة بدون أيّ عطل (NoClassDefFoundError)، ما يضمن ترقية سلسة بدون أيّ فترة توقّف.

مثال على الرمز البرمجي: وسيلة الشرح الخاصة بتحليل الطلبات والتحقّق من صحتها بتنسيق XML

لنفترض أنّ لدينا وسيلة شرح Java نموذجية في Apigee تستخرج طلبات XML الواردة وتتحقّق من صحتها باستخدام JAXB (JAXBContext وUnmarshaller).

  • قبل الإصلاح (يتعذّر في Edge for Private Cloud 4.54.00): في Edge for Private Cloud 4.53.x، تحتوي حزمة الخادم الوكيل على ملف JAR الخاص بالتوسيع فقط، وتعتمد على مكتبات وقت التشغيل المضمّنة في Java 8 لـ JAXB: 
    apiproxy/
  resources/
    java/
      OrderXmlParserCallout.jar   <-- No JAXB JAR bundled

    تنفيذ Java Callout:

    package com.example.callout;

// other required imports
import java.io.StringReader;
import javax.xml.bind.JAXBContext;
import javax.xml.bind.Unmarshaller;

public class OrderXmlParserCallout implements Execution {
    @Override
    public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
        try {
            String requestXml = messageContext.getMessage().getContent();
            JAXBContext jaxbContext = JAXBContext.newInstance(Order.class);
            Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();
            Order order = (Order) unmarshaller.unmarshal(new StringReader(requestXml));
            messageContext.setVariable("order_id", order.getId());
            return ExecutionResult.SUCCESS;
        } catch (Exception e) { }
    }
}

    الخطأ: في الإصدار 4.53.x من Edge for Private Cloud، يتم تنفيذ هذا الإجراء بدون مشاكل. بعد ترقية العقدة إلى الإصدار 4.54.00 من Edge for Private Cloud، يتعذّر على هذا الخادم الوكيل فورًا معالجة الطلبات:

    java.lang.NoClassDefFoundError: javax/xml/bind/JAXBContext
        at com.example.callout.OrderXmlParserCallout.execute(OrderXmlParserCallout.java:20)
  • بعد الإصلاح (متوافق مع Edge for Private Cloud 4.53.x و4.54.00): لن تحتاج إلى إعادة كتابة رمز Java Callout أو إعادة تجميعه. يمكنك جعل الخادم الوكيل متوافقًا مع الإصدارين مباشرةً من خلال توفير ملفات JAR المستقلة:
    1. تجميع ملفات JAR المستقلة أو تحميلها مباشرةً: احصل على مكتبات JAXB المستقلة (jakarta.xml.bind-api-2.3.3.jar وjaxb-runtime-2.3.8.jar) وضَعها داخل حزمة الخادم الوكيل ضمن apiproxy/resources/java/: 
      apiproxy/
  resources/
    java/
      OrderXmlParserCallout.jar
      jakarta.xml.bind-api-2.3.3.jar
      jaxb-runtime-2.3.8.jar

      بدلاً من ذلك، يمكنك تحميل jakarta.xml.bind-api-2.3.3.jar وjaxb-runtime-2.3.8.jar كملفات موارد باستخدام واجهة برمجة تطبيقات ملفات الموارد على مستوى الخادم الوكيل، أو على مستوى البيئة أو مستوى المؤسسة حتى تتمكّن جميع الخوادم الوكيلة في النطاق نفسه من مشاركتها بدون تجميعها في كل حزمة خادم وكيل فردية.

      إذا كنت تنشئ حزمة الخادم الوكيل من المصدر باستخدام Maven، عليك الإعلان عن هذه التبعيات في ملف pom.xml ليتم تجميعها تلقائيًا أثناء عملية الإنشاء.

    2. النشر والاختبار على مجموعة 4.53.x الحالية: انشر حزمة الخادم الوكيل المعدَّلة في بيئة Edge for Private Cloud 4.53.x الحالية وأرسِل مكالمات تجريبية. بما أنّ معالجات الرسائل في Edge for Private Cloud 4.53.x تحمّل الفئات من ملفات JAR المجمّعة هذه، يمكنك التأكّد من أنّ وسيلة الشرح ستواصل العمل بالطريقة نفسها.
    3. تفعيل تحميل الحِزم الخارجية المسموح بها من خلال "الرمز مع الإعدادات" (CwC): بما أنّ تحميل الحِزم الخارجية المسموح بها يكون غير مفعَّل تلقائيًا في Edge for Private Cloud الإصدار 4.54.00 (conf_system_java.21.enable.external.allowed.packages=false)، يجب تفعيله على كل عقدة من عقد معالج الرسائل في /opt/apigee/customer/application/message-processor.properties باستخدام الرمز مع الإعدادات (CwC): 
      conf_system_java.21.enable.external.allowed.packages=true
    4. عدم حدوث أي مشاكل في الزيارات المباشرة بعد الترقية: بعد التحقّق من صحة الخادم الوكيل في بيئة الإصدار 4.53.x وضبطه باستخدام السمة CwC، يصبح جاهزًا بالكامل. عند ترقية المجموعة إلى Edge for Private Cloud 4.54.00، يحمّل معالج الرسائل فئات JAXB المجمّعة، ما يضمن عدم حدوث أخطاء أو انقطاع في الزيارات المباشرة.

الاستراتيجية 2: التنفيذ البديل (تحديث الرموز البرمجية والتبعيات)

حالات الاستخدام: يُنصح به لقواعد الرموز البرمجية النشطة التي يمكن فيها صيانة الرمز المصدر للوكيل بسهولة. هذه هي الطريقة الأفضل على المدى الطويل للامتثال لمتطلبات Java 21. ملاحظة حول الطرح: بما أنّ نشر نُسخ الخادم الوكيل الحديثة يتطلّب تنسيق معالِج الرسائل، يمكنك إقران هذه الاستراتيجية مع الاستراتيجية 3A (أثناء فترة الصيانة المخطط لها) أو الاستراتيجية 3B (لتحقيق فترة توقّف صفرية مع معالِجات الرسائل الموازية).

طريقة العمل: استبدِل فئات Java الداخلية التي تمت إزالتها بواجهات برمجة تطبيقات Java SE الرسمية أو بمكافئات مستقلة مفتوحة المصدر، وحزِّم التبعيات المطلوبة التابعة لجهات خارجية مباشرةً في ملفات الموارد أو POM الخاصة بحزمة الخادم الوكيل.

أمثلة على الرموز:

المثال 1: تحديث الطريقة والرمز (استبدال الأدوات المساعدة الداخلية التي تمت إزالتها)

في Java 8، كانت وسائل الشرح تستخدم بشكل متكرر فئات الأدوات المساعدة الداخلية مثل sun.misc.BASE64Encoder. في إصدارات Java الحديثة، تمت إزالة هذه الفئات، ولكن واجهة برمجة التطبيقات java.util.Base64 العادية توفّر بدائل مباشرة بدون الحاجة إلى ملفات JAR خارجية:

  • قبل (تنفيذ Java 8 القديم): 
    // Incompatible in Edge for Private Cloud 4.54.00: sun.misc package removed
import sun.misc.BASE64Encoder;
// other required imports

public class Base64EncodeCallout implements Execution {
    @Override
    public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
        BASE64Encoder encoder = new BASE64Encoder();
        String encoded = encoder.encode("ApigeePayload".getBytes());
        messageContext.setVariable("encoded_data", encoded);
        return ExecutionResult.SUCCESS;
    }
}
  • بعد (التنفيذ المتوافق مع Java 21): 
    // Fully compatible with Java 21: uses standard Java SE java.util.Base64 (no external JARs needed)
import java.util.Base64;
// other required imports

public class Base64EncodeCallout implements Execution {
    @Override
    public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
        String encoded = Base64.getEncoder().encodeToString("ApigeePayload".getBytes());
        messageContext.setVariable("encoded_data", encoded);
        return ExecutionResult.SUCCESS;
    }
}
المثال 2: إعادة هيكلة على مستوى الاستيراد باستخدام مكتبة مجمّعة (JAXB Namespace Prefix Mapper)

في Java 8، كانت الخوادم الوكيلة لواجهة برمجة التطبيقات التي تخصّص بادئات مساحة أسماء XML توسّع عادةً أداة ربط JAXB الداخلية من Sun‏ com.sun.xml.internal.bind.marshaller.NamespacePrefixMapper. في Java 21، تتم إزالة حِزم Sun الداخلية ولا يمكن الوصول إليها.

توفّر المكتبة المستقلة المفتوحة المصدر (org.glassfish.jaxb:jaxb-runtime) الفئة نفسها ضمن com.sun.xml.bind.marshaller.NamespacePrefixMapper. تكون جميع توقيعات الطرق والمعلمات وأنواع القيم التي تم إرجاعها متطابقة، ويكون تغيير الرمز في عبارة الاستيراد فقط:

  • قبل (تنفيذ Java 8 القديم): 
    // In Java 8: Relied on internal Sun class in Java 8 runtime
import com.sun.xml.internal.bind.marshaller.NamespacePrefixMapper;
public class CustomNamespaceMapper extends NamespacePrefixMapper {
    @Override
    public String getPreferredPrefix(String namespaceUri, String suggestion, boolean requirePrefix) {
        if ("http://schemas.example.com/orders".equals(namespaceUri)) {
            return "ord";
        }
        return suggestion;
    }
}
  • بعد (التنفيذ المتوافق مع Java 21): 
    // In Java 21: Identical methods and logic; ONLY the import statement changes (".internal." removed)
import com.sun.xml.bind.marshaller.NamespacePrefixMapper;
public class CustomNamespaceMapper extends NamespacePrefixMapper {
    @Override
    public String getPreferredPrefix(String namespaceUri, String suggestion, boolean requirePrefix) {
        if ("http://schemas.example.com/orders".equals(namespaceUri)) {
            return "ord";
        }
        return suggestion;
    }
}
  • إعدادات التبعية المجمّعة (pom.xml): لتوفير هذه الفئة في وقت التشغيل، يمكنك تجميع مكتبات JAXB المستقلة داخل apiproxy/resources/java/ أو الإعلان عنها في pom.xml: 
    <dependencies>
    <!-- Standalone JAXB API for Java 21 -->
    <dependency>
        <groupId>jakarta.xml.bind</groupId>
        <artifactId>jakarta.xml.bind-api</artifactId>
        <version>2.3.3</version>
    </dependency>
    <!-- Standalone JAXB Runtime providing com.sun.xml.bind.marshaller.NamespacePrefixMapper -->
    <dependency>
        <groupId>org.glassfish.jaxb</groupId>
        <artifactId>jaxb-runtime</artifactId>
        <version>2.3.8</version>
    </dependency>
</dependencies>

الاستراتيجية 3 (أ): فترة التوقّف المخطط لها للصيانة (إعادة النشر في الموقع)

حالات الاستخدام: يُنصح بها للبيئات التي تتضمّن نوافذ صيانة تشغيلية مجدوَلة حيث يكون انقطاع الخدمة لفترة قصيرة مقبولاً.

الإجراء:

  1. تنسيق فترة صيانة مجدوَلة مع مستهلكي واجهة برمجة التطبيقات
  2. يُرجى ترقية مكوّنات Edge for Private Cloud إلى الإصدار 4.54.00 باتّباع دليل مسارات الترقية.
  3. انشر النسخة المُجمَّعة مسبقًا والمتوافقة مع الإصدار 4.54.00 من الخادم الوكيل لواجهة برمجة التطبيقات باستخدام واجهة مستخدم New Edge أو واجهة برمجة التطبيقات لإدارة Apigee (عمليات النشر).
  4. تحقَّق من تنفيذ وسيلة الشرح من خلال إرسال طلبات اختبار اصطناعية إلى معالِجات الرسائل وفحص السجلّات باستخدام أداة التتبُّع.
  5. أغلِق نافذة الصيانة وأعِد فتح الزيارات العامة.

الاستراتيجية 3 (ب): إنشاء بيئة جديدة (نقل البيانات بدون توقّف)

حالات الاستخدام: يُنصح بها لبيئات التشغيل الفعلي ذات المهام الحرجة التي تتطلب عدم توقّف التشغيل. استخدِم هذا الخيار عندما يتعذّر تحديث Java Callout لتعمل على Java 8 وJava 21 في الوقت نفسه.

آلية العمل: تتضمن هذه الاستراتيجية شراء بيئة جديدة واحدة أو أكثر حتى تتمكن من توصيل عُقد "معالج الرسائل" من إصدارات مختلفة بها. بعد ذلك، انشر الخوادم الوكيلة المتوافقة مع Java 8 في البيئة المرتبطة بمعالجات الرسائل 4.53.X والخوادم الوكيلة المتوافقة مع Java 21 في البيئة المرتبطة بمعالجات الرسائل 4.54.00. بعد ذلك، استخدِم جهاز موازنة الحمل أو أساليب توجيه أخرى لتوجيه الزيارات إلى الخادم الوكيل المتوافق مع Java 21 فقط.

بالنسبة إلى هذه الاستراتيجية، يُعدّ فهم كيفية تفاعل المؤسسات والبيئات ومعالِجات الرسائل أمرًا أساسيًا لعملية نقل البيانات بدون توقّف (لمزيد من المعلومات، يُرجى الاطّلاع على بنية مؤسسة Apigee Edge):

  • مؤسسة Apigee هي حدود إدارية ذات مستوى أعلى تحتوي على بيئات متعددة (مثل prod وtest).
  • يتم نشر نسخة من وكيل واجهة برمجة التطبيقات في بيئة معيّنة. يتم تحميل نسخة الوكيل وتنفيذها فقط من خلال معالجات الرسائل المرتبطة صراحةً بتلك البيئة.
+------------------------------------------------------------------------+
|                          Apigee Organization                           |
|                                                                        |
|  Existing Environment (prod)            Temporary Env (prod-migration) |
|  +--------------------------------+     +----------------------------+ |
|  | Current 4.53.01 MP Nodes       |     | New 4.54.00 MP Nodes       | |
|  |               |                |     |              |             | |
|  | Proxy Rev N (4.53.01)          |     | Proxy Rev N+1 (Modernized) | |
|  +--------------------------------+     +----------------------------+ |
+------------------------------------------------------------------------+
                   ^                                    ^
                   | Step 1: Normal Live                | Step 2: Canary
                   |         Traffic (prod)             | Step 3: Complete
          +------------------------------------------------------+
          |       Upstream Load Balancer / Ingress Router        |
          +------------------------------------------------------+

الإجراء:

  1. إنشاء بيئة مؤقتة: أنشئ بيئة جديدة (على سبيل المثال، prod-migration) داخل مؤسستك (باتّباع إعداد المضيفين والبيئات الافتراضية) باستخدام مضيف افتراضي ومنفذ مخصّصَين.
  2. توفير عُقد معالج الرسائل في الإصدار 4.54.00: ثبِّت الإصدار 4.54.00 من Edge for Private Cloud على مثيلات أجهزة افتراضية جديدة أو مؤقتة واربط هذه العُقد بـ prod-migration (يُرجى الاطّلاع على إضافة معالج رسائل).
  3. تحديد الخوادم الوكيلة المتأثرة وإنشاء نُسخ محدَّثة: حدِّد الخوادم الوكيلة لواجهة برمجة التطبيقات التي تستخدم Java Callouts (باستخدام أداة رصد التغييرات) وأنشئ نسخة جديدة من كل خادم وكيل متأثر باستخدام Java Callouts المتوافقة مع الإصدار 4.54.00 من Edge for Private Cloud (بتطبيق الاستراتيجية 1 أو الاستراتيجية 2).
  4. نشر نُسخ الوكيل المعدَّلة في البيئة المؤقتة: انشر نُسخ الوكيل المعدَّلة والمتوافقة حصريًا في prod-migration.
  5. التحقّق من الزيارات ونقلها: يمكنك إجراء اختبارات تحقّق اصطناعية على المضيف الافتراضي الجديد. بعد إثبات الملكية، اضبط جهاز موازنة الحمل الخارجي (F5 أو NGINX) لإعادة توجيه زيارات العملاء من prod إلى prod-migration.
  6. ترقية العُقد الأصلية والعودة إليها: يمكنك إلغاء نشر الخوادم الوكيلة القديمة من prod. يمكنك ترقية عُقد معالج الرسائل الأصلية إلى الإصدار 4.54.00 باتّباع دليل مسارات الترقية. نشر نُسخ الخادم الوكيل المحدَّثة في "prod"، وإعادة توجيه عدد زيارات جهاز موازنة الحمل إلى "prod"، والتحقّق من العملية
  7. إيقاف البيئة المؤقتة: يمكنك إلغاء نشر الخوادم الوكيلة من prod-migration وإزالة عُقد معالج الرسائل المؤقتة وحذف البيئة المؤقتة.

الاستراتيجية 3ج: وضع المكتبات الخارجية على مستوى العقدة (المكتبات الاحتياطية المشتركة)

حالات الاستخدام: يُنصح بهذا الخيار عندما يكون لديك عدة خوادم وكيلة لواجهة برمجة التطبيقات تعتمد على فئات Java التي تمت إزالتها في Java 21، وتكون إعادة تجميع كل حزمة خادم وكيل فردي أو إعادة حزمها قبل الترقية غير ممكنة من الناحية التشغيلية.

طريقة العمل: في الإصدار 4.54.00 من Edge for Private Cloud، توفّر معالجات الرسائل آلية لتحميل فئات Java غير المتوفّرة من دليل عقدة مخصّص: $APIGEE_ROOT/data/edge-message-processor/external-lib.

عند تفعيل هذه الآلية، يتحقّق "معالج الرسائل" من هذا الدليل بحثًا عن الفئات غير المتوفّرة قبل الرجوع إلى الحلّ التلقائي. يمكنك توفير الفئات الناقصة من خلال الحصول عليها من ملفات JAR لمكتبات تابعة لجهات خارجية أو من خلال تجميع الفئات المطلوبة في ملف JAR ووضعه في external-lib.

الإجراء:

  1. أنشئ دليل المكتبة الخارجية على كل عقدة من عقد "معالج الرسائل": 
    mkdir -p /opt/apigee/data/edge-message-processor/external-lib
  2. ضع ملفات JAR المطلوبة في الدليل: انسخ ملفات JAR التي تحتوي على الفئات المطلوبة في /opt/apigee/data/edge-message-processor/external-lib.
  3. ضبط أذونات الملفات المناسبة: تأكَّد من أنّ مستخدم خدمة apigee لديه أذونات بالقراءة: 
    chown -R apigee:apigee /opt/apigee/data/edge-message-processor/external-lib
chmod 755 /opt/apigee/data/edge-message-processor/external-lib
chmod 644 /opt/apigee/data/edge-message-processor/external-lib/*.jar
  4. تفعيل تحميل الحِزم الخارجية في إعدادات "معالج الرسائل": في الإصدار 4.54.00 من Edge for Private Cloud، يكون تحميل الحِزم الخارجية المسموح بها غير مفعَّل تلقائيًا (conf_system_java.21.enable.external.allowed.packages=false). للسماح لـ "معالج الرسائل" بحلّ الفئات وتحميلها من /opt/apigee/data/edge-message-processor/external-lib، يجب تفعيل هذه السمة في /opt/apigee/customer/application/message-processor.properties باستخدام الرمز مع الإعدادات (CwC): 
    conf_system_java.21.enable.external.allowed.packages=true
  5. أعِد تشغيل معالج الرسائل: 
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

الاستراتيجية 4: علامات JVM‏ (--add-opens / --add-exports — يجب توخي الحذر واستخدامها كحل أخير)

حالات الاستخدام: استخدِم هذه الاستراتيجية كحلّ أخير لمكتبات المورّدين الخارجيين ذات المصدر المغلق التي لا يتوفّر فيها رمز المصدر، ولم يُصدر المورّدون تحديثات Java 21، ويعتمد ملف JAR بشكل صارم على الوصول الانعكاسي إلى حزم Java الداخلية.

الإجراء:

  1. تحديد الحزمة غير المتاحة المستخدَمة للانعكاس: حدِّد وحدة Java الداخلية والحزمة التي تصل إليها مكتبة الجهة الخارجية بشكل انعكاسي. ملاحظة: تحدث أخطاء الانعكاس هذه فقط في Java 21 في Edge for Private Cloud 4.54.00 ولن تظهر في سجلّات الإصدار 4.53.x. تحقَّق من سجلّات "معالج الرسائل" (/opt/apigee/var/log/edge-message-processor/system.log) بعد الترقية بحثًا عن InaccessibleObjectException لتحديد الوحدة والحزمة المطلوبَين: 
    java.lang.reflect.InaccessibleObjectException: Unable to make field private final byte[] java.lang.String.value accessible: module java.base does not "opens java.lang" to unnamed module
  2. عدِّل /opt/apigee/customer/application/message-processor.properties باستخدام الرمز مع الإعدادات (CwC) (أنشئ الملف إذا لم يكن متوفّرًا).
  3. أضِف علامات --add-opens أو --add-exports المستهدَفة إلى bin_setenv_ext_jvm_opts. 
    # Configure targeted JVM module access for closed-source legacy callouts (enclosed in double quotes)
bin_setenv_ext_jvm_opts="-XX:+UseG1GC -XX:+AlwaysPreTouch --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/sun.misc=ALL-UNNAMED --add-opens java.base/sun.security.util=ALL-UNNAMED --add-opens java.base/sun.security.x509=ALL-UNNAMED"
  4. تأكَّد من ملكية الملفات والأذونات المناسبة: 
    chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
chmod 644 /opt/apigee/customer/application/message-processor.properties
  5. أعِد تشغيل "معالج الرسائل" باستخدام apigee-service: 
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

التغييرات في بروتوكول أمان طبقة النقل (TLS) ومجموعة الرموز

في الإصدار 4.54.00 من Edge for Private Cloud، تم تحديث مكوّنات المنصة الأساسية، بما في ذلك معالج الرسائل وخادم الإدارة والموجّه، لتعمل على Java 21 LTS. يحدّث هذا التعديل أمان التشفير من خلال تفعيل الإصدار 1.3 من بروتوكول أمان طبقة النقل (TLS) تلقائيًا (JEP 332). تتفاوض معالجات الرسائل الآن على بروتوكول أمان طبقة النقل (TLS) الإصدار 1.3 باعتباره البروتوكول المفضّل لاتصالات الخلفية الصادرة، مع الرجوع إلى بروتوكول أمان طبقة النقل (TLS) الإصدار 1.2 في حال عدم توافق الخلفية معه.

متطلبات الخلفية القديمة والمعالجة

يعدّل الأساس المرجعي لتشفير Java 21 قائمة البروتوكولات ومجموعات الرموز غير المفعّلة تلقائيًا في jdk.tls.disabledAlgorithms (مثل بروتوكولات TLS القديمة ومجموعات تبادل مفاتيح RSA الثابتة التي لا تتضمّن سرية مفاتيح الجلسات المستقبلية: TLS_RSA_*). وبما أنّك توفّر بيئة التشغيل Java 21 الخاصة بك، تعتمد القائمة الدقيقة للبروتوكولات ومجموعات الرموز غير المفعّلة على عملية تنفيذ Java 21 المحدّدة.

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

  • تحديث أمان الخلفية (إجراء يُنصح به): يمكنك ترقية الخوادم المستهدفة وأجهزة موازنة الحمل لتتوافق مع الإصدار 1.2 أو 1.3 من بروتوكول أمان طبقة النقل (TLS) مع مجموعات رموز ECDHE الحديثة. لضبط البروتوكولات ومجموعات الرموز في الخوادم الوكيلة لواجهة برمجة التطبيقات، يُرجى الاطّلاع على ضبط بروتوكول أمان طبقة النقل (TLS) من Edge إلى الخلفية ومرجع ضبط TargetEndpoint لبروتوكول أمان طبقة النقل (TLS)/طبقة المقابس الآمنة (SSL) (أو موازنة الحمل على مستوى خوادم الخلفية في حال استخدام TargetServers).
  • إعادة تفعيل الخوارزميات القديمة باستخدام CwC (إجراء انتقالي أثناء الترقية): إذا تعذّر إكمال ترقيات الخلفية قبل ترقية المنصة، يمكنك إعادة تفعيل الخوارزميات المطلوبة مؤقتًا باستخدام الرمز مع الإعدادات (CwC):
    1. تحقَّق من قيمة jdk.tls.disabledAlgorithms التلقائية في تثبيت Java 21 (على سبيل المثال، في $JAVA_HOME/conf/security/java.security).
    2. تجاوز conf_jvmsecurity_jdk.tls.disabledAlgorithms في /opt/apigee/customer/application/message-processor.properties باستخدام قائمة الخوارزميات غير المفعَّلة نفسها، مع إزالة الإدخال TLS_RSA_* فقط (يجب الإبقاء على جميع الخوارزميات الأخرى غير المفعَّلة كما هي لكي تظلّ إجراءات الحماية المتبقية مفعَّلة).
    3. أعِد تشغيل "معالج الرسائل" باستخدام apigee-service. يمكنك إزالة هذا التجاوز بعد أن تتيح الخلفية مجموعات رموز ECDHE.
  • تعديل القائمة المسموح بها لمجموعة الرموز المخصّصة: إذا سبق لك إلغاء conf_http_HTTPTransport.ssl.cipher.suites.whitelist، يُرجى مراجعتها قبل الترقية. لم يعُد Java 21 متوافقًا مع مجموعات RSA الثابتة (TLS_RSA_*)، لذا فإنّ القائمة المسموح بها التي تحتوي على هذه المجموعات فقط تترك "معالج الرسائل" بدون رمز قابل للاستخدام وتتعذّر طلبات الخلفية مع ظهور الخطأ no cipher suites in common. يُرجى إزالة إدخالات TLS_RSA_* وضبط مجموعات الرموز الحديثة المتوافقة مع إصدار Java 21. إذا لم تكن قد تجاوزت هذه السمة، فإنّ الإعدادات التلقائية للإصدار 4.54.00 تتضمّن المجموعات المتوافقة ولا حاجة إلى إجراء أي تغيير.
  • تعديل رموز "الموجّه" الداخلي إلى "معالج الرسائل": إذا سبق لك إلغاء conf_message-processor-communication_local.http.ssl.ciphers باستخدام مجموعات رموز RSA الثابتة، عليك تعديلها باستخدام مجموعات رموز حديثة متوافقة مع تنفيذ Java 21 قبل الترقية، وإلا لن يتمكّن "الموجّه" من إكمال تأكيد اتصال بروتوكول أمان طبقة النقل (TLS) مع "معالج الرسائل". بعد ذلك، أعِد تشغيل معالج الرسائل: 
    apigee-service edge-message-processor restart
     يُرجى الاطّلاع على ضبط بروتوكول أمان طبقة النقل (TLS) بين جهاز توجيه ومعالج رسائل.

لمعرفة التفاصيل حول ضبط بروتوكول أمان طبقة النقل (TLS) بين مكوّنات Edge، يُرجى الاطّلاع على ضبط بروتوكول أمان طبقة النقل (TLS) بين جهاز توجيه ومعالج رسائل.

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

توفّر Apigee أداة لرصد التغييرات من أجل فحص مجموعتك بحثًا عن الخوادم الوكيلة لواجهة برمجة التطبيقات والسياسات والمسارات المشتركة وملفات JAR للموارد التي تم نشرها والتي قد تتأثر بالترقية إلى Edge for Private Cloud 4.54.00.

تحدّد الأداة العوائق المحتملة التي قد تحول دون الترقية، بما في ذلك المكتبات غير المتوافقة مع Java 21، وواجهات برمجة التطبيقات الداخلية المغلّفة بإحكام، والسياسات القديمة التي تم إيقافها نهائيًا، وحدود RDN في OpenLDAP، وتُنشئ تقارير قابلة للاستخدام لمساعدتك في اختيار استراتيجيات المعالجة المناسبة.

للاطّلاع على المتطلبات الأساسية الكاملة وتعليمات التنزيل وبنية سطر الأوامر ونماذج التقارير، يُرجى مراجعة دليل أداة رصد التغييرات المخصّص.