خط مشی JavaCallout

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

چه

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

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

چه زمانی

برای راهنمایی، به بخش «چه زمانی باید از یک فراخوانی جاوا استفاده کنم؟» در نحوه ایجاد یک فراخوانی جاوا مراجعه کنید.

درباره ما

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

شما می‌توانید برنامه جاوا خود را با هر فایل JAR مورد نیاز خود بسته‌بندی کنید. توجه داشته باشید که محدودیت‌هایی در مورد کارهایی که می‌توانید با Java Callout انجام دهید وجود دارد. این محدودیت‌ها در زیر در بخش محدودیت‌ها فهرست شده‌اند.

نمونه‌ها

مثال ساده

نحوه ایجاد یک فراخوان جاوا

بازیابی ویژگی‌ها در کد جاوا

عنصر <Property> در این سیاست به شما امکان می‌دهد یک جفت نام/مقدار مشخص کنید که می‌توانید در زمان اجرا در کد جاوای خود بازیابی کنید. برای یک مثال کاربردی که از ویژگی‌ها استفاده می‌کند، به نحوه استفاده از ویژگی‌ها در یک فراخوانی جاوا مراجعه کنید.

از ویژگی name عنصر <Property> برای مشخص کردن نامی که با آن می‌توان از طریق کد جاوا به ویژگی دسترسی پیدا کرد، استفاده کنید. مقدار عنصر <Property> (مقداری که بین تگ‌های باز و بسته قرار می‌گیرد) مقداری است که توسط کد جاوا دریافت می‌شود. مقدار باید یک رشته باشد؛ شما نمی‌توانید برای دریافت مقدار به یک متغیر جریان ارجاع دهید.

  • ویژگی را پیکربندی کنید. در اینجا، مقدار ویژگی، متغیری با نام response.status.code است. 
    <JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout">
    <DisplayName>JavaCallout</DisplayName>
    <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
    <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
    <Properties>
        <Property name="source">response.status.code</Property>
    </Properties>
</Javascript>
  • در کد جاوای خود، سازنده‌ی زیر را روی پیاده‌سازی کلاس Execution به صورت زیر پیاده‌سازی کنید:
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){

            // Extract property values from map.
    }
    ...
}

متغیرهای جریان را در کد جاوا خود تنظیم کنید

برای توضیح واضح نحوه تنظیم متغیرها در متن پیام (متغیرهای جریان) در کد جاوا، به این پست انجمن Apigee مراجعه کنید.

مرجع عنصر

مرجع عنصر، عناصر و ویژگی‌های سیاست JavaCallout را توصیف می‌کند.

<JavaCallout name="MyJavaCalloutPolicy">
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
</JavaCallout>

ویژگی‌های <JavaCallout> 

<JavaCallout name="MyJavaCalloutPolicy" enabled="true" continueOnError="false" async="false" >

جدول زیر ویژگی هایی را توصیف می کند که برای همه عناصر اصلی خط مشی مشترک هستند:

صفت توضیحات پیش فرض حضور
name

نام داخلی سیاست. مقدار مشخصه name می تواند شامل حروف، اعداد، فاصله، خط تیره، زیرخط و نقطه باشد. این مقدار نمی تواند بیش از 255 کاراکتر باشد.

در صورت تمایل، از عنصر <DisplayName> برای برچسب گذاری خط مشی در ویرایشگر پروکسی UI مدیریت با نامی به زبان طبیعی دیگر استفاده کنید.

 N/A مورد نیاز
continueOnError

برای بازگرداندن خطا در صورت شکست خط مشی، روی false تنظیم کنید. این رفتار مورد انتظار برای اکثر سیاست ها است.

روی true تنظیم کنید تا اجرای جریان حتی پس از شکست خط مشی ادامه یابد.

 نادرست اختیاری
enabled

برای اجرای خط مشی روی true تنظیم کنید.

برای خاموش کردن خط مشی، روی false تنظیم کنید. این سیاست حتی اگر به یک جریان وابسته باشد اجرا نخواهد شد.

 درست است اختیاری
