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

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

المزايا

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

للحصول على إصدارات متوافقة من Java، راجع المتوافقة البرامج والإصدارات المتوافقة معها.

الوقت

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

لمحة

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

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

نماذج

مثال بسيط

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

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

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

استخدام <الخاصية> name للعنصر لتحديد الاسم باستخدام الذي يمكن الوصول إليه من خلال رمز 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>

&lt;JavaCallout&gt; السمات

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

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

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

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

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

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

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

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

 خطأ اختياري
enabled

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

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

 صحيح اختياري
async

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

 خطأ منهي العمل به

&lt;DisplayName&gt; عنصر

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

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

لا ينطبق

إذا لم تستخدم هذا العنصر، سيتم ضبط قيمة السمة name للسياسة على النحو التالي: استخدام البيانات المختلفة.
التواجد في المنزل اختياري
النوع سلسلة

&lt;ClassName&gt; عنصر

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

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

&lt;Property&gt; عنصر

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

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

السمات

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

تُستخدَم لتحديد اسم الموقع.

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

&lt;ResourceURL&gt; عنصر

يحدّد هذا العنصر ملف 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>

المخططات

التجميع والنشر

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

القيود

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

  • لا يُسمح بمعظم استدعاءات النظام. على سبيل المثال، لا يمكنك جعل نظام الملفات الداخلي يقرأ أو يكتب.
  • الوصول إلى الشبكة عبر المقابس. تحظر Apigee إمكانية الوصول إلى sitelocal أو anylocal وعناوين الاسترجاع و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، راجع كيفية إنشاء وسيلة شرح Java

Javadoc

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

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

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

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