این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

چگونه یک فراخوان جاوا ایجاد کنیم

شما در حال مشاهده مستندات Apigee Edge هستید.
به مستندات Apigee X مراجعه کنید . اطلاعات

فراخوانی جاوا چیست؟

Apigee Edge طیف وسیعی از سیاست‌ها را ارائه می‌دهد که الزامات رایج مدیریت API مانند امنیت، تبدیل داده‌ها، مدیریت ترافیک و موارد دیگر را برطرف می‌کند.

با این حال، مواردی وجود دارد که API شما نیاز به رفتار سفارشی دارد که در یک سیاست استاندارد پیاده‌سازی نشده است. در این موارد، Apigee گزینه‌های مختلفی را ارائه می‌دهد که شما را قادر می‌سازد رفتار API سفارشی را اسکریپت یا کدنویسی کنید. یک رویکرد، پیاده‌سازی رفتار مورد نظر در جاوا است.

برای نسخه‌های پشتیبانی‌شده جاوا، به نرم‌افزارهای پشتیبانی‌شده و نسخه‌های پشتیبانی‌شده مراجعه کنید.

چگونه می‌توانم از کد جاوا در پروکسی استفاده کنم؟

یک سیاست فراخوانی جاوا به شما امکان می‌دهد کد جاوا را از درون یک جریان پروکسی در حال اجرا فراخوانی کنید. کد جاوای شما باید رابط‌های جاوای خاص Edge را پیاده‌سازی کند که به کد اجازه می‌دهد با پروکسی در حال اجرا تعامل داشته باشد. به عنوان مثال، متدهای جاوا برای دریافت و تنظیم هدرها، پارامترهای پرس و جو، متغیرهای جریان و سایر موجودیت‌ها در چارچوب جریان فعلی پروکسی وجود دارد.

چه زمانی باید از فراخوانی جاوا استفاده کنم؟

بیایید به موقعیت‌هایی که فراخوانی‌های جاوا مفید هستند و موقعیت‌هایی که باید رویکردهای دیگری را در نظر بگیرید، نگاهی بیندازیم.

اول، رویکردهای جایگزین را در نظر بگیرید

قبل از استفاده از فراخوانی جاوا، توجه داشته باشید که ممکن است رویکردهای جایگزینی وجود داشته باشد که بتوانید به جای آن استفاده کنید. برای مثال:

برای عملیات سبک، مانند فراخوانی‌های HTTP API به سرویس‌های راه دور، استفاده از سیاست ServiceCallout را در نظر بگیرید. به سیاست Service Callout مراجعه کنید.
برای تعاملات نسبتاً ساده با محتوای پیام، مانند تغییر یا استخراج هدرهای HTTP، پارامترها یا محتوای پیام، می‌توانید از زبان‌های جاوا اسکریپت یا پایتون استفاده کنید.

کارهایی که می‌توانید با کد جاوا انجام دهید

یک فراخوانی جاوا از این عملیات اساسی پشتیبانی می‌کند:

بررسی یا دستکاری پیام‌های درخواست یا پاسخ
دریافت و تنظیم متغیرهای جریان. می‌توانید از متدهای جاوا برای دسترسی به متغیرهای جریان لبه استفاده کنید. اگر می‌خواهید به اطلاعات نقشه کلید مقدار (KVM) دسترسی داشته باشید، از یک سیاست KVM استفاده کنید، مقادیر KVM را به متغیرهای جریان اختصاص دهید و سپس می‌توانید از درون فراخوانی جاوا به متغیرهای جریان دسترسی پیدا کنید.
فراخوانی سرویس‌های خارجی
افزایش گسل‌ها
دستکاری پیام‌های خطا و کدهای وضعیت

کاری که نمی‌توانید در کد جاوا انجام دهید

اکثر فراخوانی‌های سیستمی مجاز نیستند. شما نمی‌توانید :

خواندن یا نوشتن در سیستم فایل داخلی را فعال کنید. این بدان معناست که شما نمی‌توانید از هیچ یک از بسته‌های جاوا برای خواندن/نوشتن در سیستم‌های فایل داخلی استفاده کنید. با این حال، می‌توانید فراخوانی‌های از راه دور خارجی را انجام دهید.
اطلاعاتی در مورد فرآیند فعلی، لیست فرآیندها یا میزان استفاده از CPU/حافظه در دستگاه دریافت کنید.
به کد منبع در فایل‌های `expressions-1.0.0.jar` و `message-flow-1.0.0.jar` دسترسی پیدا کنید.