async

این ویژگی منسوخ شده است.

 نادرست منسوخ شده است

عنصر <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>
پیش فرض

N/A

اگر این عنصر را حذف کنید، از مقدار ویژگی name خط مشی استفاده می شود.

حضور اختیاری
تایپ کنید رشته

عنصر <ClassName>

نام کلاس جاوا را مشخص می‌کند که هنگام اجرای سیاست فراخوانی جاوا اجرا می‌شود. این کلاس باید در فایل JAR مشخص شده توسط <ResourceURL> گنجانده شود. همچنین به نحوه ایجاد یک فراخوانی جاوا مراجعه کنید.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
پیش‌فرض: ناموجود
حضور: مورد نیاز
نوع: رشته

عنصر <ویژگی>

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

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
پیش‌فرض: هیچکدام
حضور: اختیاری
نوع: رشته

ویژگی‌ها

ویژگی توضیحات پیش‌فرض حضور
نام

نام ملک را مشخص می‌کند.

 ناموجود الزامی است.

عنصر <ResourceURL>

این عنصر فایل JAR جاوا را مشخص می‌کند که هنگام اجرای سیاست فراخوانی جاوا اجرا خواهد شد.

می‌توانید این فایل را در محدوده‌ی پروکسی API (در مسیر /apiproxy/resources/java در بسته‌ی پروکسی API یا در بخش اسکریپت‌ها از پنل Navigator ویرایشگر پروکسی API) یا در محدوده‌های سازمان یا محیط برای استفاده‌ی مجدد در چندین پروکسی API، همانطور که در فایل‌های منبع توضیح داده شده است، ذخیره کنید.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
پیش‌فرض: هیچکدام
حضور: مورد نیاز
نوع: رشته

مرجع خطا

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

خطاهای زمان اجرا

این خطاها ممکن است هنگام اجرای سیاست رخ دهند.

کد خطا وضعیت HTTP علت رفع کنید
steps.javacallout.ExecutionError 500 زمانی اتفاق می‌افتد که کد جاوا در طول اجرای یک خط‌مشی JavaCallout یک استثنا ایجاد می‌کند یا null را برمی‌گرداند.

خطاهای استقرار

این خطاها می توانند زمانی رخ دهند که پروکسی حاوی خط مشی مستقر است.

نام خطا رشته خطا وضعیت HTTP زمانی رخ می دهد
ResourceDoesNotExistResource with name [name] and type [type] does not exist N/A فایل مشخص شده در عنصر <ResourceURL> وجود ندارد.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] N/A فایل کلاس مشخص شده در عنصر <ClassName> در jar نیست.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] N/A رشته خطا را ببینید. همچنین به نرم افزارهای پشتیبانی شده و نسخه های پشتیبانی شده مراجعه کنید.
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] N/A رشته خطا را ببینید.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] N/A رشته خطا را ببینید.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] N/A رشته خطا را ببینید.
NoResourceForURL Could not locate a resource with URL [string] N/A رشته خطا را ببینید.

متغیرهای خطا

این متغیرها زمانی تنظیم می شوند که این خط مشی خطایی را ایجاد کند. برای اطلاعات بیشتر، به آنچه باید در مورد خطاهای خط مشی بدانید مراجعه کنید.

متغیرها کجا مثال
fault.name=" fault_name " fault_name نام خطا است، همانطور که در جدول خطاهای Runtime در بالا ذکر شده است. نام خطا آخرین قسمت کد خطا است. fault.name Matches "ExecutionError"
javacallout. policy_name .failed policy_name نام سیاستی است که توسط کاربر مشخص شده است که خطا را ایجاد کرده است. javacallout.JC-GetUserData.failed = true

نمونه پاسخ خطا 

{  
   "fault":{  
      "faultstring":"Failed to execute JavaCallout. [policy_name]",
      "detail":{  
         "errorcode":"javacallout.ExecutionError"
      }
   }
}

مثال قانون خطا 

<FaultRule name="JavaCalloutFailed">
    <Step>
        <Name>AM-JavaCalloutError</Name>
    </Step>
    <Condition>(fault.name Matches "ExecutionError") </Condition>
