التغييرات في Edge for Private Cloud 4.53.01

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

يتضمّن الإصدار 4.53.01 من Edge for Private Cloud العديد من التغييرات التي تعزّز مستوى أمان المنصة ويتضمّن إصدارات محدّثة من البرامج والمكتبات المطلوبة. تؤثّر هذه التغييرات في أنواع السياسات التالية:

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

وصف تفصيلي للتغييرات

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

سياسة التحقّق من صحة OAS (مواصفات OpenAPI)

السياق

تتحقّق سياسة التحقّق من صحة OAS من صحة الطلبات أو الردود الواردة استنادًا إلى القواعد المحدّدة في مواصفات OpenAPI 3.0 (JSON أو YAML). يوفّر الإصدار 4.53.01 من Edge for Private Cloud تحسينات على سياسة OAS (مواصفات OpenAPI)، مع التركيز على التحقّق الأكثر صرامة ودقة من نص الردود من واجهة برمجة التطبيقات.

التغييرات

يقدّم الإصدار 4.53.01 من Edge for Private Cloud تغييرَين مهمَّين في طريقة تحقّق سياسة OAS من صحة استجابات واجهة برمجة التطبيقات، ما يضمن توافقًا أكبر مع مواصفات OpenAPI:

  • السيناريو 1:
    • السلوك السابق: إذا كانت مواصفات OpenAPI تتطلّب نص استجابة ولكن الاستجابة الفعلية من السياسة المستهدَفة أو المصدر لم تتضمّن نصًا، لن تصنّف السياسة ذلك على أنّه خطأ في التحقّق من الصحة.
    • السلوك الحالي: ستعرض السياسة الآن بشكل صحيح خطأ في التحقّق من الصحة (مثال: defines a response schema but no response body found) في هذا السيناريو، ما يشير إلى عدم تطابق بين الاستجابة المتوقّعة والفعلية.
  • السيناريو 2:
    • السلوك السابق: إذا كانت مواصفات OpenAPI تنصّ صراحةً على أنّه لا يُتوقّع أي نص استجابة، ولكن الاستجابة الفعلية من السياسة المستهدَفة أو المصدرية تتضمّن نصًا، لن تؤدي السياسة إلى حدوث خطأ.
    • السلوك الحالي: ستؤدي السياسة الآن إلى حدوث خطأ (مثلاً: No response body is expected but one was found) في هذا السيناريو، ما يضمن الالتزام الصارم بالمخطط المحدّد في الردود.

التخفيف من حدة المشكلة

حدِّد أي خوادم وكيل أو تدفّقات مشتركة قد تتأثر بالترقية باستخدام أداة رصد التغييرات أو من خلال المراجعة اليدوية. ابحث عن أي وكلاء تتوفر فيهم أي من الحالتين التاليتين:

  • تم ضبط سياسة التحقّق من صحة OAS باستخدام علامة Source تم ضبطها على response.
  • تتحقّق سياسة "التحقّق من صحة مواصفات OpenAPI" من صحة الردّ من أي سياسة أخرى تنشئ ردًا.

في حال استخدام الأداة، سيتم إنشاء الناتج بالتنسيق التالي:

المؤسسة البيئة اسم العنصر نوع العنصر التغيير اسم السياسة نوع السياسة نوع التأثير حقل خاص بالتأثير يقين التأثير الوثائق
org2 dev proxy2 الوكيل 4 oas-validateresponse OASValidation oas_content_type_handling المصدر=calloutresponse متوسط سياسة التحقّق من صحة OAS
org1 prod proxy3 sharedflow 1 oas-spec-validation OASValidation oas_content_type_handling المصدر=الردّ متوسط سياسة التحقّق من صحة OAS

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

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

  • إذا كان ملف مواصفات OAS يحدّد نص استجابة، يجب أن تقدّم الاستجابة من السياسة المستهدَفة أو المصدرية نصًا دائمًا.
  • إذا لم يحدّد ملف مواصفات OAS نص ردّ، يجب ألا ترسل السياسة المستهدَفة أو سياسة المصدر نص ردّ.

عدِّل سياسة التحقّق من صحة مواصفات OpenAPI أو السلوك المستهدف حسب الحاجة قبل محاولة الترقية إلى Private Cloud 4.53.01. عليك التحقّق من صحة سير العمل المحدَّدة هذه في بيئات غير إنتاجية أولاً للحدّ من مخاطر حدوث انقطاعات أثناء ترقية مجموعة الإنتاج.

مسار JSON

السياق