اگرچه برخی از این فراخوانی‌ها ممکن است کار کنند، اما پشتیبانی نمی‌شوند و ممکن است در هر زمانی غیرفعال شوند. از انجام چنین فراخوانی‌هایی در کد خود خودداری کنید.

از کتابخانه‌های جاوا که همراه با Apigee Edge ارائه می‌شوند استفاده نکنید و به آنها تکیه نکنید. این کتابخانه‌ها فقط برای عملکرد محصول Edge هستند و هیچ تضمینی وجود ندارد که یک کتابخانه از انتشاری به انتشار دیگر در دسترس باشد. اگر از چنین کتابخانه‌هایی استفاده می‌کنید، فقط از آنها در نسخه‌های غیرعملیاتی استفاده کنید.

سلام، فراخوان جاوا

بیایید یک مثال ساده از فراخوانی hello world در جاوا را بررسی کنیم. در این مثال، یک پروکسی ساده با فراخوانی جاوا ایجاد می‌کنیم که پاسخ "hello world" را برمی‌گرداند. پروکسی می‌تواند یکی از دو پاسخ ممکن را برگرداند:

اگر یک هدر "username" با مقدار "name" ارسال کنید، پروکسی مقدار زیر را برمی‌گرداند:
```
Hello, <name>!
```
اگر هدر را حذف کنید، پروکسی فقط مقدار زیر را برمی‌گرداند:
```
"Hello, Guest!"
```

پروژه اولیه را دانلود کنید

برای ساده‌تر کردن کار، ما یک پروژه اولیه برای شما در گیت‌هاب در مخزن api-platform-samples آپیجی آماده کرده‌ایم.

api-platform-samples را دانلود یا روی سیستم خود کپی کنید.
در یک ترمینال یا ویرایشگر کد دلخواه خود، به پروژه api-platform-samples/doc-samples/java-hello بروید.

کد جاوا را بنویسید

فایل منبع جاوا را باز کنید: java-hello/callout/src/main/java/HelloJava.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 به جریان Proxy Endpoint Response متصل شده است. کد ذکر شده در بالا، شیء HTTP Message را برای آن جریان دریافت می‌کند. شیء Message به نوبه خود، به شما امکان دسترسی به هدرها، پارامترهای پرس‌وجو، محتوای بدنه و متغیرهای جریان را می‌دهد.
فایل را ذخیره کنید.

کد خود را با Maven کامپایل کنید

این پروژه طوری تنظیم شده است که بتوانید با Maven کامپایل کنید. اگر می‌خواهید از javac استفاده کنید، مثالی را پس از مثال Maven قرار خواهیم داد.

مطمئن شوید که Maven را نصب کرده‌اید:
```
mvn -version
```
اسکریپت java-hello/buildsetup.sh را اجرا کنید. این اسکریپت وابستگی‌های JAR مورد نیاز را در مخزن محلی Maven شما نصب می‌کند.
با استفاده از cd به پوشه java-hello/callout .
اجرای Maven:
```
mvn clean package
```
نکته: اگر با خطای Maven مواجه شدید، مطمئن شوید که در دایرکتوری java-hello/callout هستید.
در صورت تمایل، تأیید کنید که فایل JAR edge-custom-policy-java-hello.jar در java-hello/apiproxy/resources/java کپی شده است. این مکان مورد نیاز برای فایل‌های JAR است که می‌خواهید با یک پروکسی مستقر کنید.

کامپایل با جاوا (اختیاری)

در بخش قبل، شما فایل JAR جاوا مورد نیاز را به طور خودکار با یک دستور Maven تولید کردید. به طور جایگزین، اگر می‌خواهید از javac برای کامپایل کد استفاده کنید، می‌توانید کاری مشابه زیر (از دایرکتوری java-hello ) انجام دهید. فایل‌های JAR مورد نیاز در دایرکتوری java-hello/lib برای شما فراهم شده‌اند.

