تغییرات در Edge for Private Cloud نسخه ۴.۵۳.۰۱

نمای کلی تغییرات

‫Edge for Private Cloud نسخه ۴.۵۳.۰۱ تغییرات متعددی را معرفی می‌کند که وضعیت امنیتی پلاتفرم را بهبود می‌بخشد و نسخه‌های به‌روزشده نرم‌افزار و کتابخانه‌های موردنیاز را دربرمی‌گیرد. این تغییرات بر انواع خط‌مشی زیر تأثیر می‌گذارد:

همچنین می‌توانید از ابزار تشخیص تغییر برای شناسایی تغییرات در پراکسی‌ها، جاری‌سازی‌های مشترک، یا دیگر آرتیفکت‌های موجود در خوشه‌تان که ممکن است درنتیجه این ارتقا باعث اختلال شوند استفاده کنید.

شرح مفصل تغییرات

این بخش تغییرات معرفی‌شده در نسخه ۴.۵۳.۰۱ را که می‌تواند درطول یا پس‌از ارتقا روند کار شما را مختل کند شرح می‌دهد. روش‌های شناسایی مناطق مشکل‌ساز احتمالی و روش‌های کاهش یا راه‌حل‌های موقت نیز پوشش داده می‌شود.

خط‌مشی اعتبارسنجی OAS (مشخصات OpenAPI)

زمینه

خط‌مشی اعتبارسنجی OAS درخواست‌ها یا پاسخ‌های ورودی را دربرابر قوانین تعریف‌شده در مشخصات OpenAPI 3.0 (JSON یا YAML) اعتبارسنجی می‌کند. ‫Edge for Private Cloud نسخه ۴.۵۳.۰۱ بهبودهایی را در خط‌مشی OAS (مشخصات OpenAPI) ارائه می‌دهد که بر اعتبارسنجی دقیق‌تر و سخت‌گیرانه‌تر بدنه‌های پاسخ API تمرکز دارد.

تغییرات

‫Edge for Private Cloud نسخه ۴.۵۳.۰۱ دو تغییر مهم در نحوه اعتبارسنجی پاسخ‌های API توسط خط‌مشی OAS معرفی می‌کند که باعث می‌شود با مشخصات OpenAPI شما هم‌راستایی بیشتری داشته باشد:

  • سناریو ۱:
    • عملکرد قبلی: اگر مشخصات OpenAPI شما به بدنه پاسخ نیاز داشت اما پاسخ واقعی از هدف یا خط‌مشی بالادستی شامل آن نبود، خط‌مشی این مورد را به‌عنوان خطای اعتبارسنجی پرچم‌گذاری نمی‌کرد.
    • عملکرد کنونی: خط‌مشی اکنون در این سناریو خطای اعتبارسنجی (مثال: defines a response schema but no response body found) را به‌درستی برمی‌گرداند و نشان می‌دهد که بین پاسخ موردانتظار و پاسخ واقعی عدم تطابق وجود دارد.
  • سناریو ۲:
    • عملکرد قبلی: اگر مشخصات OpenAPI شما به‌طور صریح بیان می‌کرد که هیچ بدنه پاسخی موردانتظار نیست، اما پاسخ واقعی از هدف یا خط‌مشی بالادستی شامل بدنه بود، خط‌مشی منجر به خطا نمی‌شد.
    • عملکرد کنونی: اکنون این خط‌مشی در این سناریو منجر به عدم موفقیت (مثلاً No response body is expected but one was found) می‌شود و تضمین می‌کند که پاسخ‌ها کاملاً از طرحواره مشخص‌شده پیروی کنند.

کاهش

بااستفاده از ابزار تشخیص تغییر یا ازطریق بررسی دستی، هرگونه پراکسی یا جاری‌سازی مشترکی را که ممکن است تحت تأثیر ارتقا قرار گیرد شناسایی کنید. هرگونه پراکسی را که یکی از شرایط زیر را داشته باشد پیدا کنید:

  • خط‌مشی «اعتبارسنجی OAS» با برچسب Source که روی response تنظیم شده است پیکربندی شده است.
  • خط‌مشی «اعتبارسنجی OAS» پاسخ‌های خط‌مشی‌های دیگر را که پاسخ تولید می‌کنند اعتبارسنجی می‌کند.

اگر از این ابزار استفاده کنید، برونداد را در قالب زیر تولید می‌کند:

