تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

ما وسيلة شرح Java؟

توفّر Apigee Edge مجموعة من السياسات التي تلبّي متطلّبات إدارة واجهة برمجة التطبيقات الشائعة، مثل الأمان وتحويل البيانات وإدارة عدد الزيارات وغيرها.

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

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

كيف يمكنني استخدام رمز Java في خادم وكيل؟

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

متى يجب أن أستخدم وسيلة شرح Java؟

لنلقِ نظرة على الحالات التي تكون فيها وسائل شرح Java مفيدة، والمواقف التي يجب فيها التفكير في أساليب أخرى.

أولاً، عليك التفكير في مناهج بديلة

قبل استخدام وسيلة شرح بلغة Java، قد تكون هناك أساليب بديلة يمكنك استخدامها بدلاً من ذلك. مثال:

بالنسبة إلى العمليات البسيطة، مثل طلبات البيانات من واجهة برمجة تطبيقات HTTP إلى الخدمات البعيدة، يمكنك استخدام سياسة ServiceCallout. يُرجى الاطّلاع على سياسة وسائل شرح الخدمة.
بالنسبة إلى التفاعلات البسيطة نسبيًا مع محتوى الرسائل، مثل تعديل أو استخراج عناوين HTTP أو المعلَمات أو محتوى الرسالة، يمكنك استخدام لغات JavaScript أو Python.

ما يمكنك فعله باستخدام رمز Java

توفِّر وسيلة شرح Java العمليات الأساسية التالية:

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

الإجراءات التي لا يمكنك تنفيذها باستخدام رمز Java

معظم مكالمات النظام غير مسموح بها. لا يمكنك:

جعل نظام الملفات الداخلي يقرأ أو يكتب. وهذا يعني أنّه لا يمكنك استخدام أي من حِزم Java للقراءة/الكتابة في أنظمة الملفات الداخلية، ولكن يمكنك إجراء مكالمات خارجية عن بُعد.
احصل على معلومات حول العملية الحالية أو قائمة العمليات أو استخدام وحدة المعالجة المركزية (CPU)/الذاكرة على الجهاز.
الوصول إلى رمز المصدر في "expressions-1.0.0.jar" و"message-flow-1.0.0.jar"

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

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

مرحبًا وسيلة شرح Java

دعونا نتعرف على مثال أساسي مرحبا لعالم Java. في هذا المثال، ننشئ خادمًا وكيلاً بسيطًا مع وسيلة شرح في Java تعرض استجابة "hello world". ويمكن للخادم الوكيل عرض إحدى الاستجابات المحتملة:

إذا أدخلت عنوان "username" مع قيمة "name"، سيعرض الخادم الوكيل ما يلي:
```
Hello, <name>!
```
إذا حذفت العنوان، سيعرض الخادم الوكيل فقط ما يلي:
```
"Hello, Guest!"
```

تنزيل المشروع الأوّلي

لتبسيط الأمور، لدينا مشروع أساسي تم إعداده لك على GitHub في مستودع api-platform-samples الخاص بـ Apigee.

يمكنك تنزيل api-platform-samples أو نسخها إلى نظامك.
في أيّ وحدة طرفية أو أداة تعديل رموز من اختيارك، انتقِل إلى مشروع api-platform-samples/doc-samples/java-hello.

كتابة رمز Java

افتح ملف مصدر Java: java-hello/callout/src/main/java/HelloJava.java. هذا الملف هو نسخة هيكلية لفئة Java الرئيسية التي سنقوم بتنفيذها. وتكون الحِزم المستورَدة مطلوبة لرمز وسيلة الشرح في Edge Java. توفِّر هذه الفئات طرقًا تتيح لك الوصول إلى سياق تنفيذ الخادم الوكيل. سنستعرض بعد قليل خطوات تجميع هذا الرمز ونشره.

package com.apigeesample;

import com.apigee.flow.execution.ExecutionContext;
import com.apigee.flow.execution.ExecutionResult;
import com.apigee.flow.execution.spi.Execution;
import com.apigee.flow.message.MessageContext;


