سياسة 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>
الإعداد التلقائي: لا ينطبق
الحضور: مطلوب
النوع: سلسلة

مرجع الخطأ

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.javacallout.ExecutionError 500 Occurs when Java code throws an exception or returns null during the execution of a JavaCallout policy.

Deployment errors

These errors can occur when the proxy containing the policy is deployed.

Error name Fault string HTTP status Occurs when
ResourceDoesNotExist Resource with name [name] and type [type] does not exist N/A The file specified in the <ResourceURL> element does not exist.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] N/A The class file specified in the <ClassName> element is not in the jar.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] N/A See fault string. See also Supported software and supported versions.
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] N/A See fault string.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] N/A See fault string.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] N/A See fault string.
NoResourceForURL Could not locate a resource with URL [string] N/A See fault string.

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "ExecutionError"
javacallout.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. javacallout.JC-GetUserData.failed = true

Example error response

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

Example fault rule

<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.

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