سازمان محیط زیست نام آرتیفکت نوع آرتیفکت ویرایش نام خط‌مشی نوع خط‌مشی نوع تأثیر فیلد اختصاصی تأثیر قطعیت تأثیر اسناد
org2 dev proxy2 پراکسی 4 oas-validateresponse OASValidation oas_content_type_handling منبع=calloutresponse متوسط خط‌مشی تأیید OAS
org1 prod proxy3 جریان هم‌رسانی 1 oas-spec-validation OASValidation oas_content_type_handling منبع=پاسخ متوسط خط‌مشی تأیید OAS

برای توضیح دقیق ستون‌های جدول برونداد، به بخش درک برونداد ابزار مراجعه کنید.

پس‌از شناسایی جریان مشترک یا پراکسی، مطمئن شوید که پاسخ و مشخصات OAS شما ازنظر وجود یا عدم وجود بدنه پاسخ هماهنگ باشند. می‌توانید از ردیابی استاندارد Apigee برای بررسی الگوهای ترافیک خود استفاده کنید. اگر هدف به‌صورت متناوب پاسخ برمی‌گرداند، از خط‌مشی‌های دیگر برای اعتبارسنجی پاسخ قبل‌از اینکه پاسخ به خط‌مشی «اعتبارسنجی OAS» ارسال شود استفاده کنید.

  • اگر فایل مشخصات OAS شما بدنه پاسخ را تعریف می‌کند، پاسخ از خط‌مشی هدف یا بالادستی همیشه باید آن را ارائه دهد.
  • اگر فایل مشخصات OAS شما بدنه پاسخ را تعریف نمی‌کند، خط‌مشی هدف یا بالادستی نباید آن را ارسال کند.

قبل‌از تلاش برای ارتقا به Private Cloud 4.53.01، خط‌مشی اعتبارسنجی OAS یا رفتار هدف خود را درصورت نیاز به‌روز کنید. ابتدا باید چنین گردش‌های کاری شناسایی‌شده‌ای را در محیط‌های غیرتولیدی خود اعتبارسنجی کنید تا خطر اختلال درطول ارتقای خوشه تولید را به حداقل برسانید.

مسیر JSON

زمینه

‫Edge for Private Cloud نسخه 4.53.01 تغییراتی در نحوه استفاده از عبارات مسیر JSON در خط‌مشی‌های مختلف ایجاد کرده است. از عبارت‌های JSONPath می‌توان در خط‌مشی‌هایی مثل خط‌مشی ExtractVariable، خط‌مشی RegularExpressionProtection، پوشش داده برای تجزیه محتوای JSON یا ذخیره مقادیر در متغیرها استفاده کرد. از عبارت‌های JSONPath می‌توان در الگوهای پیام عمومی نیز استفاده کرد تا متغیرها را به‌طور پویا درطول اجرای پراکسی با مقادیر جایگزین کند. عبارت‌ها و قالب‌های جدید JSONPath از جدیدترین استانداردهای عبارت JSON پیروی می‌کنند.

تغییرات

مهم است که کارگزاران API/جریان‌های مشترک موجود را برای خط‌مشی‌هایی که از عبارات 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. عبارت‌های Dynamic JSONPath

    به خط‌مشی‌هایی که در آن‌ها عبارت JSONPath توسط متغیر ارائه می‌شود (مثال: {myJsonPathVariable} یا {dynamicPath}) توجه ویژه‌ای داشته باشید. مقدار این متغیرها نیز باید دربرابر تغییرات رفتاری بالقوه که در بالا ذکر شد بررسی شود.

کاهش

بااستفاده از ابزار تشخیص تغییر یا بررسی دستی پراکسی‌های API خود برای یافتن الگوهای توصیف‌شده، هرگونه پراکسی یا جریان مشترکی را که ممکن است تحت تأثیر ارتقا قرار گیرد شناسایی کنید. اگر از این ابزار استفاده کنید، برونداد آن جریان مشترک یا پراکسی تحت‌تأثیر قرارگرفته، خط‌مشی مربوطه، و هر مسیر JSON مشکل‌دار را شناسایی می‌کند، همان‌طور که در برونداد نمونه زیر نشان داده شده است:

