خط‌مشی JavaCallout

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

چه

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

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

زمان

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

درباره

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

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

نمونه‌ها

مثال ساده

نحوه ایجاد کردن «نوشته راهنمای» Java

بازیابی کردن دارایی‌ها در کد جاوا

عنصر <Property> خط‌مشی به شما امکان می‌دهد جفت نام/مقدار را مشخص کنید که می‌توانید در زمان اجرا در کد Java خود بازیابی کنید. برای دیدن نمونه کاری که از دارایی‌ها استفاده می‌کند، به نحوه استفاده از دارایی‌ها در «تمام‌بر» Java مراجعه کنید.

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

  • دارایی را پیکربندی کنید. در اینجا، مقدار دارایی نام متغیر 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>
  • در کد جاوا، سازنده زیر را در پیاده‌سازی کلاس «اجرا» به‌صورت زیر پیاده‌سازی کنید:
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){

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

متغیرهای جاری‌سازی را در کد Java تنظیم کنید

برای شرح واضح نحوه تنظیم متغیرها در بافت پیام (متغیرهای جاری‌سازی) در کد Java خود، این پست «انجمن 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 را مشخص می‌کند که وقتی خط‌مشی «تماس با Java» اجرا می‌شود، اجرا می‌شود. کلاس باید در فایل JAR مشخص‌شده توسط <ResourceURL> گنجانده شود. همچنین نحوه ساختن «نوشته راهنمای Java» را ببینید.

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

عنصر <Property>

مشخص می‌کند که در زمان اجرا می‌توانید از کد Java به کدام دارایی دسترسی داشته باشید. باید مقدار رشته‌ای حرفی برای هر دارایی مشخص کنید؛ نمی‌توانید در این عنصر به متغیرهای جریان کار ارجاع دهید. برای نمونه کاری که از دارایی‌ها استفاده می‌کند، به نحوه استفاده از دارایی‌ها در ندای Java مراجعه کنید.

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

مشخصه‌ها

مشخصه شرح پیش‌فرض حضور
نام

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

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

عنصر<ResourceURL>

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

می‌توانید این فایل را در محدوده پراکسی 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 و استقرار آن با پراکسی، به نحوه ایجاد یک ندای کمکی Java مراجعه کنید.

محدودیت‌ها

در زیر محدودیت‌هایی را که باید هنگام نوشتن «تماس‌های بیرونی Java» درنظر بگیرید مشاهده می‌کنید:

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

بسته بندی

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

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

برای اطلاعات درباره بارگذاری Java JAR، به فایل‌های منبع مراجعه کنید.

برای دیدن نمونه‌ای دقیق که نحوه بسته‌بندی و استقرار «پیام‌واره Java» را بااستفاده از Maven یا javac نشان می‌دهد، به نحوه ایجاد پیام‌واره Java مراجعه کنید.

Javadoc

‫Javadoc برای نوشتن کد «تماس با جاوا» در اینجا در GitHub ارائه شده است. باید HTML را در سیستم خود شبیه‌سازی یا بارگیری کنید، و سپس به‌سادگی فایل index.html را در مرورگر باز کنید.

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

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

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