أدخلت الإصدار 4.53.01 من Edge for Private Cloud تغييرات على طريقة استخدام تعبيرات مسار JSON في السياسات المختلفة. يمكن استخدام تعبيرات JSONPath في سياسات مثل سياسة ExtractVariable وسياسة RegularExpressionProtection وإخفاء البيانات لتحليل محتوى JSON أو تخزين القيم في متغيرات. يمكن أيضًا استخدام تعبيرات JSONPath في نماذج الرسائل العامة لاستبدال المتغيرات بالقيم بشكل ديناميكي أثناء تنفيذ الخادم الوكيل. تتّبع تعبيرات JSONPath وتنسيقاتها الجديدة أحدث معايير تعبيرات JSON.

التغييرات

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

يتم استخدام إدخال json أدناه لشرح التغييرات:

{
  "store": {
    "book": [
      {"category": "reference", "author": "Nigel Rees", "price": 8.95},
      {"category": "fiction", "author": "Evelyn Waugh", "price": 12.99},
      {"category": "fiction", "author": "Herman Melville", "price": 8.99}
    ],
    "bicycle": {
      "color": "red",
      "book": [
        {"author": "Abc"}
      ]
    }
  }
}
  1. تغيير في سلوك حرف البدل [*] في JSONPath لقيم العناصر

    تم تغيير سلوك حرف البدل [*] عند استخدامه للوصول إلى جميع القيم المباشرة لعنصر JSON. في السابق، كانت الدالة $.object[*] تعرض القيم المباشرة مضمّنة في عنصر JSON واحد. باستخدام المكتبات المعدَّلة، أصبح الناتج الآن عبارة عن مصفوفة تحتوي على هذه القيم.

    على سبيل المثال، $.store[*]:

    السلوك السابق: 
    {
  "bicycle": {
    "color": "red",
    "book": [{"author": "Abc"}]
  },
  "book": [
    {"price": 8.95, "category": "reference", "author": "Nigel Rees"},
    {"price": 12.99, "category": "fiction", "author": "Evelyn Waugh"},
    {"price": 8.99, "category": "fiction", "author": "Herman Melville"}
  ]
}
    آلية العمل الحالية: 
    [
  [
    {"category": "reference", "author": "Nigel Rees", "price": 8.95},
    {"category": "fiction", "author": "Evelyn Waugh", "price": 12.99},
    {"category": "fiction", "author": "Herman Melville", "price": 8.99}
  ],
  {
    "color": "red",
    "book": [{"author": "Abc"}]
  }
]
    الإجراء:

    غيِّر تعبير JSONPath لاستهداف العنصر الرئيسي فقط (مثال: $.store) لاستهداف العناصر التي تم استردادها سابقًا بشكل مباشر.

  2. تتسبب النقطة الأخيرة (.) في مسارات JSONPath في حدوث خطأ

    يتم التحقّق من صحة تعبيرات JSONPath بشكل أكثر صرامة. في السابق، كان يتم تجاهل المسارات التي تنتهي بنقطة لاحقة غير صالحة (مثال: $.path.to.element.) بدون إشعار، وكان طلب البحث يعرض نتيجة إذا كان جزء المسار الصالح السابق يتطابق مع طلب البحث. باستخدام الإصدار الجديد، يتم الآن تحديد هذه المسارات غير الصالحة بشكل صحيح، وسيؤدي ذلك إلى حدوث خطأ.

    على سبيل المثال، $.store.book.

    السلوك السابق: 
    [
  {"price":8.95,"category":"reference","author":"Nigel Rees"},
  {"price":12.99,"category":"fiction","author":"Evelyn Waugh"},
  {"price":8.99,"category":"fiction","author":"Herman Melville"}
]
    آلية العمل الحالية: 
    ERROR: com.jayway.jsonpath.InvalidPathException - Path must not end with a '.' or '..'

    ستتعذّر الآن أي سياسات حالية تستخدم تعبيرات JSONPath مع نقطة لاحقة غير مقصودة مع ظهور الخطأ InvalidPathException.

    الإجراء:

    أزِل النقطة الأخيرة من أي تعبير JSONPath ينتهي بنقطة. على سبيل المثال، غيِّر $.store.book. إلى $.store.book.

  3. تغيير في بنية إخراج (..) لعملية البحث المتكرّر في JSONPath

    هناك تغييرات في طريقة عرض النتائج عند استخدام عامل التشغيل (..) (النزول المتكرر) لتحديد جميع مواضع عنصر مسمّى. في السابق، كانت تتم تسوية جميع العناصر التي تم العثور عليها في قائمة واحدة. تعرض المكتبات المعدَّلة الآن قائمة بالقوائم، مع الحفاظ على بنية التجميع الأصلية التي تم العثور فيها على العناصر، بدلاً من قائمة مسطّحة واحدة.

    على سبيل المثال، $..book

    السلوك السابق: 
    [
  {"price":8.95,"category":"reference","author":"Nigel Rees"},
  {"price":12.99,"category":"fiction","author":"Evelyn Waugh"},
  {"price":8.99,"category":"fiction","author":"Herman Melville"},
  {"author":"Abc"}
]
    آلية العمل الحالية: 
    [
  [
    {"category":"reference","author":"Nigel Rees","price":8.95},
    {"category":"fiction","author":"Evelyn Waugh","price":12.99},
    {"category":"fiction","author":"Herman Melville","price":8.99}
  ],
  [
    {"author":"Abc"}
  ]
]
    الإجراء:

    عدِّل منطق المعالجة النهائية ليراعي بنية المصفوفة المتداخلة الجديدة. من المحتمل أنّك ستحتاج إلى تكرار JSONArray الخارجي ثم تكرار كل JSONArray داخلي للوصول إلى العناصر الفردية.

  4. فهرسة JSONPath بعد اختيار عناصر متعددة أو فلتر يعرض مصفوفة فارغة

    هناك تغيير في السلوك عند تطبيق فهرس (مثال: [0]) مباشرةً بعد أداة اختيار عناصر متعدّدة (مثل [*]) أو فلتر ([?(condition)]). في السابق، كانت هذه التعبيرات تحاول اختيار العنصر في الفهرس المحدّد من النتائج المدمَجة. باستخدام الإصدار الجديد، ستعرض هذه التعبيرات الآن مصفوفة فارغة ([]).

    على سبيل المثال، $.store.book[*][0]

    السلوك السابق: 
    {"category": "reference", "price": 8.95, "author": "Nigel Rees"}
    آلية العمل الحالية: 
    []
    الإجراء:

    إذا كانت هناك حاجة إلى فلترة مجموعة ثم الحصول على عنصر معيّن من المجموعة التي تمّت فلترتها، يمكنك معالجة المصفوفة التي تمّت فلترتها والتي تمّ إرجاعها بواسطة JSONPath، على سبيل المثال $..book[?(@.category == 'fiction')]، ثمّ الحصول على [0] من النتيجة السابقة.

  5. تغيير في إخراج تقسيم المصفوفة السلبي في JSONPath

    عدّلت النسخة الجديدة سلوك تقسيم المصفوفات السلبي (مثال: [-2:], [-1:]). في السابق، عند تطبيق تقسيم سلبي على مصفوفة (يشير إلى عناصر من نهاية المصفوفة)، كانت النسخة القديمة تعرض بشكل غير صحيح عنصرًا واحدًا فقط من هذا التقسيم. يعرض الإصدار الجديد الآن بشكل صحيح قائمة (مصفوفة) تحتوي على جميع العناصر التي تقع ضمن النطاق السلبي المحدّد.

    على سبيل المثال $.store.book[-2:]

    السلوك السابق: 
    {"price":12.99,"category":"fiction","author":"Evelyn Waugh"}
    آلية العمل الحالية: 
    [
  {"category":"fiction","author":"Evelyn Waugh","price":12.99},
  {"category":"fiction","author":"Herman Melville","price":8.99}
]
    الإجراء:

    يجب الآن تعديل منطق المعالجة النهائية لتكرار مصفوفة JSON التي تم إرجاعها للحصول على الناتج المطلوب.

  6. نقطة سابقة أكثر صرامة في JSONPath

    يتم تطبيق قواعد أكثر صرامة على صيغة العناصر التي يتم الوصول إليها مباشرةً من الجذر. عند الوصول إلى العناصر مباشرةً من الجذر بدون نقطة سابقة (مثال: $propertyelement)، يتم الآن اعتبار هذه البنية خطأً وستمنع نشر الخادم الوكيل.

    على سبيل المثال $store،

    {
  "bicycle": {
    "color": "red",
    "book": [{"author": "Abc"}]
  },
  "book": [
    {"price": 8.95, "category": "reference", "author": "Nigel Rees"},
    {"price": 12.99, "category": "fiction", "author": "Evelyn Waugh"},
    {"price": 8.99, "category": "fiction", "author": "Herman Melville"}
  ]
}

    آلية العمل الحالية:

    Proxy will fail to deploy.

    الإجراء:

    غيِّر JSONPath لتضمين النقطة: $.propertyName (مثال: $.store). سيؤدي ذلك إلى استهداف القيمة واستردادها بشكلٍ صحيح.

  7. تعبيرات JSONPath الديناميكية

    انتبه جيدًا إلى السياسات التي يتم فيها توفير تعبير JSONPath نفسه من خلال متغيّر (مثال: {myJsonPathVariable} أو {dynamicPath}). يجب أيضًا التحقّق من قيمة هذه المتغيّرات مقارنةً بالتغييرات المحتملة في السلوك الموضّحة أعلاه.

