سياسة Javaوسائل الشرح

يتم الآن عرض مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. المعلومات

الموضوع

يمكّنك من استخدام لغة Java لتنفيذ سلوك مخصّص لا يتم إدراجه على نحو مبتكر من خلال سياسات Apigee. في رمز Java، يمكنك الوصول إلى خصائص الرسالة (العناوين ومعلَمات طلب البحث والمحتوى) ومتغيّرات التدفق في تدفق الخادم الوكيل. إذا كنت قد بدأت للتو في استخدام هذه السياسة، اطّلِع على كيفية إنشاء وسيلة شرح بلغة Java.

لمعرفة إصدارات Java المتوافقة، يُرجى الاطّلاع على البرامج المتوافقة والإصدارات المتوافقة.

حالات الاستخدام

للحصول على إرشادات، اطّلِع على "متى يجب استخدام وسيلة شرح JavaScript؟" في كيفية إنشاء وسيلة شرح بلغة Java.

لمحة عامة

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

يمكنك حزم تطبيق Java مع أي ملفات JAR للحزمة تحتاج إليها. وتجدر الإشارة إلى أن هناك بعض القيود على ما يمكنك فعله باستخدام وسيلة شرح جافا. ويمكنك الاطّلاع على هذه المشاكل أدناه في قسم القيود.

عيّنات

مثال بسيط

كيفية إنشاء وسيلة شرح بلغة Java

استرداد المواقع في رمز Java

يتيح لك عنصر <Property> للسياسة تحديد زوج الاسم/القيمة الذي يمكنك استرداده في وقت التشغيل باستخدام رمز Java. للاطّلاع على مثال عملي يستخدم الخصائص، يمكنك الاطّلاع على كيفية استخدام السمات في وسيلة شرح Java.

استخدِم السمة name لعنصر <Property> لتحديد الاسم الذي يمكنك باستخدامه الوصول إلى الخاصية من رمز Java. قيمة العنصر <Property> (القيمة بين علامتَي الفتح والإغلاق) هي القيمة التي سيستلمها رمز Java. يجب أن تكون القيمة سلسلة، ولا يمكنك الإشارة إلى متغيّر تدفق للحصول على القيمة.

  • اضبط الموقع. في هذا المثال، تكون قيمة السمة هي اسم المتغيّر response.status.code. 
    <JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout">
    <DisplayName>JavaCallout</DisplayName>
    <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
    <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
    <Properties>
        <Property name="source">response.status.code</Property>
    </Properties>
</Javascript>
  • في رمز Java، نفِّذ دالة الإنشاء التالية في تنفيذ فئة التنفيذ على النحو التالي:
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){
        
            // Extract property values from map.
    }
    ...
}

تعيين متغيرات التدفق في رمز Java

للحصول على وصف واضح لكيفية ضبط المتغيّرات في سياق الرسالة (متغيّرات التدفق) في رمز Java، يمكنك الاطّلاع على هذه المشاركة في منتدى Apigee.

مرجع العنصر

يصف مرجع العنصر عناصر وسمات سياسة JavaCallout.

<JavaCallout name="MyJavaCalloutPolicy">
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
</JavaCallout>

سمات <JavaCallout>

<JavaCallout name="MyJavaCalloutPolicy" enabled="true" continueOnError="false" async="false" >

يوضِّح الجدول التالي السمات الشائعة لجميع العناصر الرئيسية للسياسة:

السمة الوصف تلقائي التواجد في المنزل
name

الاسم الداخلي للسياسة وقد تحتوي قيمة السمة name على أحرف وأرقام ومسافات وواصلات وشرطات سفلية ونقاط. لا يمكن أن تتجاوز هذه القيمة 255 حرفًا.

ويمكنك اختياريًا استخدام العنصر <DisplayName> لتصنيف السياسة في محرِّر الخادم الوكيل لواجهة المستخدم الإدارية باستخدام اسم مختلف للغة طبيعية.

 لا ينطبق مطلوبة
continueOnError

اضبط القيمة على false لعرض رسالة خطأ عند تعذُّر تنفيذ السياسة. وهو سلوك متوقّع لمعظم السياسات.

اضبط القيمة على true لمواصلة تنفيذ التدفق حتى بعد تعذُّر تنفيذ السياسة.

 false إجراء اختياري
enabled

اضبط القيمة على true لفرض السياسة.

اضبط القيمة على false من أجل إيقاف السياسة. ولن يتم فرض السياسة حتى إذا ظلت مرتبطة بمسار.

 صحيح إجراء اختياري
async

تم إيقاف هذه السمة نهائيًا.

 false منهي العمل به