سازمان محیط زیست نام آرتیفکت نوع آرتیفکت ویرایش نام خط‌مشی نوع خط‌مشی نوع تأثیر فیلد اختصاصی تأثیر قطعیت تأثیر اسناد
org1 dev proxy1 پراکسی 4 EV-ExtractRequestParams ExtractVariables تغییر رفتار «کارت عام» JSONPath [*] برای مقادیر شیء $.store[*] حداکثر تغییر رفتار «کارت عام» JSONPath [*] برای مقادیر شیء
org2 prod proxy2 جریان هم‌رسانی 1 EV-ExtractResponseParams ExtractVariables نقطه انتهایی (.) در مسیرهای JSONPath اکنون باعث خطا می‌شود $.store.book. حداکثر نقطه انتهایی (.) در مسیرهای JSONPath باعث خطا می‌شود
org3 dev proxy3 پراکسی 3 SC-FetchUserProfile ServiceCallout تغییر ساختار برونداد «نزول بازگشتی JSONPath» (..) ‫$..book حداکثر تغییر ساختار برونداد نزول بازگشتی JSONPath (..)
org4 prod proxy4 جریان هم‌رسانی 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 عبارت‌های Dynamic JSONPath myJsonPathVariable متوسط عبارت‌های Dynamic JSONPath

برای توضیح دقیق ستون‌های جدول برونداد بالا، به بخش درک برونداد ابزار مراجعه کنید.

برای کاهش این مشکل، یک استراتژی جامع ضروری است. این فرایند شامل تصمیم‌گیری درباره مسیر به‌روزرسانی مناسب و اعمال اصلاحات لازم برای عبارات JSONPath شناسایی‌شده است.

«روش مسیر ارتقا» را که برایتان مناسب‌تر است انتخاب کنید:

  • انتقال بدون زمان اَکار

    این استراتژی شامل تهیه یک یا چند محیط جدید است تا بتوانید گره‌های پردازشگر پیام جداگانه را به آن متصل کنید. چنین گره‌های پردازشگر پیام را می‌توان برای نصب نسخه ۴.۵۳.۰۱ تنظیم کرد و دارای پراکسی‌هایی با عبارت‌های مدرن JSONPath هستند. این‌ها می‌توانند درطول ارتقا استفاده شوند و پس‌از تکمیل ارتقا می‌توانند ازکار بیفتند. این استراتژی یکپارچه است اما شامل تهیه موقت گره‌های پردازشگر پیام اضافی برای پشتیبانی از ارتقاء روان است. جزئیات در زیر:

    • محیط جدیدی ایجاد کنید و گره‌های پردازشگر پیام جدیدی از نسخه ۴.۵۳.۰۱ به این محیط جدید اضافه کنید.
    • بسته پراکسی را برای پراکسی‌های تحت‌تأثیر قرارگرفته در محیط جدید بارگذاری کنید و اصلاحات لازم را که در بخش اقدامات اصلاحی توضیح داده شده است اعمال کنید و بسته پراکسی به‌روزشده را در محیط جدید مستقر کنید.
    • ترافیک را به محیط جدید هدایت کنید و پراکسی‌های تحت‌تأثیر را از محیط قدیمی لغو استقرار کنید.
    • گره‌های پردازشگر پیام اصلی را به نسخه 4.53.01 ارتقا دهید. کارگزاران نیابتی را که برای JSONPath در محیط اصلی اصلاحات دارند مستقر کنید.
    • ترافیک را به محیط قدیمی برگردانید، که اکنون پردازشگرهای پیام در نسخه ۴.۵۳.۰۱ و پراکسی مدرن‌شده برای عبارت‌های جدید jsonpath دارد.
    • محیط جدید و گره‌های مرتبط را حذف و ازکار بیندازید.
  • زمان اَکار و ارتقا

    این استراتژی شامل تهیه زمان ازکارافتادگی برای «پراکسی‌های API» بااستفاده از عبارات «مسیر JSON» معیوب است. این کار نیازی به تهیه گره‌های پردازشگر پیام اضافی ندارد اما باعث اختلال در ترافیک میانای برنامه‌سازی کاربردی برای پراکسی‌های تحت‌تأثیر قرارگرفته می‌شود.

    • کارگزاران تحت‌تأثیر را با خط‌مشی‌های تحت‌تأثیر شناسایی کنید و نسخه جدیدی برای همه کارگزاران تحت‌تأثیر تولید کنید.
    • با پیاده‌سازی اصلاحات توضیح‌داده‌شده در بخش اصلاح در نسخه جدیدی از پراکسی، اصلاحات لازم را اعمال کنید. هنوز این را مستقر نکنید.
    • زمان توقف را برای پراکسی/پراکسی‌های تأثیرگذار تهیه کنید.
    • همه پردازشگرهای پیام را به Edge برای نسخه ابری خصوصی ۴.۵۳.۰۱ ارتقا دهید. توجه داشته باشید که کارگزاران نیابتی موجود ممکن است در پردازشگرهای پیام جدیداً ارتقایافته با مشکل مواجه شوند.
    • پس‌از اینکه همه پردازشگرهای پیام به نسخه 4.53.01 از Edge برای ابر خصوصی ارتقا یافتند، نسخه اصلاح‌شده پراکسی جدیداً ایجادشده را با عبارت JSONPath اصلاح‌شده مستقر کنید.
    • ترافیک را در چنین پراکسی‌هایی ازسر بگیرید.
  • بازطراحی «پراکسی» قبل‌از ارتقا

    می‌توانید خود پراکسی را قبل‌از ارتقا دادن به Edge for Private Cloud 4.53.01 بازطراحی کنید. به‌جای تکیه بر عبارت‌های مسیر JSON خاص، می‌توانید بااستفاده از روشی دیگر به نتیجه یکسانی برسید.

    برای مثال، اگر از «خط‌مشی متغیر استخراج» با مسیر JSON استفاده می‌کنید، می‌توانید قبل‌از ارتقا دادن به نسخه جدیدتر، خط‌مشی را با خط‌مشی Javascript که داده‌های مشابه را استخراج می‌کند جایگزین کنید. پس‌از تکمیل ارتقا، می‌توانید پراکسی خود را به استفاده از «مسیرهای JSON» با قالب‌های جدیدتر تغییر دهید.