التخفيف من حدة المشكلة

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

المؤسسة البيئة اسم العنصر نوع العنصر التغيير اسم السياسة نوع السياسة نوع التأثير حقل خاص بالتأثير يقين التأثير الوثائق
org1 dev proxy1 الوكيل 4 EV-ExtractRequestParams ExtractVariables تغيير في سلوك حرف البدل [*] في JSONPath لقيم الكائنات $.store[*] مرتفع تغيير في سلوك حرف البدل [*] في JSONPath لقيم الكائنات
org2 prod proxy2 sharedflow 1 EV-ExtractResponseParams ExtractVariables النقطة اللاحقة (.) في مسارات JSONPath تؤدي الآن إلى حدوث خطأ $.store.book. مرتفع تتسبب النقطة الأخيرة في مسارات JSONPath في حدوث خطأ
org3 dev proxy3 الوكيل 3 SC-FetchUserProfile ServiceCallout تغيير بنية إخراج "النزول المتكرر" في JSONPath (..) $..book مرتفع تغيير بنية إخراج البحث المتكرر (..) في JSONPath
org4 prod proxy4 sharedflow 2 RF-InvalidAuthToken RaiseFault فهرسة JSONPath بعد اختيار عناصر متعددة أو فلتر تعرض الآن مصفوفة فارغة $.store.book[*][0] مرتفع فهرسة JSONPath بعد اختيار عناصر متعددة أو فلتر يعرض مصفوفة فارغة
org5 اختبار proxy5 الوكيل 6 SC-FetchProfileDetails ServiceCallout تغيير في ناتج تقسيم مصفوفة JSONPath السلبي $.store.book[-2:] مرتفع تغيير في إخراج تقسيم المصفوفة السلبي في JSONPath
org6 prod proxy6 الوكيل 2 ML-LogRequestDetails MessageLogging نقطة سابقة أكثر صرامة في JSONPath $store مرتفع نقطة سابقة أكثر صرامة في JSONPath
org7 اختبار proxy7 الوكيل 5 RF-InvalidTokenDetails RaiseFault تعبيرات JSONPath الديناميكية myJsonPathVariable متوسط تعبيرات JSONPath الديناميكية

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