</FaultRule>

طرحواره‌ها

کامپایل و استقرار

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

محدودیت‌ها

محدودیت‌هایی که هنگام نوشتن Calloutهای جاوا باید در نظر بگیرید، در زیر آمده است:

  • اکثر فراخوانی‌های سیستمی مجاز نیستند. برای مثال، شما نمی‌توانید خواندن یا نوشتن فایل سیستم داخلی را مجاز کنید.
  • دسترسی به شبکه از طریق سوکت‌ها. Apigee دسترسی به آدرس‌های sitelocal، anylocal، loopback و linklocal را محدود می‌کند.
  • این فراخوانی نمی‌تواند اطلاعاتی در مورد فرآیند فعلی، لیست فرآیندها یا میزان استفاده از CPU/حافظه در دستگاه دریافت کند. اگرچه برخی از این فراخوانی‌ها ممکن است کاربردی باشند، اما پشتیبانی نمی‌شوند و ممکن است در هر زمانی به طور فعال غیرفعال شوند. برای سازگاری رو به جلو، باید از انجام چنین فراخوانی‌هایی در کد خود خودداری کنید.
  • تکیه بر کتابخانه‌های جاوا که در Apigee Edge گنجانده شده‌اند، پشتیبانی نمی‌شود. این کتابخانه‌ها فقط برای عملکرد محصول Edge هستند و هیچ تضمینی وجود ندارد که یک کتابخانه از انتشاری به انتشار دیگر در دسترس باشد.
  • io.apigee یا com.apigee به عنوان نام بسته در Java Callouts استفاده نکنید. این نام‌ها رزرو شده و توسط سایر ماژول‌های Apigee استفاده می‌شوند.

بسته بندی

فایل JAR را در یک پروکسی API در مسیر /resources/java قرار دهید. اگر Java Callout شما به کتابخانه‌های شخص ثالث دیگری که به صورت فایل‌های JAR مستقل بسته‌بندی شده‌اند، متکی است، آن فایل‌های JAR را نیز در دایرکتوری /resources/java قرار دهید تا از بارگذاری صحیح آنها در زمان اجرا اطمینان حاصل شود.

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

برای اطلاعات بیشتر در مورد آپلود فایل‌های JAR جاوا، به فایل‌های منبع مراجعه کنید.

برای مثال مفصلی که نحوه بسته‌بندی و استقرار یک Callout جاوا با استفاده از Maven یا javac را نشان می‌دهد، به نحوه ایجاد یک Callout جاوا مراجعه کنید.

جوادوک

Javadoc برای نوشتن کد Java Callout اینجا در GitHub گنجانده شده است. شما باید HTML را روی سیستم خود کپی یا دانلود کنید و سپس به سادگی فایل index.html را در یک مرورگر باز کنید.

یادداشت‌های استفاده

  • یک سیاست فراخوانی جاوا (Java Callout policy) حاوی هیچ کد واقعی نیست. در عوض، یک سیاست فراخوانی جاوا به یک «منبع» جاوا ارجاع می‌دهد و مرحله‌ای را در جریان API تعریف می‌کند که کد جاوا در آن اجرا می‌شود. می‌توانید فایل جاوا JAR خود را از طریق ویرایشگر پروکسی رابط کاربری مدیریت (Management UI proxy editor) آپلود کنید، یا می‌توانید آن را در دایرکتوری /resources/java در پروکسی‌های API که به صورت محلی توسعه می‌دهید، قرار دهید.
  • برای عملیات سبک، مانند فراخوانی‌های API به سرویس‌های راه دور، توصیه می‌کنیم از سیاست ServiceCallout استفاده کنید. به سیاست Service Callout مراجعه کنید.
  • برای تعاملات نسبتاً ساده با محتوای پیام، مانند تغییر یا استخراج هدرهای HTTP، پارامترها یا محتوای پیام، Apigee استفاده از یک سیاست جاوا اسکریپت را توصیه می‌کند.

مباحث مرتبط