العنصر <DisplayName>

استخدِم هذه السمة بالإضافة إلى السمة name لتصنيف السياسة في محرِّر الخادم الوكيل لواجهة المستخدم الإدارية باستخدام اسم مختلف بلغة طبيعية.

<DisplayName>Policy Display Name</DisplayName>
تلقائي

لا ينطبق

إذا لم تستخدم هذا العنصر، سيتم استخدام قيمة السمة name الخاصة بالسياسة.
التواجد في المنزل إجراء اختياري
Type سلسلة

عنصر <ClassName>

تحدِّد هذه السمة اسم فئة Java التي يتم تنفيذها عند تشغيل سياسة وسائل شرح Java. ويجب تضمين الفئة في ملف JAR المحدَّد في <ResourceURL>. راجِع أيضًا كيفية إنشاء وسيلة شرح بلغة Java.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
الخيار التلقائي: لا ينطبق
الحضور: مطلوبة
النوع: سلسلة

عنصر <الخاصية>

تُحدِّد هذه السياسة موقعًا يمكنك الوصول إليه من رمز Java في وقت التشغيل. عليك تحديد قيمة سلسلة حرفية لكل سمة، ولا يمكنك الإشارة إلى متغيّرات التدفق في هذا العنصر. للاطّلاع على مثال عملي يستخدم الخصائص، يمكنك الاطّلاع على كيفية استخدام السمات في وسيلة شرح Java.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
الخيار التلقائي: لا ينطبق
الحضور: إجراء اختياري
النوع: سلسلة

السمات

السمة الوصف تلقائي التواجد في المنزل
اسم

تُحدِّد اسم الموقع.

 لا ينطبق مطلوبة.

عنصر<ResourceURL>

يحدّد هذا العنصر ملف Java JAR الذي سيتم تنفيذه عند تشغيل سياسة وسيلة الشرح في Java.

يمكنك تخزين هذا الملف في نطاق الخادم الوكيل لواجهة برمجة التطبيقات (ضمن /apiproxy/resources/java في حزمة الخادم الوكيل لواجهة برمجة التطبيقات أو في قسم "النصوص البرمجية" ضمن مساحة "مستكشف الخادم الوكيل لواجهة برمجة التطبيقات") أو في نطاقات المؤسسة أو البيئة لإعادة استخدامه في عدة خوادم وكيل لواجهة برمجة التطبيقات، كما هو موضّح في ملفات الموارد.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
الخيار التلقائي: لا ينطبق
الحضور: مطلوبة
النوع: سلسلة

مرجع الخطأ

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

أخطاء في وقت التشغيل

يمكن أن تحدث هذه الأخطاء عند تنفيذ السياسة.

رمز الخطأ رموز حالة HTTP السبب إصلاح
steps.javacallout.ExecutionError 500 يحدث عندما يقدم رمز Java استثناءً أو يعرض قيمة فارغة أثناء تنفيذ سياسة JavaCallout.

أخطاء النشر

يمكن أن تحدث هذه الأخطاء عند تفعيل الخادم الوكيل الذي يحتوي على السياسة.

اسم الخطأ سلسلة الخطأ رموز حالة HTTP يحدث عند
ResourceDoesNotExist Resource with name [name] and type [type] does not exist لا ينطبق الملف المحدد في العنصر <ResourceURL> غير موجود.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] لا ينطبق ملف الفئة المحدّد في العنصر <ClassName> ليس في الوعاء.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] لا ينطبق الاطّلاع على سلسلة الخطأ راجِع أيضًا البرامج المتوافقة والإصدارات المتوافقة.
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] لا ينطبق الاطّلاع على سلسلة الخطأ
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] لا ينطبق الاطّلاع على سلسلة الخطأ
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] لا ينطبق الاطّلاع على سلسلة الخطأ
NoResourceForURL Could not locate a resource with URL [string] لا ينطبق الاطّلاع على سلسلة الخطأ

متغيرات الخطأ

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

المتغيرات المكان مثال
fault.name="fault_name" fault_name هو اسم الخطأ، كما هو موضَّح في جدول أخطاء وقت التشغيل أعلاه. اسم الخطأ هو الجزء الأخير من رمز الخطأ. fault.name Matches "ExecutionError"
javacallout.policy_name.failed policy_name هو اسم السياسة التي حدّدها المستخدم التي أدت إلى حدوث الخطأ. javacallout.JC-GetUserData.failed = true

مثال على الردّ على الخطأ

{  
   "fault":{  
      "faultstring":"Failed to execute JavaCallout. [policy_name]",
      "detail":{  
         "errorcode":"javacallout.ExecutionError"
      }
   }
}