وللحدّ من ذلك، يجب وضع استراتيجية شاملة. تتضمّن هذه العملية تحديد مسار التعديل المناسب وتطبيق الإصلاح اللازم لتعبيرات JSONPath التي تم رصدها.

اختَر طريقة ترقية النظام الأنسب لك:

  • Zero Downtime Migration

    تتضمّن هذه الاستراتيجية توفير بيئة جديدة واحدة أو أكثر لتتمكّن من ربط عُقد معالجة الرسائل المنفصلة بها. يمكن ضبط عُقد معالجة الرسائل هذه لتثبيت الإصدار 4.53.01 واستخدام وكلاء مع تعبيرات JSONPath الحديثة. ويمكن استخدامها أثناء الترقية وإيقافها نهائيًا بعد اكتمالها. هذه الاستراتيجية سلسة ولكنّها تتضمّن توفير عُقد إضافية لمعالجة الرسائل بشكل مؤقت من أجل إتاحة الترقية بسلاسة. يمكنك الاطّلاع على التفاصيل أدناه:

    • أنشئ بيئة جديدة وأضِف عُقد معالجة رسائل جديدة من الإصدار 4.53.01 إلى هذه البيئة الجديدة.
    • حمِّل حزمة الوكيل للوكلاء المتأثّرين إلى البيئة الجديدة وطبِّق الإصلاحات اللازمة الموضّحة في قسم الإصلاح، ثمّ وزِّع حزمة الوكيل المعدَّلة على البيئة الجديدة.
    • أعِد توجيه الزيارات إلى البيئة الجديدة وألغِ نشر الخوادم الوكيلة المتأثرة من البيئة القديمة.
    • ترقية عُقد معالج الرسائل الأصلية إلى الإصدار 4.53.01 نشر خوادم وكيلة تتضمّن إصلاحات لـ JSONPath في البيئة الأصلية
    • أعِد توجيه حركة البيانات إلى البيئة القديمة التي تتضمّن الآن معالِجات الرسائل بالإصدار 4.53.01 ووكيلًا تم تحديثه ليتوافق مع تعبيرات jsonpath الجديدة.
    • احذف البيئة الجديدة والعُقد المرتبطة بها وأوقِفها نهائيًا.
  • وقت الاستراحة والترقية

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

    • حدِّد الخوادم الوكيلة المتأثرة بالسياسات المتأثرة وأنشئ مراجعة جديدة لجميع الخوادم الوكيلة المتأثرة.
    • طبِّق الإصلاحات اللازمة من خلال تنفيذ الإصلاحات الموضّحة في قسم "الإجراءات العلاجية" في مراجعة جديدة للخادم الوكيل. لا تنشر هذا التغيير بعد.
    • احصل على وقت تعليق للوكيل/الوكلاء المتأثرين.
    • ترقية جميع معالِجات الرسائل إلى Edge للإصدار 4.53.01 من السحابة الخاصة يُرجى العِلم أنّ الخوادم الوكيلة الحالية قد لا تعمل على معالجات الرسائل التي تمّت ترقيتها حديثًا.
    • بعد ترقية جميع معالِجات الرسائل إلى الإصدار 4.53.01 من Edge للسحابة الخاصة، يمكنك نشر مراجعة الوكيل التي تم إنشاؤها حديثًا باستخدام تعبير JSONPath الثابت.
    • استئناف حركة الزيارات على هذه الخوادم الوكيلة
  • إعادة تصميم الخادم الوكيل قبل الترقية

    يمكنك إعادة تصميم الخادم الوكيل نفسه قبل الترقية إلى Edge for Private Cloud 4.53.01. بدلاً من الاعتماد على تعبيرات مسار JSON معيّنة، يمكنك الحصول على النتيجة نفسها باستخدام طريقة مختلفة.

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