public class HelloJava implements Execution {

        public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
                
                try {

                        // Your code here.
            
            return ExecutionResult.SUCCESS;

                } catch (Exception e) {
                        return ExecutionResult.ABORT;
                }
        }

}

استبدِل السطر الذي تم التعليق عليه // Your code here بالرمز التالي:
```
String name = messageContext.getMessage().getHeader("username");

if (name != null && name.length()>0) {
        messageContext.getMessage().setContent("Hello, " + name + "!");
        messageContext.getMessage().removeHeader("username");
} else {
        messageContext.getMessage().setContent("Hello, Guest!");
}
```
ملاحظة: ملاحظة: يتيح لك الكائن MessageContext الوصول إلى الكيانات داخل المسار الذي يتم فيه تنفيذ سياسة "وسيلة شرح Java". ولنفترض أن سياسة وسائل شرح Java مرتبطة بمسار استجابة نقطة نهاية الخادم الوكيل. ويحصل الرمز البرمجي المذكور أعلاه على كائن رسالة HTTP لسياق التدفق هذا. بدوره، يمنحك كائن الرسالة إمكانية الوصول إلى العناوين ومعلَمات طلب البحث ومحتوى النص ومتغيّرات التدفق.
احفظ الملف.

تجميع الرمز باستخدام Maven

تم إعداد المشروع بحيث يمكنك التجميع باستخدام Maven. وإذا كنت تريد استخدام السمة javac، سنُضمِّن مثالاً على مثال Maven.

تأكَّد من تثبيت Maven من خلال:
```
mvn -version
```
نفِّذ النص البرمجي java-hello/buildsetup.sh. يثبّت هذا النص البرمجي تبعيات JAR المطلوبة في مستودع Maven المحلي.
القرص المضغوط إلى دليل java-hello/callout.
نفِّذ Maven:
```
mvn clean package
```
ملاحظة: إذا ظهرت لك رسالة خطأ Maven، تأكَّد من أنّك في دليل java-hello/callout.
تأكَّد من أنّه تم نسخ ملف JAR edge-custom-policy-java-hello.jar إلى java-hello/apiproxy/resources/java، إذا أردت ذلك. وهذا هو المكان المطلوب لملفات JAR التي تريد نشرها باستخدام خادم وكيل.

التجميع باستخدام javac (اختياري)

في القسم السابق، يمكنك إنشاء ملف Java JAR المطلوب تلقائيًا باستخدام أمر Maven. إذا أردت استخدام javac لتجميع الرمز، يمكنك بدلاً من ذلك تنفيذ ما يلي (من الدليل java-hello). يتم توفير ملفات JAR المطلوبة لك في دليل java-hello/lib.

القرص المضغوط إلى api-platform-samples/doc-samples/java-hello.
تأكد من أن لديك javac في مسارك.
```
javac -version
```

نفِّذ أمر javac التالي:

javac -d . -classpath ./lib/expressions-1.0.0.jar:./lib/message-flow-1.0.0.jar:. callout/src/main/java/HelloJava.java

سيؤدي هذا إلى إنشاء com/apigeesample/HelloJava.class.

أنشِئ ملف JAR يحتوي على الفئة التي تم تجميعها في دليل apiproxy/resources/java. وهذا هو المكان المطلوب لملفات JAR التي تريد نشرها باستخدام خادم وكيل. يمكنك إجراء ذلك من خلال تنفيذ الأمر التالي في الدليل java-hello (لا تنسَ إضافة النقطة في النهاية).
```
jar cvf apiproxy/resources/java/edge-custom-policy-java-hello.jar -C com .
```

نشر الخادم الوكيل والاتصال به

يتم توفير نص برمجي للتفعيل في دليل ./java-hello. ولكن قبل تشغيله، عليك إجراء إعداد سريع.