با دستور cd به api-platform-samples/doc-samples/java-hello .
مطمئن شوید که javac را در مسیر خود دارید.
```
javac -version
```
دستور جاواک زیر را اجرا کنید:
```
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 خود ویرایش کنید: نام کاربری (آدرس ایمیل مرتبط با حساب شما)، نام سازمان و دامنه‌ای که برای برقراری تماس‌های مدیریت API استفاده می‌کنید. به عنوان مثال، برای Edge cloud، دامنه https://api.enterprise.apigee.com است؛ با این حال، اگر از Edge Private Cloud استفاده می‌کنید، دامنه شما ممکن است متفاوت باشد.
فایل setenv.sh را ذخیره کنید.
اسکریپت استقرار را اجرا کنید:
```
./deploy.sh
```
اگر استقرار موفقیت‌آمیز بود، اسکریپت فراخوانی را اجرا کنید:
```
./invoke.sh
```
اسکریپت invoke یک دستور cURL را فراخوانی می‌کند که به صورت زیر است:
```
curl  http://$org-$env.$api_domain/java-hello -H "username:Will"
```
که برمی‌گرداند «سلام، ویل!»
شما می‌توانید اسکریپت invoke.sh را برای تغییر نام ویرایش کنید، یا اگر فراخوانی cURL را برای حذف هدر تغییر دهید، دستور "Hello, Guest!" را برمی‌گرداند.

درباره پروکسی

بیایید به سرعت سیاست‌های مورد استفاده در این پروکسی را بررسی کنیم. به محل قرارگیری سیاست‌ها در جریان پروکسی و دلیل آن توجه کنید.

سیاست اختصاص پیام

یک سیاست پیام Assign به جریان درخواست ProxyEndpoint پیوست شده است. این سیاست، هدر نام کاربری را از درخواست کپی کرده و آن را به پاسخ اختصاص می‌دهد. این عملیات به سیاست 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>

سیاست فراخوانی جاوا

سیاست فراخوانی جاوا به جریان پاسخ متصل است. دلیل این امر این است که کد جاوای سفارشی تغییراتی را در هدرهای پاسخ و پیام ایجاد می‌کند. عنصر ClassName این سیاست، کلاس اصلی را که توسط این سیاست اجرا می‌شود، مشخص می‌کند. عنصر ResourceURL نام فایل JAR است که شما ساخته‌اید و به دایرکتوری resources/java پروکسی اضافه کرده‌اید.

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

آنچه باید در مورد فراخوانی جاوا بدانید

نکات مهمی که باید در مورد پیاده‌سازی فراخوانی جاوا به آنها توجه داشت عبارتند از:

کلاس‌هایی را از بسته‌های com.apigee.flow.execution و com.apigee.flow.message وارد می‌کند. این بسته‌ها باید در فایل JAR که بسته‌بندی و مستقر می‌شود، گنجانده شوند. می‌توانید JAR جاوای خود را از طریق ویرایشگر پروکسی رابط کاربری مدیریت (Management UI proxy editor) آپلود کنید، یا می‌توانید آن را در دایرکتوری /resources/java در پروکسی‌های API که به صورت محلی توسعه می‌دهید، قرار دهید.
رابط اجرایی (Execution interface) را پیاده‌سازی می‌کند. هر کد جاوا که درون یک پروکسی API اجرا می‌شود، باید اجرایی (Execution) را پیاده‌سازی کند.
یک خط‌مشی فراخوانی جاوا (Java Callout) حاوی هیچ کد واقعی نیست. در عوض، یک خط‌مشی فراخوانی جاوا به یک «منبع» جاوا اشاره می‌کند که باید آن را در یک JAR بسته‌بندی کنید.
نام‌های بسته‌ای که باید از آنها اجتناب کنید: در Java Calloutها از io.apigee یا com.apigee به عنوان نام بسته استفاده نکنید. این نام‌ها رزرو شده و توسط سایر ماژول‌های Apigee استفاده می‌شوند.
اگر Java Callout شما به کتابخانه‌های شخص ثالث دیگری که به صورت فایل‌های JAR مستقل بسته‌بندی شده‌اند، متکی است، آن فایل‌های JAR را نیز در دایرکتوری /resources/java قرار دهید تا از بارگذاری صحیح آنها در زمان اجرا اطمینان حاصل شود.
اگر چندین فایل JAR وجود دارد، کافیست آنها را به عنوان منابع اضافی اضافه کنید. نیازی به تغییر پیکربندی خط‌مشی برای ارجاع به فایل‌های JAR اضافی نیست. قرار دادن آنها در /resources/java کافی است.
برای اطلاعات بیشتر در مورد آپلود فایل‌های JAR جاوا، به فایل‌های منبع مراجعه کنید.