تغييرات JavaCallout

السياق

كانت الإصدارات 4.53.00 والإصدارات الأقدم من Edge for Private Cloud تتضمّن دليلًا باسم deprecated ($APIGEE_ROOT/edge-message-processor/lib/deprecated) يحتوي على مجموعة من مكتبات JAR. كانت هذه المكتبات متاحة للاستخدام في رمز Java البرمجي في سياسة JavaCallout، وكان من الممكن أن يستخدمها رمز Java البرمجي المخصّص بشكل مباشر أو غير مباشر.

التغييرات

تمت الآن إزالة الدليل الذي تم إيقافه نهائيًا في Edge للإصدار 4.53.01 من السحابة الخاصة. في حال كان رمز Java يعتمد على هذه المكتبات، ستتعذّر الوكلاء الذين يستخدمون عمليات استدعاء Java هذه عند ترقية معالجات الرسائل إلى الإصدار 4.53.01. لتجنُّب حدوث مثل هذه الأعطال، اتّبِع خطوات التخفيف أدناه قبل ترقية معالجات الرسائل إلى الإصدار 4.53.01.

التخفيف من حدة المشكلة

  1. راجِع سياسات Java Callout وملفات JAR المرتبطة بها باستخدام أداة رصد التغييرات أو يدويًا. تحقَّق مما إذا كانت أي من السياسات تشير إلى مكتبات متوفرة في الدليل "deprecated" لمعالجات الرسائل الحالية.

    إذا كنت تستخدم الأداة التي توفّرها Apigee لعمليات الرصد المذكورة أعلاه، ستنشئ الأداة تقريرًا كما هو موضّح في الجدول التالي . على وجه التحديد، تستهدف هذه السياسة السياسات التي تشير إلى ملفات JAR في الدليل $APIGEE_ROOT/edge-message-processor/lib/deprecated للإصدارات القديمة من Edge for Private Cloud.

    ستنشئ الأداة تقارير بالتنسيق التالي:

    المؤسسة البيئة اسم العنصر نوع العنصر التغيير اسم السياسة نوع السياسة نوع التأثير حقل خاص بالتأثير يقين التأثير الوثائق
    org1 بدون بدون org-level-jar بدون بدون java-callout تم رصد مكتبة متوقّفة نهائيًا للحزمة simple-javacallout-o1-jar-1.jar [‎'Detected use of class org.apache.commons.io.FileUtils from commons-io-2.5.jar, ‎'Detected use of class org.apache.commons.io.input.XmlStreamReaderException from commons-io-2.5.jar‎'] مرتفع التغييرات في JavaCallout
    org3 env3 بدون env-level-jar بدون بدون java-callout تم رصد مكتبة متوقّفة نهائيًا للحزمة fat-javacallout-e3-jar-1.jar ['تم رصد استخدام الفئة org.apache.http.impl.auth.NTLMSchemeFactory من httpclient-4.5.2.jar'] مرتفع التغييرات في JavaCallout
    org1 env1 p1 proxy-level-jar 1 بدون java-callout تم رصد مكتبة متوقّفة نهائيًا للحزمة simple-javacallout-p1-jar-1.jar ['تم رصد استخدام الفئة org.apache.commons.lang3.builder.ToStringBuilder من commons-lang3-3.4.jar', 'تم رصد استخدام الفئة org.apache.commons.lang3.Validate من commons-lang3-3.4.jar'] مرتفع التغييرات في JavaCallout

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

  2. بعد تحديد هذه المكتبات المتوقّفة نهائيًا، يمكنك اتّباع إحدى الطرق أدناه للحدّ من المشكلة.
    • وضع الموارد (يُنصح به إذا كان لديك عدد قليل من ملفات JAR أو المكتبات من الدليل المتوقّف نهائيًا التي تشير إليها ملفات JAR الخاصة بـ Java-Callout)
      • حمِّل ملفات JAR التي تم تحديدها على أنّها متوقّفة نهائيًا كمورد على المستوى المطلوب: مراجعة خادم وكيل واجهة برمجة التطبيقات أو البيئة أو المؤسسة.
      • واصِل ترقية برامج Apigee كالمعتاد.
    • الموضع اليدوي (يُنصح به إذا كان لديك عدد كبير من ملفات JAR أو المكتبات التي تشير إليها ملفات JAR الخاصة بـ Java-Callout)
      • في كل عقدة لمعالجة الرسائل، أنشئ دليلاً جديدًا باسم external-lib في المسار $APIGEE_ROOT/data/edge-message-processor/.
      • انسخ ملفات JAR المحدّدة إلى دليل external-lib هذا من الدليل المتوقّف نهائيًا: cp $APIGEE_ROOT/edge-message-processor/lib/deprecated/some.jar $APIGEE_ROOT/data/edge-message-processor/external-lib/some.jar
      • تأكَّد من أنّ دليل ملفات JAR الأساسية يمكن قراءته من قِبل مستخدم Apigee: chown -R apigee:apigee $APIGEE_ROOT/data/edge-message-processor/external-lib
      • واصِل ترقية برامج Apigee كالمعتاد.

تغيير OpenLDAP

السياق

يمكن استخدام OpenLDAP في Edge Private Cloud للمصادقة والتفويض. في الإصدار 4.53.01 من Edge for Private Cloud، تمت ترقية برنامج OpenLDAP الذي توفّره Apigee من الإصدار 2.4 إلى الإصدار 2.6.

التغييرات

في OpenLDAP 2.6، يقتصر الاسم المميز النسبي (RDN) على 241 بايت/حرف تقريبًا. هذا الحدّ الأقصى إلزامي ولا يمكن تعديله.

التأثير
  • تحدث حالات تعذُّر النسخ المتماثل أو الاستيراد للإدخالات التي تحتوي على أسماء مميّزة نسبية كبيرة جدًا.
  • قد تؤدي محاولة إنشاء عناصر، مثل المؤسسات والبيئات والأدوار المخصّصة والأذونات وما إلى ذلك، إلى ظهور رسالة الخطأ: "message": "[LDAP: error code 80 - Other]".
  • سيتأثر أي اسم مميّز أطول من 241 بايت في LDAP من Apigee. ستمنع أسماء DN هذه ترقية برنامج Apigee OpenLDAP بنجاح، وسيكون عليك اتّباع استراتيجيات التخفيف من حدة المشاكل لهذه العناصر قبل المتابعة في عملية الترقية.

بشكل عام، في LDAP من Apigee، ترتبط الأسماء المميزة الطويلة بالأذونات لأنّها يتم إنشاؤها من خلال ربط عدة كيانات. وتكون إدخالات الأذونات هذه عرضة بشكل خاص لمشاكل الترقية.

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

dn: cn=@@@environments@@@*@@@applications@@@*@@@revisions@@@*@@@debugsessions,ou=resources,cn=businessuser,ou=userroles,o=orgname,ou=organizations,dc=apigee,dc=com

عادةً، يكون لديك أسماء مؤسسات وبيئات وأدوار بأطوال تؤدي إلى أن تكون أسماء RDN في LDAP أصغر من 241 بايت.

التخفيف من حدة المشكلة

قبل الترقية إلى الإصدار 4.53.01:

ستساعدك الخطوات التالية في التحقّق من توفّر أسماء مميّزة نسبية طويلة في مجموعة LDAP 2.4 الحالية.

الخطوة 1: استخراج بيانات LDAP

استخدِم الأمر ldapsearch للعثور على الاسم المميز (dn) وإعادة توجيه الناتج إلى ملف: 

ldapsearch -o ldif-wrap=no -b "dc=apigee,dc=com" -D "cn=manager,dc=apigee,dc=com" -H ldap://:10389 -LLL -x -w LDAP_PASSWORD dn > /tmp/DN.ldif

تأكَّد من أنّ ملف DN.ldif أعلاه يحتوي على إدخالات LDAP.

‫2- تحديد أسماء RDN الطويلة

تستخدِم أداة رصد التغييرات ملف LDIF تم إنشاؤه لتحديد أسماء RDN لبروتوكول LDAP التي تتجاوز 241 بايت/حرف.

ستنشئ الأداة تقارير بالتنسيق التالي:

المؤسسة البيئة اسم العنصر نوع العنصر التغيير اسم السياسة نوع السياسة نوع التأثير حقل خاص بالتأثير يقين التأثير الوثائق
بدون بدون cn=really-long-name,ou=userroles,o=edge-platform,ou=organizations,dc=apigee,dc=com ملف ldif بدون ما مِن قيمة بدون يتجاوز RDN في LDAP عدد الأحرف المسموح به وهو 241 حرفًا cn=really-long-name مرتفع تغيير OpenLDAP

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

إذا لم ينتج عن الأمر أعلاه أي ناتج، يعني ذلك أنّه لا تتجاوز أي أسماء مميزة نسبية في إعداد LDAP الحالي 241 بايت/حرف. يمكنك المتابعة وإجراء الترقية كالمعتاد.

إذا كان الأمر أعلاه ينتج عنه ناتج، يشير ذلك إلى توفّر أسماء مميّزة نسبية تتجاوز 241 بايت/حرف. بالنسبة إلى هذه العناصر، اتّبِع خطوات التخفيف من المخاطر كما هو موضّح في الخطوة 3 قبل المتابعة في ترقية Edge for Private Cloud 4.53.01.

‫3- التعامل مع أسماء الموارد المحددة الطويلة

إذا تم تلقّي الناتج من الخطوة رقم 2، يشير ذلك إلى توفّر أسماء مميّزة نسبية تتجاوز 241 بايت/حرفًا، ويجب اتّباع خطوات التخفيف أدناه:

راجِع إدخالات LDAP التي تتجاوز 241 بايت.

  • إذا كان اسم الدور المخصّص أو التطبيق أو منتج واجهة برمجة التطبيقات أو الكيانات الأخرى هو العامل الأساسي الذي يتسبّب في أن يكون اسم RDN طويلاً، يمكنك الانتقال إلى استخدام كيان بديل باسم أقصر.
  • إذا كان اسم المؤسسة أو اسم البيئة هو المساهم الأساسي في طول الاسم المميز النسبي، عليك نقل البيانات إلى مؤسسة أو بيئة أخرى باسم أقصر.

استمر في تكرار الخطوات أعلاه إلى أن لا يحتوي LDAP على أي أسماء مميزة نسبية أطول من 241 بايت. بعد الوصول إلى هذه الحالة، يمكنك مواصلة ترقية إصدار السحابة الخاصة كالمعتاد.

تغييرات موفّر التشفير

السياق

هذا التغيير هو نتيجة من الإصدار 4.53.00 من Edge for Private Cloud. في الإصدار 4.53.00 من Edge for Private Cloud، تم تعديل موفِّر التشفير الداخلي من Bouncy Castle (BC) إلى Bouncy Castle FIPS (BCFIPS) لإتاحة التوافق مع معيار FIPS.

التغييرات

إذا كانت سياسات JavaCallout تعتمد على استخدام موفّر BC الأصلي، خاصةً عند استخدام وظائف الأمان التي تم تحسينها في موفّر BCFIPS (على سبيل المثال، استخدام زوج مفاتيح مشترك لكل من التشفير والتوقيع)، يجب تحديث سياسات JavaCallout هذه. قد تتعذّر سياسات JavaCallout التي تحاول تحميل موفّر التشفير Bouncy Castle باستخدام الاسم BC لأنّ الموفّر التلقائي قد تغيّر. وقد تتعطّل هذه السياسات التي تستخدم موفِّر BC لاحقًا. لن يعود بإمكانك الوصول إلى أي عمليات تنفيذ مخصّصة تعتمد على موفّر BC القديم، وسيكون عليك مراجعتها وإعادة تنفيذها.

التخفيف من حدة المشكلة

الحل البديل المقترَح هو استخدام موفّر BCFIPS. يجب مراجعة عمليات تنفيذ JavaCallout المخصّصة التي كانت تعتمد على موفّر الخدمة القديم وإعادة تنفيذها باستخدام موفّر خدمة Bouncy Castle FIPS، الذي يمكن الوصول إليه باستخدام السلسلة "BCFIPS".

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

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

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

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

تشغيل الأداة

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

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

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

./change-detector --help

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

export APIGEE_PASSWORD=[your_password]
./change-detector --username [your_username] --mgmt-url [MGMT url]

لرصد إدخالات LDAP الكبيرة التي تتضمّن اسم مميّز نسبيًا، شغِّل الأمر التالي:

./change-detector --username [your_username] --mgmt-url [MGMT url] --ldif-file [LDIF_file]

تنشئ الأداة مخرجات بتنسيق json أو csv يمكن استخدامها مباشرةً أو استيرادها إلى أداة يمكن للمستخدمين العاديين قراءتها، مثل "جداول بيانات Google".

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

المؤسسة

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

البيئة

البيئة المحدّدة (مثل التطوير والاختبار والإنتاج) داخل المؤسسة بالنسبة إلى تغيير OpenLDAP، سيكون هذا الحقل None.

بالنسبة إلى تغييرات Java Callout، إذا كان Artifact Type=env-level-jar، سيكون هذا الحقل None.

اسم العنصر

يعرض هذا الحقل اسم الخادم الوكيل أو المسار المشترك. بالنسبة إلى تغيير OpenLDAP، يعرض هذا الحقل عنصر LDAP الخاص بـ RDN.

بالنسبة إلى تغييرات Java Callout، إذا كان Artifact Type=env-level-jar أو org-level-jar، سيكون هذا الحقل None.

نوع العنصر

  • بالنسبة إلى تغييرات OAS وJSON، يحدّد هذا العمود نوع العنصر أو الخادم الوكيل أو التدفق المشترك.
  • بالنسبة إلى تغيير Java Callout، يقدّم هذا العمود تفاصيل حول المكان أو المستوى الذي يتم فيه تحميل ملف jar المتأثر. يمكن تخزين المراجع (ملفات JAR) على أحد المستويات الثلاثة: org-level وenv-level وproxy-level.
  • بالنسبة إلى تغيير OpenLDAP، يشير هذا الحقل إلى ملف LDIF المستخدَم في الأداة.

التغيير

يشير إلى المراجعة التي تم نشرها للخادم الوكيل أو المسار المشترك المتأثر. بالنسبة إلى تغيير OpenLDAP، سيكون None.

اسم السياسة

اسم السياسة المحدّدة التي تم رصدها كمشكلة محتملة بالنسبة إلى تغيير OpenLDAP، سيكون None.

نوع السياسة

تشير هذه السمة إلى نوع السياسة. بالنسبة إلى تغيير OpenLDAP، سيكون None.

نوع التأثير

  • يصف هذا الحقل النوع المحدّد من التغيير الذي تم رصده في وكيل أو مسار مشترك.
  • بالنسبة إلى تغيير Java Callout، عند رصد تغييرات ذات صلة بـ java-callouts، تشير الأداة إلى java-callout المتأثر الذي يحتوي على مراجع إلى ملفات JAR المتوفرة في الدليل $APIGEE_ROOT/edge-message-processor/lib/deprecated من الإصدارات القديمة من Edge for Private Cloud بالطريقة التالية في هذا العمود تحديدًا.
    • deprecated library detected for NAME_OF_THE_AFFECTED_JAVA_CALLOUT_JAR
  • بالنسبة إلى تغيير OpenLDAP، يعرض هذا الحقل ما إذا كان RDN لأي كيان LDAP قد تجاوز 241 بايت أو حرفًا.

حقل التأثير المحدّد

  • بالنسبة إلى تغيير OAS، يكون هذا الحقل هو اسم المتغيّر المستخدَم في علامة المصدر الخاصة بالسياسة.
  • بالنسبة إلى تغيير JSON، يعرض هذا الحقل تعبير JSONPath أو العنصر الدقيق الذي تم الإبلاغ عنه كمشكلة محتملة.
  • بالنسبة إلى تغيير Java Callout، يحتوي هذا الحقل على تفاصيل الفئات الدقيقة واسم ملف JAR المقابل (الموجود في الدليل $APIGEE_ROOT/edge-message-processor/lib/deprecated في إصدارات Private Cloud القديمة) الذي يستخدمه/يشير إليه ملف JavaCallout jar المتأثر، ما سيؤدي إلى حدوث أخطاء عند الترقية إلى الإصدار 4.53.01 في حال عدم حلّ المشكلة.
    •  ['Detected use of class CLASS_NAME_1 from JAR_NAME_1',
    Detected use of class CLASS_NAME_2 from JAR_NAME_2', 
  .. , .. , ]
  • بالنسبة إلى تغيير OpenLDAP، يعرض هذا الحقل RDN لعنصر LDAP الذي تجاوز 241 بايت أو حرفًا.

مدى التأكّد من التأثير

  • يعرض هذا الحقل مستوى الدقة الذي رصدت به الأداة عنصرًا معيّنًا. يمكن أن تكون قيم هذا العمود عالية أو متوسطة (يمكن إضافة المزيد من القيم لاحقًا).

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

  • ستحمل عمليات الرصد المرتبطة بتغييرات JavaCallout وOpenLDAP دائمًا القيمة عالية في أعمدة صحة التأثير.

الوثائق

يوفّر هذا العمود رابطًا تشعّبيًا إلى مستندات Apigee (الأقسام ذات الصلة من هذه المقالة) التي تشرح المشكلة وخطوات التخفيف من حدّتها.