القرص المضغوط إلى api-platform-samples/doc-samples/java-hello
إذا لم يسبق لك إجراء ذلك، افتح الملف ../../setup/setenv.sh وعدِّله كما هو موضّح في معلومات حسابك على Apigee: اسم المستخدم (عنوان البريد الإلكتروني المرتبط بحسابك) واسم مؤسستك والنطاق الذي تستخدمه لإجراء طلبات إدارة واجهة برمجة التطبيقات. على سبيل المثال، بالنسبة إلى سحابة Edge، يكون النطاق هو https://api.enterprise.apigee.com، ولكن قد يكون نطاقك مختلفًا إذا كنت تستخدم Edge Private Cloud.
احفظ الملف setenv.sh.
نفِّذ النص البرمجي للتفعيل:
```
./deploy.sh
```
في حال نجاح عملية النشر، نفِّذ النص البرمجي للاستدعاء:
```
./invoke.sh
```
يستدعي النص البرمجي للاستدعاء أمر cURL يبدو على النحو التالي:
```
curl  http://$org-$env.$api_domain/java-hello -H "username:Will"
```
الذي يعرض "Hello, Will!

يمكنك تعديل النص البرمجي invoke.sh لتغيير الاسم، أو إذا غيّرت استدعاء cURL لإزالة العنوان، سيعرض الأمر "مرحبًا، ضيف!"

معلومات عن الخادم الوكيل

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

سياسة تخصيص الرسالة

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

<AssignMessage async="false" continueOnError="false" enabled="true" name="CopyHeader">     
    <DisplayName>CopyHeader</DisplayName>     
    <Copy source="request">         
        <Headers>             
          <Header name="username"/>         
        </Headers>     
    </Copy>     
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>     
    <AssignTo createNew="false" transport="http" type="response"/> 
</AssignMessage>

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

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

<JavaCallout name="hello-java">         
    <ClassName>com.apigeesample.HelloJava</ClassName>         
    <ResourceURL>java://edge-custom-policy-java-hello.jar</ResourceURL> 
</JavaCallout>

ما تحتاج إلى معرفته عن وسيلة شرح Java

أمور مهمة يجب ملاحظتها حول تنفيذ وسيلة شرح جافا هي:

لاستيراد الصفوف من حِزمتَي com.apigee.flow.execution وcom.apigee.flow.message. يجب تضمين هذه الحِزم في ملف JAR الذي يتم تعبئته ونشره. يمكنك تحميل Java JAR من خلال محرِّر الخادم الوكيل لواجهة المستخدم الإدارية، أو يمكنك تضمينه في دليل /resources/java في الخوادم الوكيلة لواجهة برمجة التطبيقات التي تطوّرها محليًا.
تنفيذ واجهة التنفيذ. أي رمز Java يتم تنفيذه داخل خادم وكيل لواجهة برمجة التطبيقات يجب أن ينفّذ التنفيذ.
لا تحتوي سياسة وسائل شرح Java على أي رمز فعلي. وبدلاً من ذلك، تشير سياسة وسائل شرح Java إلى "مورد" Java يجب تجميعه في JAR.
يجب عدم استخدام أسماء الحِزم: لا تستخدم io.apigee أو com.apigee كأسماء حِزم في وسائل شرح Java. هذه الوحدات محجوزة وتستخدمها وحدات Apigee أخرى.
إذا كانت وسيلة شرح Java تعتمد على مكتبات إضافية تابعة لجهات خارجية تكون مضمّنة في ملفات JAR مستقلة، عليك وضع ملفات JAR هذه في دليل /resources/java أيضًا لضمان تحميلها بشكل صحيح في وقت التشغيل.
في حال وجود العديد من عناصر JAR، ما عليك سوى إضافتها كموارد إضافية. ولن تحتاج إلى تعديل ضبط السياسة للإشارة إلى ملفات JAR الإضافية. يكفي وضعها في /resources/java.
للحصول على معلومات إضافية عن تحميل تطبيقات Java JAR، يُرجى الاطّلاع على ملفات الموارد.