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

أنت الآن بصدد الاطّلاع على مستندات Apigee Edge.
انتقِل إلىمستندات Apigee X. info

الأدوات المستخدمة

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

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

الوقت

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

لمحة

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

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

نماذج

مثال بسيط

كيفية إنشاء سياسة Java Callout

استرداد الخصائص في رمز Java

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

استخدِم السمة 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، نفِّذ الدالة الإنشائية التالية في تنفيذ فئة Execution على النحو التالي:
    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 لمواصلة تنفيذ المسار حتى بعد تطبيق إحدى السياسات. فشل.

 خطأ اختياري
enabled

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

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

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

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

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

&lt;DisplayName&gt; عنصر

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

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

لا ينطبق

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

العنصر <ClassName>

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

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

العنصر <Property>

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

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
القيمة التلقائية: بلا
التواجد في المنزل: اختياري
النوع: سلسلة

السمات

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

يحدّد اسم السمة.

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

<ResourceURL> العنصر

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

يمكنك تخزين هذا الملف على مستوى الخادم الوكيل لواجهة برمجة التطبيقات (ضمن /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 Callout.

القيود

في ما يلي القيود التي عليك أخذها في الاعتبار عند كتابة سياسات Java Callout:

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

حزمة المحتوى

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

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

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

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

Javadoc

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

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

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

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

  • للاطّلاع على نماذج ذات صلة، يُرجى الاطّلاع على مستودع java-cookbook repository.