خط مشی 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>
پیش فرض: هیچ کدام
حضور: مورد نیاز
نوع: رشته

مرجع خطا

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

طرحواره ها

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

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

محدودیت ها

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

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