برنامه نویسی پراکسی های 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);

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

قبل از شروع

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

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

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

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

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

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

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

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

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

Proxy Endpoints > default > PostFlow را در قسمت Navigator انتخاب کنید.

پیکربندی 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 توجه کنید.)
• <HTTPPproxyConnection> - مسیر میزبان و 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 از جاوا اسکریپت برای بهبود عملکرد استفاده می کند، بعید است که جاوا اسکریپت به خوبی سیاست ها عمل کند. نگهداری و اشکال زدایی جاوا اسکریپت ممکن است دشوارتر باشد. جاوا اسکریپت را برای عملکردی که منحصر به نیاز شماست رزرو کنید.

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

خلاصه

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