تغییرات JavaCallout

زمینه

‫Edge for private cloud نسخه ۴.۵۳.۰۰ و نسخه‌های قدیمی‌تر قبلاً حاوی دایرکتوری‌ای به‌نام منسوخ ($APIGEE_ROOT/edge-message-processor/lib/deprecated) بود که شامل مجموعه‌ای از کتابخانه‌های JAR بود. این کتابخانه‌ها برای استفاده در کد Java در خط‌مشی JavaCallout دردسترس بودند و می‌توانستند به‌طور مستقیم یا غیرمستقیم توسط کد Java سفارشی شما استفاده شوند.

تغییرات

دایرکتوری منسوخ‌شده اکنون در Edge برای نسخه 4.53.01 ابر خصوصی برداشته شده است. اگر کد جاوا شما به چنین کتابخانه‌هایی متکی باشد، کارگزاران نیابتی که از چنین فراخوان‌های جاوا استفاده می‌کنند، وقتی پردازشگرهای پیام به نسخه ۴.۵۳.۰۱ ارتقا یابند، با خطا مواجه خواهند شد. برای جلوگیری از چنین خطاهایی، قبل‌از ارتقا دادن پردازشگرهای پیام به نسخه ۴.۵۳.۰۱، مراحل کاهشی زیر را دنبال کنید.

