‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

نحوه ایجاد یک تماس با جاوا

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

«تماس با Java» چیست؟

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

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

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

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

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

چه زمانی باید از یک تماس Java استفاده کنم؟

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

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

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

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

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

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

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

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

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

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

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

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

سلام نوشته راهنمای Java

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

اگر سرصفحه «نام کاربری» را با مقدار «نام» ارسال کنید، پراکسی این موارد را برمی‌گرداند:
```
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 است که پیاده‌سازی خواهیم کرد. بسته‌های واردشده برای کد «نوشته راهنمای تماس Java Edge» لازم است. این کلاس‌ها روش‌هایی را ارائه می‌دهند که به شما امکان می‌دهد به زمینه اجرای پراکسی دسترسی پیدا کنید. به‌زودی مراحل گردآوری و استقرار این کد را مرور خواهیم کرد.

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