برنامه نویسی پراکسی های API با جاوا اسکریپت

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

در این مبحث، یاد خواهید گرفت که چگونه از جاوا اسکریپت برای اضافه کردن پویای هدرهای HTTP به یک پیام پاسخ استفاده کنید و چگونه یک پاسخ JSON را تجزیه کرده و زیرمجموعه‌ای از ویژگی‌های آن را به برنامه درخواست‌کننده برگردانید.

کد نمونه را دانلود و امتحان کنید

درباره این نمونه کتاب آشپزی

این مثال کتاب آشپزی، یک الگوی پراکسی API را نشان می‌دهد که در آن شما رفتار API را در جاوا اسکریپت پیاده‌سازی می‌کنید. مثال‌های جاوا اسکریپت به گونه‌ای طراحی شده‌اند که نحوه کار با متغیرهای ساده و محتوای پیام را به شما نشان دهند. یک نمونه به شما نحوه دریافت و تنظیم متغیرها را نشان می‌دهد. مثال دوم به شما نشان می‌دهد که چگونه JSON را تجزیه کرده و از نتیجه آن یک پیام بسازید.

دو نمونه جاوا اسکریپت در پروکسی API وجود دارد:

• setHeaders.js : این فایل جاوااسکریپت مقادیر چند متغیر را که هنگام فراخوانی یک پروکسی API تنظیم می‌شوند، دریافت می‌کند. جاوااسکریپت این متغیرها را به پیام پاسخ اضافه می‌کند تا بتوانید مقادیر آنها را برای هر درخواستی که ارسال می‌کنید، مشاهده کنید.
• minimize.js : این جاوااسکریپت به شما نشان می‌دهد که چگونه با محتوای پیام کار کنید. ایده پشت این نمونه این است که یک سرویس اغلب داده‌های بیشتری از آنچه لازم است را برمی‌گرداند. بنابراین، جاوااسکریپت پیام پاسخ را تجزیه می‌کند، چند ویژگی جالب را استخراج می‌کند و سپس از آنها برای ساخت محتوای پیام پاسخ استفاده می‌کند.

کد مربوط به setHeader.js :

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));
context.setVariable("response.header.X-Apigee-ApiProxyName", context.getVariable("apiproxy.name"));
context.setVariable("response.header.X-Apigee-ProxyName", context.getVariable("proxy.name"));
context.setVariable("response.header.X-Apigee-ProxyBasePath", context.getVariable("proxy.basepath"));
context.setVariable("response.header.X-Apigee-ProxyPathSuffix", context.getVariable("proxy.pathsuffix"));
context.setVariable("response.header.X-Apigee-ProxyUrl", context.getVariable("proxy.url"));

کد مربوط به minimize.js :

// Parse the respose from the target.
var res = JSON.parse(context.proxyResponse.content);

// Pull out only the information we want to see in the response.
var minimizedResponse = { city: res.root.city,
                          state: res.root.state };
          
// Set the response variable. 
context.proxyResponse.content = JSON.stringify(minimizedResponse);

شما می‌توانید از طریق شیء context به متغیرهای جریان در جاوااسکریپت دسترسی داشته باشید. این شیء بخشی از مدل شیء جاوااسکریپت Edge است. برای جزئیات بیشتر در مورد مدل شیء، به مدل شیء جاوااسکریپت مراجعه کنید.

قبل از اینکه شروع کنی

قبل از اینکه این مثال کتاب آشپزی را بررسی کنید، باید با این مفاهیم اساسی نیز آشنا باشید:

• سیاست‌ها چیستند و چگونه می‌توان آنها را به پروکسی‌ها متصل کرد. برای آشنایی بیشتر با سیاست‌ها، به «سیاست چیست؟» مراجعه کنید.
• ساختار یک جریان پروکسی، همانطور که در پیکربندی جریان‌ها توضیح داده شده است. جریان‌ها به شما امکان می‌دهند توالی اجرای سیاست‌ها توسط یک پروکسی API را مشخص کنید. در این مثال، چندین سیاست ایجاد شده و به یک جریان پروکسی API اضافه می‌شوند.
• نحوه سازماندهی یک پروژه پروکسی API در سیستم فایل شما، همانطور که در مرجع پیکربندی پروکسی API توضیح داده شده است.
• دانش کاربردی XML، JSON و جاوا اسکریپت. در این مثال، شما پروکسی API و سیاست‌های آن را با فایل‌های XML که در سیستم فایل قرار دارند، می‌سازید.

اگر کد نمونه را دانلود کرده‌اید، می‌توانید تمام فایل‌های مورد بحث در این مبحث را در پوشه نمونه javascript-cookbook پیدا کنید. بخش‌های بعدی به تفصیل در مورد کد نمونه بحث خواهند کرد.

