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

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

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

ما هي Java Callout؟

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

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

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

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

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

متى يجب استخدام Java Callout؟

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

أولاً، ننصحك بالتفكير في أساليب بديلة

قبل استخدام وسيط برمجي Java، يُرجى العِلم أنّه قد تكون هناك طرق بديلة يمكنك استخدامها بدلاً من ذلك. على سبيل المثال:

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

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

تتيح عملية الربط الخارجية في Java العمليات الأساسية التالية:

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

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

لا يُسمح بمعظم طلبات النظام. لا يمكنك إجراء ما يلي:

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

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

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

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

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

إذا أرسلت عنوان "اسم المستخدم" مع قيمة "الاسم"، سيعرض الخادم الوكيل ما يلي:
```
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 Callout. توفّر هذه الفئات طرقًا تتيح لك الوصول إلى سياق تنفيذ الخادم الوكيل. سنشرح لك قريبًا خطوات تجميع هذه الرموز البرمجية ونشرها.

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

cd إلى 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. ولكن قبل تشغيله، عليك إجراء عملية إعداد سريعة.

cd إلى api-platform-samples/doc-samples/java-hello
إذا لم يسبق لك إجراء ذلك، افتح الملف ../../setup/setenv.sh وعدِّله كما هو موضّح باستخدام معلومات حسابك على Apigee: اسم المستخدم (عنوان البريد الإلكتروني المرتبط بحسابك) واسم مؤسستك والنطاق الذي تستخدمه لإجراء طلبات إدارة واجهة برمجة التطبيقات. على سبيل المثال، بالنسبة إلى Edge Cloud، يكون النطاق هو 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 Callout، المرفقة بتدفق الاستجابة، الوصول إلى عنوان اسم المستخدم وإنشاء نص استجابة مخصّص باستخدام قيمة هذا العنوان.

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

يتم إرفاق سياسة Java callout بتسلسل الردود. ويرجع ذلك إلى أنّ رمز 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 callout

في ما يلي بعض الملاحظات المهمة حول تنفيذ عملية استدعاء Java:

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