کاهش

  1. خط‌مشی‌های «تماس با جاوا» و فایل‌های jar مرتبط را بااستفاده از ابزار تشخیص تغییر یا به‌صورت دستی مرور کنید. بررسی کنید که آیا هیچ‌یک از خط‌مشی‌ها به کتابخانه‌های موجود در فهرست «منسوخ» پردازشگرهای پیام فعلی شما ارجاع می‌دهند یا خیر.

    اگر از ابزار ارائه‌شده توسط 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 شناسایی شد ['استفاده از کلاس org.apache.commons.io.FileUtils از commons-io-2.5.jar شناسایی شد، 'استفاده از کلاس org.apache.commons.io.input.XmlStreamReaderException از 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. پس‌از شناسایی چنین کتابخانه‌های منسوخی، می‌توانید یکی از روش‌های زیر را برای کاهش مشکل دنبال کنید.
    • جای‌گذاری منبع (اگر تعداد کمی کوزه / کتابخانه از دایرکتوری منسوخ‌شده دارید که توسط کوزه‌های Java-Callout ارجاع داده می‌شوند، توصیه می‌شود)
      • جار‌های منسوخ‌شده شناسایی‌شده را به‌عنوان منبع در سطح موردنظر بارگذاری کنید: نسخه بازبینی کارگزار نیابتی API، محیط، یا سازمان.
      • طبق معمول، ارتقای نرم‌افزار Apigee را ادامه دهید.
    • جای‌گذاری دستی (اگر تعداد زیادی کوزه / کتابخانه دارید که توسط کوزه‌های 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
      • مطمئن شوید که کاربر Apigee می‌تواند فهرستگان و فایل‌های jar زیرین را بخواند: chown -R apigee:apigee $APIGEE_ROOT/data/edge-message-processor/external-lib
      • طبق معمول، ارتقای نرم‌افزار Apigee را ادامه دهید.

تغییر OpenLDAP

زمینه

می‌توان از OpenLDAP در Edge Private Cloud هم برای اصالت‌سنجی و هم برای صدور مجوز استفاده کرد. در Edge for Private Cloud نسخه ۴.۵۳.۰۱، نرم‌افزار OpenLDAP که Apigee ارائه کرده است از نسخه ۲.۴ به ۲.۶ ارتقا یافت.

تغییرات

در OpenLDAP 2.6، نام متمایز نسبی (RDN) به تقریباً ۲۴۱ بایت/نویسه محدود می‌شود. این محدودیت یک سقف سخت است که اعمال می‌شود و قابل‌تغییر نیست.

تأثیر
  • خطاهای تکثیر یا وارد کردن برای ورودی‌هایی با RDNهای بیش‌ازحد بزرگ رخ می‌دهد.
  • تلاش برای ایجاد نهادهایی مثل سازمان‌ها، محیط‌ها، نقش‌های سفارشی، اجازه‌ها، و غیره ممکن است منجر به این پیام خطا شود: "message": "[LDAP: error code 80 - Other]".
  • هر DN طولانی‌تر از ۲۴۱ بایت در 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 کوچک‌تر از ۲۴۱ بایت می‌شود.

کاهش

قبل‌از ارتقا به نسخه ۴.۵۳.۰۱:

مراحل زیر به درستی‌سنجی وجود RDNهای طولانی در خوشه LDAP 2.4 موجود شما کمک می‌کند.

#۱ - استخراج داده‌های «ال‌دپ»

از دستور 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 داشته باشد.

#۲ - شناسایی RDNهای طولانی

ابزار تشخیص تغییر از فایل LDIF تولیدشده برای شناسایی LDAP RDNهایی که از ۲۴۱ بایت/نویسه فراتر می‌روند استفاده می‌کند.

این ابزار گزارش‌ها را در قالب زیر تولید می‌کند:

سازمان محیط زیست نام آرتیفکت نوع آرتیفکت ویرایش نام خط‌مشی نوع خط‌مشی نوع تأثیر فیلد اختصاصی تأثیر قطعیت تأثیر اسناد
خالی خالی cn=really-long-name,ou=userroles,o=edge-platform,ou=organizations,dc=apigee,dc=com فایل ldif خالی خالی خالی ‫Ldap RDN از ۲۴۱ نویسه فراتر رفته است cn=really-long-name حداکثر تغییر OpenLDAP

برای توضیح دقیق ستون‌های جدول برونداد بالا، به بخش درک برونداد ابزار مراجعه کنید.

اگر فرمان بالا هیچ بروندادی تولید نکرد، یعنی هیچ RDN در تنظیمات LDAP موجود از ۲۴۱ بایت/نویسه فراتر نمی‌رود. می‌توانید طبق معمول ارتقا را ادامه دهید.

اگر فرمان بالا بروندادی تولید کند، نشان می‌دهد که RDNهایی وجود دارد که از ۲۴۱ بایت/نویسه فراتر رفته‌اند. برای چنین مواردی، قبل‌از ادامه دادن با ارتقای Edge for Private Cloud 4.53.01، مراحل کاهشی را که در مرحله شماره ۳ توضیح داده شده است دنبال کنید.

#۳ - مدیریت نام‌های RDN طولانی

اگر برونداد از مرحله ۲ دریافت شود، نشان‌دهنده وجود RDNهایی است که از ۲۴۱ بایت/نویسه فراتر رفته‌اند و باید مراحل زیر را برای کاهش آن دنبال کنید:

مدخل‌های «ال‌دپ» را که از ۲۴۱ بایت بیشتر است مرور کنید.

  • اگر نام نقش سفارشی، برنامه، محصول API، یا نهادهای دیگری عامل اصلی طولانی شدن RDN است، به استفاده از نهاد جایگزینی با نام کوتاه‌تر مهاجرت کنید.
  • اگر نام سازمان یا نام محیط عامل اصلی طولانی بودن RDN است، باید به سازمان یا محیط دیگری با نام کوتاه‌تر انتقال دهید.

مراحل بالا را آنقدر تکرار کنید تا LDAP شما هیچ RDN با طول بیشتر از ۲۴۱ بایت نداشته باشد. پس‌از رسیدن به این وضعیت، ارتقای نسخه فضای ابری خصوصی را طبق روال معمول انجام دهید.

تغییرات «ارائه‌دهنده رمزنگاری»

زمینه

این تغییر از Edge for Private Cloud نسخه ۴.۵۳.۰۰ منتقل شده است. در Edge for Private Cloud 4.53.00، ارائه‌دهنده رمزنگاری داخلی از 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، خط‌مشی‌ها، و جریان‌های مشترکی که ممکن است درطول و پس‌از انتقال به Edge for Private Cloud 4.53.01 تحت‌تأثیر قرار گیرند ساخته شده است. این ابزار گزارشی تولید می‌کند که جزئیات پراکسی‌های مستقر، جاری‌سازی‌های هم‌رسانی‌شده، و OpenLDAP تحت‌تأثیر تغییرات را ارائه می‌دهد و به راهنماها و استراتژی‌های خاص مربوط به آن پراکسی‌ها یا جاری‌سازی‌های هم‌رسانی‌شده شناسایی‌شده هدایت می‌کند.

پیش‌نیازها

  1. برای اجرای این ابزار، دستگاه مبتنی بر RHEL لازم است.
  2. ‫JRE 8 باید در ماشین مجازی میزبان نصب و به‌درستی پیکربندی شود تا به اجرا شدن دستورگان ابزار اجازه دهد.
  3. این ابزار برای اصالت‌سنجی و بازیابی داده‌ها به نقطه پایان (نشانی وب) صحیح «سرور مدیریت» و اطلاعات اعتباری سرپرست معتبر نیاز دارد.
  4. این ابزار برای استخراج دسته‌ها، تولید گزارش‌ها، و ذخیره برونداد به دسترسی به یک پوشه کاری تعیین‌شده (برای نمونه، /tmp) نیاز دارد. مطمئن شوید این فهرست راهنما فضای دیسک کافی و اجازه‌های خواندن/نوشتن مناسب را داشته باشد.
  5. این ابزار برای شناسایی RDNهای طولانی‌تر از ۲۴۱ نویسه / بایت، به فایل LDIF بااستفاده از فرمان ldapsearch در بخش تغییر OpenLDAP - استخراج داده‌های LDAP نیاز دارد.

درحال اجرای ابزار

پس‌از برآورده شدن همه پیش‌نیازهای فهرست‌شده در بالا، ابزار را بارگیری کنید و نام کاربری و گذرواژه Apigee را که برای دسترسی به مخزن Apigee استفاده می‌کنید به آن ارائه دهید. پس‌از بارگیری، بایگانی بارگیری‌شده را استخراج کنید.

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

پس‌از تکمیل بارگیری، می‌توانید فرمان زیر را اجرا کنید تا همه گزینه‌های دردسترس برای ابزار را ببینید:

./change-detector --help

برای اجرای ابزار، از فرمان زیر استفاده کنید و جای‌بان‌ها را با اطلاعات خودتان جایگزین کنید:

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

برای شناسایی ورودی‌های بزرگ RDN LDAP، فرمان زیر را اجرا کنید:

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

این ابزار برونداد را در قالب json یا csv تولید می‌کند که می‌تواند مستقیماً مصرف شود یا در ابزاری قابل‌خواندن برای انسان، مثل «کاربرگ‌نگار Google»، وارد شود.

درک برونداد ابزار

سازمان

به نام سازمانی که محصول در آن قرار دارد اشاره می‌کند. برای تغییر OpenLDAP، این مقدار None خواهد بود.

محیط زیست

محیط خاص (برای نمونه، توسعه، آزمایش، تولید) در سازمان. برای تغییر OpenLDAP، این مقدار None خواهد بود.

برای تغییرات «تماس با Java»، اگر «نوع آرتیفکت»=env-level-jar، این فیلد None خواهد بود.

نام آرتیفکت

این فیلد نام جریان مشترک/پراکسی را نشان می‌دهد. برای تغییر OpenLDAP، این فیلد نهاد LDAP مربوط به RDN را نشان می‌دهد.

برای تغییرات «نوشته راهنمای تماس Java»، اگر «نوع آرتیفکت»=env-level-jar یا org-level-jar، این فیلد None خواهد بود.

نوع آرتیفکت

  • برای تغییرات OAS و JSON، این ستون نوع آرتیفکت، پراکسی، یا جریان مشترک را مشخص می‌کند.
  • برای تغییر «ندای جاوا»، این ستون جزئیاتی درباره مکان یا سطحی که فایل jar تحت‌تأثیر قرارگرفته در آن بارگذاری شده است ارائه می‌دهد. منابع (JAR) می‌توانند در یکی از سه سطح ذخیره شوند: org-level، env-level، proxy-level.
  • برای تغییر OpenLDAP، این فیلد نشان‌دهنده فایل LDIF استفاده‌شده در ابزار است.

ویرایش

به نسخه اصلاح‌شده مستقرشده از جریان مشترک/پراکسی تحت‌تأثیر اشاره می‌کند. برای تغییر OpenLDAP، مقدار آن None خواهد بود.

نام خط‌مشی

نام خط‌مشی خاصی که به‌عنوان مشکل احتمالی شناسایی شده است. برای تغییر OpenLDAP، مقدار آن None خواهد بود.

نوع خط‌مشی

به نوع خط‌مشی اشاره می‌کند. برای تغییر OpenLDAP، مقدار آن None خواهد بود.

نوع تأثیر

  • این فیلد نوع خاص تغییر شناسایی‌شده در یک جریان مشترک/پراکسی را توصیف می‌کند.
  • برای تغییر «پیام‌واره Java»، ابزار تغییرات مربوط به پیام‌واره‌های Java را شناسایی می‌کند و به پیام‌واره Java تحت‌تأثیر قرارگرفته که به فایل‌های 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 از ۲۴۱ بایت یا نویسه فراتر رفته است یا نه.

فیلد خاص تأثیر

  • برای تغییر «سیستم خودکار پیشنهاد قیمت»، این فیلد نام متغیری است که در برچسب منبع خط‌مشی استفاده می‌شود.
  • برای تغییر JSON، این فیلد عبارت یا عنصر دقیق JSONPath را که به‌عنوان مشکل بالقوه پرچم‌گذاری شده است نشان می‌دهد.
  • برای تغییر «تماس با جاوا»، این فیلد جزئیات دقیق کلاس‌ها و نام JAR مربوطه (موجود در دایرکتوری $APIGEE_ROOT/edge-message-processor/lib/deprecated نسخه‌های قدیمی‌تر «ابر خصوصی») را دارد که توسط فایل jar «تماس با جاوا» تحت‌تأثیر قرارگرفته استفاده/ارجاع می‌شود و درصورت عدم کاهش، منجر به خرابی در ارتقا به نسخه ۴.۵۳.۰۱ می‌شود.
    •  ['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 را نشان می‌دهد که همه آن‌ها از ۲۴۱ بایت یا نویسه بیشتر هستند.

قطعیت تأثیر

  • این فیلد میزان اطمینان ابزار را در تشخیص یک مورد خاص نشان می‌دهد. مقادیر این ستون می‌تواند بالا یا متوسط باشد (ممکن است مقادیر بیشتری بعداً اضافه شود).

    مقدار بالا یعنی ابزار تعیین کرده است که احتمال بسیار زیادی وجود دارد که پس‌از ارتقا به نسخه 4.53.01، این مورد باعث ازکارافتادن برنامه شود. مقدار متوسط نشان می‌دهد که ابزار درباره تشخیص نامطمئن است و برای تعیین آن به استراتژی‌های بیشتری نیاز است (برای مثال، گرفتن ردگیری برای مشاهده متغیرهای حل‌شده درطول اجرای پراکسی).

  • شناسایی‌های مربوط به تغییرات JavaCallout و OpenLDAP همیشه مقدار بالا برای ستون‌های قطعیت تأثیر دارند.

اسناد

این ستون اَبَرپیوندی به مستندات Apigee (بخش‌های مرتبط این مقاله) ارائه می‌دهد که مشکل و مراحل کاهش آن را توضیح می‌دهد.