درک جریان پروکسی

برای اینکه جاوا اسکریپت در یک پروکسی API اجرا شود، باید آن را با استفاده از یک پیوست سیاست به نام 'Step' به یک جریان متصل کنید. یک سیاست از نوع Javascript (به حروف بزرگ توجه کنید) به سادگی شامل ارجاعی به نام یک فایل جاوا اسکریپت است. شما با استفاده از عنصر ResourceURL، سیاست را به یک فایل جاوا اسکریپت ارجاع می‌دهید.

برای مثال، سیاست زیر به فایل جاوا اسکریپتی به نام setHeader.js اشاره می‌کند.

<Javascript name='setHeaders' timeLimit='200'>
    <ResourceURL>setHeaders.js</ResourceURL>
</Javascript>

شما می‌توانید این سیاست را مانند هر نوع سیاست دیگری به یک جریان پروکسی API متصل کنید. با اتصال سیاست به جریان پروکسی API، مشخص می‌کنید که جاوا اسکریپت کجا باید اجرا شود. این به شما امکان می‌دهد جاوا اسکریپتی را اجرا کنید که با پیام‌های درخواست یا پیام پاسخ در تعامل است، زیرا این پیام‌ها از طریق پروکسی API «جریان» می‌یابند. در این مثال، هر دو جاوا اسکریپت در جریان پاسخ اجرا می‌شوند، زیرا سیاست‌ها دو کار انجام می‌دهند: تنظیم هدرهای HTTP روی پیام پاسخ و «به حداقل رساندن» پیام پاسخی که Apigee Edge به برنامه درخواست‌کننده برمی‌گرداند.

اگر این پیکربندی جریان را در رابط کاربری مدیریت باز کنید، پیکربندی جریان را در زیر مشاهده خواهید کرد.

در پنل ناوبر، Proxy Endpoints > default > PostFlow را انتخاب کنید.

پیکربندی XML مربوطه برای ProxyEndpoint با نام 'default' در زیر نشان داده شده است.

<ProxyEndpoint name="default">
  <PostFlow>
    <Response>
      <!-- Steps reference policies under /apiproxy/policies -->
      <!-- First, set a few HTTP headers with variables for this transaction. -->
      <Step><Name>setHeaders</Name></Step>
      <!-- Next, transform the response from XML to JSON for easier parsing with JavaScript -->
      <Step><Name>transform</Name></Step>
      <!-- Finally, use JavaScript to create minimized response with just city and state. -->
      <Step><Name>minimize</Name></Step>
    </Response>
  </PostFlow>
  <HTTPProxyConnection>
        <!-- BasePath defines the network address for this API proxy. See the script 'invoke.sh' to see how the complete URL for this API proxy is constructed.-->
    <BasePath>/javascript-cookbook</BasePath>
     <!-- Set VirtualHost to 'secure' to have this API proxy listen on HTTPS. -->
    <VirtualHost>default</VirtualHost>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

در اینجا خلاصه‌ای از عناصر این جریان آورده شده است.

• <Request> - عنصر <Request> از چندین عنصر <Step> تشکیل شده است. هر مرحله یکی از سیاست‌هایی را که در ادامه این مبحث ایجاد می‌کنید، فراخوانی می‌کند. این سیاست‌ها یک جاوا اسکریپت را به جریان پروکسی API متصل می‌کنند و محل پیوست سیاست، زمان اجرای جاوا اسکریپت را تعیین می‌کند.
• <Response> - عنصر <Response> همچنین شامل <Steps> است. این مراحل همچنین سیاست‌هایی را فراخوانی می‌کنند که مسئول پردازش پاسخ نهایی از هدف هستند (که در این مثال هدف سرویس ساختگی Apigee است - به تنظیم HTTPTargetConnection در زیر /apiproxy/targets/default.xml توجه کنید.)
• <HTTPProxyConnection> - میزبان و مسیر URI را مشخص می‌کند که آدرس شبکه‌ای را که برنامه‌ها برای استفاده از این API فراخوانی می‌کنند، تعریف می‌کنند.
  
• <RouteRule> - این عنصر مشخص می‌کند که کدام پیکربندی TargetEndpoint توسط ProxyEndpoint فراخوانی می‌شود.

افزودن کد جاوا اسکریپت به پروکسی

