شما در حال مشاهده اسناد Apigee Edge هستید.
به مستندات Apigee X بروید . اطلاعات
چی
این خط مشی به شما امکان می دهد کد جاوا اسکریپت سفارشی را اضافه کنید که در چارچوب یک جریان پراکسی API اجرا می شود. در کد جاوا اسکریپت سفارشی خود، می توانید از اشیاء، روش ها و ویژگی های مدل شی جاوا اسکریپت Apigee Edge استفاده کنید. مدل شی به شما امکان می دهد متغیرها را در زمینه جریان پروکسی دریافت، تنظیم و حذف کنید. همچنین میتوانید از توابع رمزنگاری اولیه که با مدل شی ارائه شدهاند استفاده کنید.
درباره
موارد استفاده زیادی برای خط مشی جاوا اسکریپت وجود دارد. به عنوان مثال، میتوانید متغیرهای جریان را دریافت و تنظیم کنید، منطق سفارشی را اجرا کنید و مدیریت خطا را انجام دهید، دادهها را از درخواستها یا پاسخها استخراج کنید، URL هدف باطن را بهصورت پویا ویرایش کنید، و موارد دیگر. این خطمشی به شما امکان میدهد رفتار سفارشی را پیادهسازی کنید که توسط سایر خطمشیهای استاندارد Edge پوشش داده نمیشود. در واقع، میتوانید از یک خطمشی جاوا اسکریپت برای دستیابی به بسیاری از رفتارهای مشابهی که توسط سیاستهای دیگر مانند AssignMessage و ExtractVariable پیادهسازی شدهاند، استفاده کنید.
یکی از موارد استفاده ای که ما برای خط مشی جاوا اسکریپت توصیه نمی کنیم، ورود به سیستم است. خطمشی Message Logging برای ورود به سیستم عاملهای ثبت شخص ثالث مانند Splunk، Sumo و Loggly بسیار مناسبتر است و با اجرای سیاست ثبت پیام در PostClientFlow، عملکرد پروکسی API را بهبود میبخشید، که پس از ارسال پاسخ اجرا میشود. به مشتری.
خط مشی جاوا اسکریپت به شما امکان می دهد یک فایل منبع جاوا اسکریپت را برای اجرا مشخص کنید یا می توانید کد جاوا اسکریپت را مستقیماً با عنصر <Source>
در پیکربندی خط مشی وارد کنید. در هر صورت، کد جاوا اسکریپت زمانی اجرا می شود که مرحله ای که خط مشی به آن متصل شده است اجرا می شود. برای گزینه فایل منبع، کد منبع همیشه در یک مکان استاندارد در بسته پروکسی ذخیره میشود: apiproxy/resources/jsc
. یا میتوانید کد منبع را در یک فایل منبع در سطح محیط یا سازمان ذخیره کنید. برای دستورالعملها، فایلهای منابع را ببینید. همچنین می توانید جاوا اسکریپت خود را از طریق ویرایشگر پروکسی Apigee UI آپلود کنید.
فایل های منبع جاوا اسکریپت همیشه باید دارای پسوند .js
باشند.
نرم افزارهای پشتیبانی شده و نسخه های پشتیبانی شده را برای نسخه پشتیبانی شده فعلی جاوا اسکریپت ببینید.
ویدئو
برای یادگیری نحوه ایجاد یک برنامه افزودنی خط مشی سفارشی با استفاده از خط مشی جاوا اسکریپت، ویدیوی کوتاهی را تماشا کنید.
نمونه ها
URL مورد نظر را دوباره بنویسید
در اینجا یک مورد استفاده رایج وجود دارد: استخراج داده از بدنه درخواست، ذخیره آن در یک متغیر جریان، و استفاده از آن متغیر جریان در جای دیگری در جریان پراکسی. فرض کنید یک برنامه دارید که کاربر نام خود را در فرم HTML وارد کرده و آن را ارسال می کند. شما می خواهید که پروکسی API داده های فرم را استخراج کند و به صورت پویا به URL مورد استفاده برای فراخوانی سرویس Backend اضافه کند. چگونه این کار را در یک خط مشی جاوس اسکریپت انجام می دهید؟
توجه: اگر میخواهید این مثال را امتحان کنید، فرض میکنیم که یک پروکسی جدید در ویرایشگر پروکسی ایجاد کردهاید. هنگامی که آن را ایجاد کردید، فقط یک URL سرویس Backend به آن بدهید: http://www.example.com. برای این مثال، ما قصد داریم URL backend را به صورت پویا بازنویسی کنیم. اگر نمی دانید چگونه یک پروکسی جدید ایجاد کنید، به آموزش شروع مراجعه کنید. .
- در Edge UI، پروکسی را که در ویرایشگر پروکسی ایجاد کرده اید باز کنید.
- تب Develop را انتخاب کنید.
- از منوی New، New Script را انتخاب کنید.
- در گفتگو، جاوا اسکریپت را انتخاب کنید و به اسکریپت یک نام مانند
js-example
بدهید. - کد زیر را در ویرایشگر کد قرار دهید و پروکسی را ذخیره کنید. نکته مهمی که باید به آن توجه کرد، موضوع
context
است. این شی برای کد جاوا اسکریپت در هر نقطه از جریان پروکسی در دسترس است. برای به دست آوردن ثابت های خاص جریان، برای فراخوانی روش های مفید دریافت/تنظیم و برای عملیات بیشتر استفاده می شود. این بخش شی از مدل شی جاوا اسکریپت Edge است. همچنین توجه داشته باشید که متغیر جریانtarget.url
یک متغیر داخلی، خواندن/نوشتن است که در جریان درخواست هدف قابل دسترسی است. وقتی آن متغیر را با URL API تنظیم می کنیم، Edge با آن URL تماس می گیرد. ما اساساً URL هدف اصلی را بازنویسی کردهایم، که همان چیزی بود که هنگام ایجاد پروکسی مشخص کردید (به عنوان مثال، http://www.example.com).
if (context.flow=="PROXY_REQ_FLOW") { var username = context.getVariable("request.formparam.user"); context.setVariable("info.username", username); } if (context.flow=="TARGET_REQ_FLOW") { context.setVariable("request.verb", "GET"); var name = context.getVariable("info.username"); var url = "http://mocktarget.apigee.net/" context.setVariable("target.url", url + "?user=" + name); }
- از منوی New Policy، جاوا اسکریپت را انتخاب کنید.
- به خط مشی یک نام بدهید، مانند
target-rewrite
. پیش فرض ها را بپذیرید و خط مشی را ذخیره کنید. - اگر Proxy Endpoint Preflow را در Navigator انتخاب کنید، خواهید دید که این خط مشی به آن جریان اضافه شده است.
- در Navigator، نماد Target Endpoint PreFlow را انتخاب کنید.
- از Navigator، خط مشی جاوا اسکریپت را به سمت درخواست نقطه پایانی هدف در ویرایشگر جریان بکشید.
- ذخیره کنید.
- API را به این شکل فراخوانی کنید و در صورت لزوم، نام سازمان و نام پروکسی صحیح خود را جایگزین کنید:
curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example
نکته آخر، بیایید نگاهی به تعریف XML برای خط مشی جاوا اسکریپت استفاده شده در این مثال بیندازیم. نکته مهمی که باید به آن توجه داشت این است که عنصر <ResourceURL>
برای تعیین فایل منبع جاوا اسکریپت برای اجرا استفاده می شود. این الگوی مشابه برای هر فایل منبع جاوا اسکریپت استفاده می شود: jsc://filename.js
. اگر کد جاوا اسکریپت به شامل نیاز دارد، میتوانید از یک یا چند عنصر <IncludeURL>
برای انجام این کار استفاده کنید، همانطور که در ادامه این مرجع توضیح داده شد.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="target-rewrite"> <DisplayName>target-rewrite</DisplayName> <Properties/> <ResourceURL>jsc://js-example.js</ResourceURL> </Javascript>
مقدار ویژگی را از جاوا اسکریپت بازیابی کنید
می توانید یک عنصر <Property>
را در پیکربندی اضافه کنید، سپس مقدار عنصر را با جاوا اسکریپت در زمان اجرا بازیابی کنید.
از ویژگی name
عنصر برای تعیین نامی که با آن از کد جاوا اسکریپت به ویژگی دسترسی داشته باشید استفاده کنید. مقدار عنصر <Property>
(مقدار بین تگ های باز و بسته) مقدار تحت اللفظی است که توسط جاوا اسکریپت دریافت می شود.
در جاوا اسکریپت، مقدار ویژگی Policy را با دسترسی به آن به عنوان ویژگی شی Properties
، مانند موارد زیر، بازیابی می کنید:
- ویژگی را پیکربندی کنید. در اینجا، مقدار ویژگی، نام متغیر
response.status.code
است.<Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="JavascriptURLRewrite"> <DisplayName>JavascriptURLRewrite</DisplayName> <Properties> <Property name="source">response.status.code</Property> </Properties> <ResourceURL>jsc://JavascriptURLRewrite.js</ResourceURL> </Javascript>
- ویژگی را با جاوا اسکریپت بازیابی کنید. در اینجا، مقدار بازیابی شده -- نام متغیر -- سپس توسط تابع
getVariable
برای بازیابی مقدار متغیر استفاده می شود.var responseCode = properties.source; // Returns "response.status.code" var value = context.getVariable(responseCode); // Get the value of response.status.code context.setVariable("response.header.x-target-response-code", value);
رسیدگی به خطاها
برای مثالها و بحث در مورد تکنیکهای مدیریت خطا که میتوانید در فراخوانی جاوا اسکریپت استفاده کنید، به این پست در انجمن Apigee مراجعه کنید. پیشنهادات ارائه شده در انجمن Apigee فقط برای اطلاع رسانی است و لزوماً بهترین شیوه های توصیه شده توسط Apigee را نشان نمی دهد.
مرجع عنصر
مرجع عنصر عناصر و ویژگی های خط مشی جاوا اسکریپت را توصیف می کند.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="JavaScript-1"> <DisplayName>JavaScript 1</DisplayName> <Properties> <Property name="propName">propertyValue</Property> </Properties> <SSLInfo> <Enabled>trueFalse</Enabled> <ClientAuthEnabled>trueFalse</ClientAuthEnabled> <KeyStore>ref://keystoreRef</KeyStore> <KeyAlias>keyAlias</KeyAlias> <TrustStore>ref://truststoreRef</TrustStore> </SSLInfo> <IncludeURL>jsc://a-javascript-library-file</IncludeURL> <ResourceURL>jsc://my-javascript-source-file</ResourceURL> <Source>insert_js_code_here</Source> </Javascript>
<Javascript> صفات
<Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">
ویژگی های زیر مختص این سیاست است.
صفت | توضیحات | پیش فرض | حضور |
---|---|---|---|
محدودیت زمانی | حداکثر زمان (بر حسب میلی ثانیه) که اسکریپت مجاز به اجرای آن است را مشخص می کند. برای مثال، اگر از حد مجاز 200 میلیثانیه فراتر رود، خطمشی این خطا را ایجاد میکند: توجه: برای حساب های آزمایشی رایگان، زمان اجرا به 200 میلی ثانیه محدود می شود. | N/A | مورد نیاز |
جدول زیر ویژگی هایی را توصیف می کند که برای همه عناصر اصلی خط مشی مشترک هستند:
صفت | توضیحات | پیش فرض | حضور |
---|---|---|---|
name | نام داخلی سیاست. مقدار مشخصه در صورت تمایل، از عنصر | N/A | مورد نیاز |
continueOnError | برای بازگرداندن خطا در صورت شکست خط مشی، روی روی | نادرست | اختیاری |
enabled | برای اجرای خط مشی روی برای خاموش کردن خط مشی، روی | درست است | اختیاری |
async | این ویژگی منسوخ شده است. | نادرست | منسوخ شده است |
عنصر <DisplayName>
علاوه بر ویژگی name
برای برچسبگذاری خطمشی در ویرایشگر پروکسی رابط کاربری مدیریت با نامی متفاوت و به زبان طبیعی، از آن استفاده کنید.
<DisplayName>Policy Display Name</DisplayName>
پیش فرض | N/A اگر این عنصر را حذف کنید، از مقدار ویژگی |
---|---|
حضور | اختیاری |
تایپ کنید | رشته |
عنصر <IncludeURL>
یک فایل کتابخانه جاوا اسکریپت را مشخص می کند که به عنوان وابستگی به فایل جاوا اسکریپت اصلی مشخص شده با عنصر <ResourceURL>
یا <Source>
بارگذاری شود. اسکریپت ها به ترتیبی که در خط مشی فهرست شده اند ارزیابی می شوند. کد شما می تواند از اشیاء، روش ها و ویژگی های مدل شی جاوا اسکریپت استفاده کند.
بیش از یک منبع وابستگی جاوا اسکریپت را با عناصر <IncludeURL>
اضافه کنید.
<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>
پیش فرض: | هیچ کدام |
حضور: | اختیاری |
نوع: | رشته |
مثال
به مثال پایه در بخش نمونه ها مراجعه کنید.
عنصر <Property>
خصوصیتی را مشخص می کند که می توانید از کد جاوا اسکریپت در زمان اجرا به آن دسترسی داشته باشید.
<Properties> <Property name="propName">propertyValue</Property> </Properties>
پیش فرض: | هیچ کدام |
حضور: | اختیاری |
نوع: | رشته |
صفات
صفت | توضیحات | پیش فرض | حضور |
---|---|---|---|
نام | نام ملک را مشخص می کند. | N/A | مورد نیاز. |
مثال
نمونه را در بخش نمونه ها ببینید.
عنصر <ResourceURL>
فایل اصلی جاوا اسکریپت را که در جریان API اجرا می شود را مشخص می کند. میتوانید این فایل را در محدوده پروکسی API (در زیر /apiproxy/resources/jsc
در بسته پروکسی API یا در بخش اسکریپتها در پنجره ناوبر ویرایشگر پراکسی API)، یا در محدوده سازمان یا محیط برای استفاده مجدد در چندین پراکسی API ذخیره کنید. همانطور که در فایل های منابع توضیح داده شده است. کد شما می تواند از اشیاء، روش ها و ویژگی های مدل شی جاوا اسکریپت استفاده کند.
<ResourceURL>jsc://my-javascript.js</ResourceURL>
پیش فرض: | هیچ کدام |
حضور: | <ResourceURL> یا <Source> مورد نیاز است. اگر <ResourceURL> و <Source> هر دو موجود باشند <ResourceURL> نادیده گرفته می شود. |
نوع: | رشته |
مثال
به مثال پایه در بخش نمونه ها مراجعه کنید.
عنصر <منبع>
به شما امکان می دهد جاوا اسکریپت را مستقیماً در پیکربندی XML خط مشی وارد کنید. کد جاوا اسکریپت درج شده زمانی اجرا می شود که خط مشی در جریان API اجرا شود.
پیش فرض: | هیچ کدام |
حضور: | <ResourceURL> یا <Source> مورد نیاز است. اگر <ResourceURL> و <Source> هر دو موجود باشند <ResourceURL> نادیده گرفته می شود. |
نوع: | رشته |
مثال
<Javascript name='JS-ParseJsonHeaderFullString' timeLimit='200' > <Properties> <Property name='inboundHeaderName'>specialheader</Property> <Property name='outboundVariableName'>json_stringified</Property> </Properties> <Source> var varname = 'request.header.' + properties.inboundHeaderName + '.values.string'; var h = context.getVariable(varname); if (h) { h = JSON.parse(h); h.augmented = (new Date()).valueOf(); var v = JSON.stringify(h, null, 2) + '\n'; // further indent var r = new RegExp('^(\S*)','mg'); v= v.replace(r,' $1'); context.setVariable(properties.outboundVariableName, v); } </Source> </Javascript>
عنصر <SSLIinfo>
خصوصیات مورد استفاده برای پیکربندی TLS برای تمام نمونه های سرویس گیرنده HTTP ایجاد شده توسط خط مشی جاوا اسکریپت را مشخص می کند.
<SSLInfo> <Enabled>trueFalse</Enabled> <ClientAuthEnabled>trueFalse</ClientAuthEnabled> <KeyStore>ref://keystoreRef</KeyStore> <KeyAlias>keyAlias</KeyAlias> <TrustStore>ref://truststoreRef</TrustStore> </SSLInfo>
پیش فرض: | هیچ کدام |
حضور: | اختیاری |
نوع: | رشته |
فرآیند پیکربندی TLS برای یک کلاینت HTTP همان فرآیندی است که برای پیکربندی TLS برای TargetEndpoint/TargetServer استفاده میکنید. برای اطلاعات بیشتر به پیکربندی TLS از Edge به Backend مراجعه کنید.
نکات استفاده
خط مشی جاوا اسکریپت حاوی هیچ کد واقعی نیست. در عوض، یک خطمشی جاوا اسکریپت به یک «منبع» جاوا اسکریپت ارجاع میدهد و مرحله را در جریان API که جاوا اسکریپت اجرا میکند، تعریف میکند. میتوانید اسکریپت خود را از طریق ویرایشگر پروکسی مدیریت رابط کاربری آپلود کنید، یا میتوانید آن را در فهرست /resources/jsc
در پراکسیهای API که به صورت محلی توسعه میدهید قرار دهید.
اشکال زدایی کد خط مشی جاوا اسکریپت
از تابع print() برای خروجی اطلاعات اشکال زدایی به پانل خروجی تراکنش در ابزار Trace استفاده کنید. برای جزئیات و مثالها، عبارات Debug with JavaScript print() را ببینید.
برای مشاهده بیانیه های چاپی در Trace:
- ابزار Trace را باز کنید و یک جلسه ردیابی برای پروکسی که حاوی خط مشی جاوا اسکریپت شما است را شروع کنید.
- با پروکسی تماس بگیرید
- در ابزار Trace، روی Output from all Transactions کلیک کنید تا پانل خروجی باز شود.
- بیانیه های چاپی شما در این پانل ظاهر می شود.
می توانید از تابع print() برای خروجی اطلاعات اشکال زدایی به ابزار Trace استفاده کنید. این تابع مستقیماً از طریق مدل شی جاوا اسکریپت در دسترس است. برای جزئیات، به " Debug JavaScript with print() " مراجعه کنید.
متغیرهای جریان
این سیاست به طور پیش فرض هیچ متغیری را پر نمی کند. با این حال، می توانید متغیرهای جریان را در کد جاوا اسکریپت خود با فراخوانی متدها بر روی شی متن تنظیم کنید (و دریافت کنید). یک الگوی معمولی به این صورت است:
context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"))
شی متن بخشی از مدل شی جاوا اسکریپت Apigee Edge است.
مرجع خطا
این بخش کدهای خطا و پیامهای خطایی را که برگردانده میشوند و متغیرهای خطا را که توسط Edge تنظیم میشوند، هنگامی که این خطمشی خطا را راهاندازی میکند، توضیح میدهد. این اطلاعات برای دانستن اینکه آیا در حال توسعه قوانین خطا برای رسیدگی به خطاها هستید، مهم است. برای کسب اطلاعات بیشتر، آنچه را که باید در مورد خطاهای خط مشی و مدیریت خطاها بدانید را ببینید.
خطاهای زمان اجرا
این خطاها ممکن است هنگام اجرای سیاست رخ دهند.
کد خطا | وضعیت HTTP | علت | رفع کنید |
---|---|---|---|
steps.javascript.ScriptExecutionFailed | 500 | خط مشی جاوا اسکریپت می تواند انواع مختلفی از خطاهای ScriptExecutionFailed را ایجاد کند. انواع خطاهای رایج عبارتند از RangeError ، ReferenceError ، SyntaxError ، TypeError و URIError . | build |
steps.javascript.ScriptExecutionFailedLineNumber | 500 | خطایی در کد جاوا اسکریپت رخ داد. برای جزئیات بیشتر به رشته خطا مراجعه کنید. | N/A |
steps.javascript.ScriptSecurityError | 500 | هنگام اجرای جاوا اسکریپت یک خطای امنیتی روی داد. برای جزئیات بیشتر به رشته خطا مراجعه کنید. | N/A |
خطاهای استقرار
این خطاها ممکن است زمانی رخ دهند که یک پروکسی حاوی این خط مشی را مستقر می کنید.
نام خطا | علت | رفع کنید |
---|---|---|
InvalidResourceUrlFormat | اگر قالب URL منبع مشخص شده در <ResourceURL> یا عنصر <IncludeURL> خط مشی جاوا اسکریپت نامعتبر باشد، در این صورت استقرار پروکسی API با شکست مواجه می شود. | build |
InvalidResourceUrlReference | اگر عناصر <ResourceURL> یا <IncludeURL> به یک فایل جاوا اسکریپت اشاره می کنند که وجود ندارد، در این صورت استقرار پروکسی API با شکست مواجه می شود. فایل منبع ارجاع شده باید در سطح پروکسی API، محیط یا سطح سازمان باشد. | build |
WrongResourceType | اگر عناصر <ResourceURL> یا <IncludeURL> خط مشی جاوا اسکریپت به هر نوع منبعی غیر از jsc (فایل جاوا اسکریپت) اشاره داشته باشند، این خطا در حین استقرار رخ می دهد. | build |
NoResourceURLOrSource | اگر عنصر <ResourceURL> اعلان نشده باشد یا URL منبع در این عنصر تعریف نشده باشد، استقرار خط مشی جاوا اسکریپت می تواند با این خطا شکست بخورد. عنصر <ResourceURL> یک عنصر اجباری است. یا، عنصر <IncludeURL> اعلام شده است اما URL منبع در این عنصر تعریف نشده است. عنصر <IncludeURL> اختیاری است، اما اگر اعلام شود، URL منبع باید در عنصر <IncludeURL> مشخص شود. | build |
متغیرهای خطا
این متغیرها زمانی تنظیم می شوند که این خط مشی خطایی را در زمان اجرا ایجاد کند. برای اطلاعات بیشتر، به آنچه باید در مورد خطاهای خط مشی بدانید مراجعه کنید.
متغیرها | کجا | مثال |
---|---|---|
fault.name=" fault_name " | fault_name نام خطا است، همانطور که در جدول خطاهای Runtime در بالا ذکر شده است. نام خطا آخرین قسمت کد خطا است. | fault.name Matches "ScriptExecutionFailed" |
javascript. policy_name .failed | policy_name نام سیاستی است که توسط کاربر مشخص شده است که خطا را ایجاد کرده است. | javascript.JavaScript-1.failed = true |
نمونه پاسخ خطا
{ "fault": { "faultstring": "Execution of SetResponse failed with error: Javascript runtime error: "ReferenceError: "status" is not defined. (setresponse.js:6)\"", "detail": { "errorcode": "steps.javascript.ScriptExecutionFailed" } } }
مثال قانون خطا
<FaultRule name="JavaScript Policy Faults"> <Step> <Name>AM-CustomErrorResponse</Name> <Condition>(fault.name Matches "ScriptExecutionFailed") </Condition> </Step> <Condition>(javascript.JavaScript-1.failed = true) </Condition> </FaultRule>
طرحواره
هر نوع خط مشی توسط یک طرح XML ( .xsd
) تعریف می شود. برای مرجع، طرحهای خطمشی در GitHub در دسترس هستند.
موضوعات مرتبط
- مدل شی جاوا اسکریپت
- برای دستورالعملها، نمونههای خطمشی و نمونههای جاوا اسکریپت، برنامهنویسی پراکسیهای API با جاوا اسکریپت را ببینید.
مقالات انجمن Apigee
می توانید این مقالات مرتبط را در انجمن Apigee بیابید: