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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

برای ساده کردن کارها، ما یک پروژه اساسی در GitHub در مخزن Api-platform-samples Apigee برای شما آماده کرده ایم.

نمونه های پلتفرم api را در سیستم خود دانلود یا کلون کنید.
در ترمینال یا ویرایشگر کد مورد نظر خود، به پروژه 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 در آن اجرا می شود دسترسی داشته باشید. فرض کنید خط مشی فراخوانی جاوا به جریان پاسخ نقطه پایانی پروکسی متصل است. کد فهرست شده در بالا، شیء پیام HTTP را برای آن زمینه جریان دریافت می کند. شی Message به نوبه خود به شما امکان دسترسی به هدرها، پارامترهای پرس و جو، محتوای بدنه و متغیرهای جریان را می دهد.
فایل را ذخیره کنید.

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

در مورد پروکسی

بیایید به سرعت سیاست های استفاده شده در این پراکسی را بررسی کنیم. توجه داشته باشید که سیاست ها در کجا و چرا در جریان پروکسی قرار می گیرند.

خط مشی پیام اختصاص دادن

یک خط مشی پیام اختصاص به جریان درخواست 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>

خط مشی فراخوانی جاوا

خط مشی فراخوانی جاوا به جریان پاسخ پیوست شده است. این به این دلیل است که کد جاوا سفارشی تغییراتی را در هدرهای پاسخ و پیام ایجاد می کند. عنصر 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 که بسته‌بندی و مستقر می‌شود گنجانده شوند. می‌توانید Java JAR خود را از طریق ویرایشگر پروکسی مدیریت رابط کاربری آپلود کنید، یا می‌توانید آن را در فهرست /resources/java در پراکسی‌های API که به صورت محلی توسعه می‌دهید قرار دهید.
رابط Execution را پیاده سازی می کند. هر کد جاوا که در یک پروکسی API اجرا می شود باید Execution را پیاده سازی کند.
یک خط مشی فراخوانی جاوا حاوی هیچ کد واقعی نیست. در عوض، یک خط‌مشی جاوا Callout به یک «منبع» جاوا اشاره می‌کند که باید آن را در JAR بسته بندی کنید.
از نام‌های بسته‌هایی که باید اجتناب کنید: از io.apigee یا com.apigee به عنوان نام بسته‌ها در Java Callouts استفاده نکنید. آن‌ها توسط سایر ماژول‌های Apigee رزرو شده و استفاده می‌شوند.
اگر Java Callout شما به کتابخانه های شخص ثالث دیگری که به عنوان فایل های JAR مستقل بسته بندی شده اند متکی است، آن فایل های JAR را در فهرست /resources/java نیز قرار دهید تا مطمئن شوید که در زمان اجرا به درستی بارگذاری می شوند.
اگر چندین JAR وجود دارد، به سادگی آنها را به عنوان منابع اضافی اضافه کنید. برای مراجعه به فایل های JAR اضافی، نیازی به تغییر پیکربندی خط مشی ندارید. قرار دادن آنها در /resources/java کافی است.
برای اطلاعات بیشتر در مورد بارگذاری جاوا JAR ها، فایل های منابع را ببینید.