تمت ترجمة هذه الصفحة بواسطة 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 API إلى الخدمات البعيدة، يمكنك استخدام سياسة ServiceCallout يُرجى الاطّلاع على سياسة وسيلة شرح الخدمة.
بالنسبة إلى التفاعلات البسيطة نسبيًا مع محتوى الرسائل، مثل تعديل المحتوى أو استخراجه عناوين HTTP أو المعلَمات أو محتوى الرسالة، يمكنك استخدام لغات JavaScript أو Python.

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

تدعم وسيلة شرح Java العمليات الأساسية التالية:

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

ما لا يمكنك فعله في Java رقم الاعتماد

لا يُسمح بمعظم استدعاءات النظام. لا يمكنك:

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

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

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

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

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

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

تنزيل مشروع المبتدئين

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

نزِّل 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 Callout. هيا نرى لنفترض أن سياسة وسيلة شرح 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"
```
والتي تعرض عبارة "مرحبًا يا ولاء!

يمكنك تعديل النص البرمجي "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

أمور مهمة يجب ملاحظتها حول تنفيذ وسيلة شرح 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، يُرجى الاطّلاع على ملفات الموارد.