خط مشی JavaCallout

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

چی

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

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

چه زمانی

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

درباره

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

می توانید برنامه جاوا خود را با هر بسته فایل 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>

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

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

عنصر <Property>

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

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

صفات

صفت توضیحات پیش فرض حضور
نام

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

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

عنصر <ResourceURL>

این عنصر فایل جاوا JAR را مشخص می کند که با اجرای خط مشی فراخوانی جاوا اجرا می شود.

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

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

مرجع خطا

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.javacallout.ExecutionError 500 Occurs when Java code throws an exception or returns null during the execution of a JavaCallout policy.

Deployment errors

These errors can occur when the proxy containing the policy is deployed.

Error name Fault string HTTP status Occurs when
ResourceDoesNotExist Resource with name [name] and type [type] does not exist N/A The file specified in the <ResourceURL> element does not exist.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] N/A The class file specified in the <ClassName> element is not in the jar.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] N/A See fault string. See also Supported software and supported versions.
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] N/A See fault string.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] N/A See fault string.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] N/A See fault string.
NoResourceForURL Could not locate a resource with URL [string] N/A See fault string.

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "ExecutionError"
javacallout.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. javacallout.JC-GetUserData.failed = true

Example error response

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

Example fault rule

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

طرحواره ها

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

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

محدودیت ها

در زیر محدودیت هایی وجود دارد که باید هنگام نوشتن Java Callouts در نظر بگیرید:

  • اکثر تماس های سیستمی غیر مجاز هستند. به عنوان مثال، شما نمی توانید سیستم فایل داخلی را بخواند یا بنویسد.
  • دسترسی به شبکه از طریق سوکت 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 ها، فایل های منابع را ببینید.

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

جوادوک

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

نکات استفاده

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

موضوعات مرتبط