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

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

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

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

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

الوقت

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

لمحة

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

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

نماذج

مثال بسيط

كيفية إنشاء وسيلة شرح 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، نفِّذ الدالة الإنشائية التالية في تنفيذ فئة 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.

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

العنصر <Property>

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

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

القيود

في ما يلي القيود التي يجب مراعاتها عند كتابة Java Callouts:

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

حزمة المحتوى

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

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

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

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

Javadoc

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

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

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

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