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

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

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

بارگیری و امتحان کردن کد نمونه

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

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

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

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

کد 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);

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

قبل‌از شروع

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

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

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

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

برای اینکه JavaScript در یک پراکسی API اجرا شود، باید آن را بااستفاده از یک پیوست خط‌مشی به نام «مرحله» به یک جریان پیوست کنید. خط‌مشی نوع جاوا اسکریپت (به حروف بزرگ توجه کنید) به‌سادگی حاوی ارجاع به نام فایل جاوا اسکریپت است. بااستفاده از عنصر ResourceURL، خط‌مشی را به فایل JavaScript هدایت می‌کنید.

برای مثال، خط‌مشی زیر به فایل JavaScript به‌نام setHeader.js ارجاع می‌دهد.

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

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

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

در قاب پیمایشگر ، نقطه‌های پایان پراکسی > پیش‌فرض > 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 فراخوانی می‌شود.

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

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

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

امتحان کنید

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

درحال وارد کردن و استقرار پراکسی 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 حاوی جاوا اسکریپت خود را مستقر کنید تا تغییراتتان اعمال شود.

خطاهای دستورگان

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

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

خلاصه

در این موضوع دستورالعمل، یاد گرفتید که چگونه می‌توان از JavaScript در پیکربندی کارگزار API برای پیاده‌سازی رفتار سفارشی استفاده کرد. عملکرد سفارشی پیاده‌سازی‌شده توسط نمونه‌ها نشان می‌دهد چگونه متغیرها را دریافت کنیم و چگونه پیام‌های پاسخ سفارشی را تجزیه و بسازیم. JSON