جاوا اسکریپت (مانند اسکریپت‌های پایتون، فایل‌های JAR جاوا، فایل‌های XSLT و غیره) به عنوان منابع ذخیره می‌شوند. وقتی تازه شروع به کار با جاوا اسکریپت کرده‌اید، ساده‌ترین راه این است که فایل‌های جاوا اسکریپت خود را در پروکسی API ذخیره کنید. با پیشرفت، جاوا اسکریپت باید تا حد امکان عمومی و قابل استفاده مجدد شود و سپس در سطح محیط یا سازمان ذخیره شود. این کار مانع از آن می‌شود که مجبور شوید فایل‌های جاوا اسکریپت یکسان را در چندین پروکسی API ذخیره کنید، که می‌تواند به سرعت غیرقابل مدیریت شود.

برای کسب اطلاعات در مورد ذخیره منابع در سطح سازمان و محیط، به فایل‌های منبع مراجعه کنید.

امتحانش کن.

برای دستورالعمل‌های مربوط به استقرار و فراخوانی پروکسی، به کتاب راهنمای جاوا اسکریپت README مراجعه کنید.

وارد کردن و استقرار پروکسی API

پس از ایجاد تغییرات، می‌توانید پروکسی API را در ابزار سازنده پروکسی API در رابط کاربری مدیریت ذخیره کنید .

یا می‌توانید دستور زیر را در دایرکتوری /api-platform-samples/doc-samples/javascript-cookbook اجرا کنید.

$ sh deploy.sh

تست جاوا اسکریپت

دستور زیر را در دایرکتوری /api-platform-samples/doc-samples/javascript-cookbook اجرا کنید.

$ sh invoke.sh

پرچم curl با -v در اسکریپت پوسته برای مشاهده هدرهای HTTP در پیام پاسخی که توسط جاوا اسکریپت تغییر یافته است، استفاده می‌شود.

شما می‌توانید مستقیماً درخواست خود را به صورت زیر ارسال کنید:

$ curl -v http://{org_name}-test.apigee.net/javascript-cookbook 

اگر جاوا اسکریپت به درستی اجرا شود، پاسخی مانند زیر خواهید دید:

< X-Apigee-Demo-Target: default
< X-Apigee-Demo-ApiProxyName: simple-javascript
< X-Apigee-Demo-ProxyName: default
< X-Apigee-Demo-ProxyBasePath: /javascript-cookbook
< X-Apigee-Demo-ProxyPathSuffix: /xml
< X-Apigee-Demo-ProxyUrl: http://rrt331ea.us-ea.4.apigee.com/javascript-cookbook/xml
 
{"city":"San Jose","state":"CA"}

اکنون می‌توانید جاوا اسکریپت را برای امتحان کردن چیزهای جدید تغییر دهید، پروکسی API را مجدداً مستقر کنید و با ارسال همان درخواست، نتایج را تأیید کنید. همیشه مطمئن شوید که پروکسی API را که حاوی جاوا اسکریپت شماست، مستقر می‌کنید تا تغییرات شما اعمال شوند.

خطاهای اسکریپت

هنگام نوشتن جاوا اسکریپت، ناگزیر با خطاهایی مواجه خواهید شد. قالب خطاهای جاوا اسکریپتی که توسط یک پروکسی API صادر می‌شوند، در زیر نشان داده شده است.

{  
   "fault":{  
      "faultstring":"Execution of rewriteTargetUrl failed with error: Javascript runtime error: \"TypeError: Cannot find function getVariable in object TARGET_REQ_FLOW. (rewriteTargetUrl_js#1). at line 1 \"",
      "detail":{  
         "errorcode":"steps.javascript.ScriptExecutionFailed"
      }
   }
}

چه زمانی از جاوا اسکریپت استفاده کنیم

در Apigee Edge، معمولاً بیش از یک راه برای پیاده‌سازی قابلیت‌های خاص وجود دارد. در صورت امکان از سیاست‌های آماده استفاده کنید و از وسوسه کدنویسی تمام منطق پروکسی API خود در جاوا اسکریپت خودداری کنید. اگرچه Apigee Edge از جاوا اسکریپت کامپایل شده برای بهبود عملکرد استفاده می‌کند، بعید است که جاوا اسکریپت به خوبی Policyها عمل کند. نگهداری و اشکال‌زدایی جاوا اسکریپت ممکن است دشوارتر باشد. جاوا اسکریپت را برای قابلیت‌هایی که منحصر به نیازهای شما هستند، رزرو کنید.

اگر عملکرد برای قابلیت‌های سفارشی مهم است، در صورت امکان از جاوا استفاده کنید.

خلاصه

در این مبحث از کتاب آشپزی، یاد گرفتید که چگونه می‌توان جاوا اسکریپت را در پیکربندی پروکسی API برای پیاده‌سازی رفتار سفارشی گنجاند. رفتار سفارشی پیاده‌سازی شده توسط نمونه‌ها، نحوه دریافت متغیرها و نحوه تجزیه JSON و ساخت پیام‌های پاسخ سفارشی را نشان می‌دهد.