مثال لقاعدة خطأ

<FaultRule name="JavaCalloutFailed">
    <Step>
        <Name>AM-JavaCalloutError</Name>
    </Step>
    <Condition>(fault.name Matches "ExecutionError") </Condition>
</FaultRule>

المخططات

تجميع ونشر

للحصول على تفاصيل حول كيفية تجميع رمز JavaScript المخصّص ونشره باستخدام خادم وكيل، يُرجى الاطّلاع على كيفية إنشاء وسيلة شرح بلغة Java.

القيود

فيما يلي القيود التي يجب مراعاتها عند كتابة وسائل شرح جافا:

  • معظم مكالمات النظام غير مسموح بها. على سبيل المثال، لا يمكنك جعل نظام الملفات الداخلي يقرأ أو يكتب.
  • الوصول إلى الشبكة عبر المقابس. تحظر Apigee الوصول إلى عناوين sitelocal وأي عنوان محلي واسترجاع وlinklocal.
  • لا يمكن لوسيلة الشرح الحصول على معلومات حول العملية الحالية أو قائمة العمليات أو استخدام وحدة المعالجة المركزية (CPU)/الذاكرة على الجهاز. على الرغم من أنّ بعض هذه الطلبات قد تكون فعّالة، فهي غير متاحة وقد يتم إيقافها بشكل نشط في أي وقت. ولتوافق إعادة التوجيه، عليك تجنُّب إجراء مثل هذه الطلبات في الرمز البرمجي الخاص بك.
  • لا يمكن الاعتماد على مكتبات Java المضمّنة في Apigee Edge. وهذه المكتبات مخصّصة لوظائف منتج Edge فقط، وليس هناك ما يضمن توفّر مكتبة من إصدار إلى آخر.
  • لا تستخدم io.apigee أو com.apigee كأسماء حِزم في وسائل شرح Java. هذه الأسماء محجوزة وتستخدمها وحدات Apigee أخرى.

حزمة محتوى

ضَع JAR في خادم وكيل لواجهة برمجة التطبيقات ضمن /resources/java. إذا كانت وسيلة شرح Java تعتمد على مكتبات إضافية تابعة لجهات خارجية في شكل ملفات JAR مستقلة، عليك وضع ملفات JAR هذه في دليل /resources/java أيضًا لضمان تحميلها بشكل صحيح في وقت التشغيل.

إذا كنت تستخدم واجهة مستخدم الإدارة لإنشاء الخادم الوكيل أو تعديله، أضِف موردًا جديدًا وحدِّد ملف JAR إضافيًا تابعًا. في حال توفّر عدة JAR، ما عليك سوى إضافتها كموارد إضافية. ولن تحتاج إلى تعديل إعدادات السياسة للإشارة إلى ملفات JAR الإضافية. يكفي وضعها في /resources/java.

للحصول على معلومات عن تحميل Java JAR، يُرجى الاطِّلاع على ملفات الموارد.

للحصول على مثال تفصيلي يوضّح كيفية تجميع وسيلة شرح Java ونشرها باستخدام Maven أو javac، يمكنك الاطّلاع على كيفية إنشاء وسيلة شرح JavaScript.

JavaScript

تم تضمين JavaScript لكتابة رمز وسيلة شرح Java هنا على GitHub. ستحتاج إلى نسخ رمز HTML أو تنزيله على نظامك ثم فتح ملف index.html في المتصفح.

ملاحظات الاستخدام

  • لا تحتوي سياسة وسائل شرح Java على أي رمز فعلي. وبدلاً من ذلك، تشير سياسة وسائل شرح Java إلى "مورد" Java وتحدّد الخطوة في مسار واجهة برمجة التطبيقات التي يتم فيها تنفيذ رمز Java. يمكنك تحميل Java JAR من خلال محرِّر الخادم الوكيل لواجهة المستخدم الإدارية، أو يمكنك تضمينه في دليل /resources/java في الخوادم الوكيلة لواجهة برمجة التطبيقات التي تطوّرها محليًا.
  • بالنسبة إلى العمليات البسيطة، مثل طلبات البيانات من واجهة برمجة التطبيقات إلى الخدمات عن بُعد، نقترح استخدام سياسة ServiceCallout. يُرجى الاطّلاع على سياسة وسائل شرح الخدمة.
  • بالنسبة إلى التفاعلات البسيطة نسبيًا مع محتوى الرسائل، مثل تعديل أو استخراج عناوين HTTP أو المعلَمات أو محتوى الرسالة، تنصح Apigee باستخدام سياسة JavaScript.

مواضيع ذات صلة