برمجة الخوادم الوكيلة لواجهة برمجة التطبيقات باستخدام JavaScript

أنت الآن بصدد الاطّلاع على مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. info

في هذا الموضوع، ستتعرّف على كيفية استخدام JavaScript لإضافة عناوين HTTP بشكل ديناميكي إلى رسالة ردّ ، وكيفية تحليل استجابة JSON وعرض مجموعة فرعية من خصائصها على التطبيق الذي أرسل الطلب.

تنزيل عيّنة الرمز البرمجي وتجربتها

لمحة عن مثال كتاب الطبخ هذا

يوضّح مثال كتاب الطبخ هذا نمط خادم وكيل لواجهة برمجة التطبيقات تنفّذ فيه سلوك واجهة برمجة التطبيقات في JavaScript. تم تصميم أمثلة JavaScript لتوضيح كيفية استخدام المتغيّرات البسيطة ومحتوى الرسالة. توضّح لك إحدى العيّنات كيفية الحصول على المتغيّرات وضبطها. يوضّح لك المثال الثاني كيفية تحليل JSON وإنشاء رسالة من النتيجة.

تتضمّن عيّنة الخادم الوكيل لواجهة برمجة التطبيقات عيّنتَين من JavaScript:

• setHeaders.js: يحصل هذا النص البرمجي JavaScript على قيم بعض المتغيّرات التي يتم ضبطها عند استدعاء خادم وكيل لواجهة برمجة التطبيقات. يضيف النص البرمجي JavaScript هذه المتغيّرات إلى رسالة الردّ حتى تتمكّن من الاطّلاع على قيمها لكل طلب ترسله.
• minimize.js: يوضّح لك هذا النص البرمجي JavaScript كيفية استخدام محتوى الرسالة. تستند فكرة هذه العيّنة إلى أنّ الخدمة غالبًا ما تعرض بيانات أكثر من اللازم. لذا، يحلّل النص البرمجي 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);

يمكنك الوصول إلى متغيّرات التدفق في JavaScript من خلال عنصر السياق. هذا العنصر هو جزء من نموذج كائنات JavaScript في Edge. لمعرفة تفاصيل نموذج الكائنات، يُرجى الاطّلاع على نموذج كائنات JavaScript.

قبل البدء

قبل استكشاف مثال كتاب الطبخ هذا، عليك أيضًا التعرّف على هذه المفاهيم الأساسية:

• ما هي السياسات وكيفية إرفاقها بالخوادم الوكيلة. للحصول على مقدّمة جيدة عن السياسات، يُرجى الاطّلاع على مقالة ما هي السياسة؟.
• بنية تدفق الخادم الوكيل، كما هو موضّح في ضبط التدفقات. تتيح لك التدفقات تحديد التسلسل الذي يتم فيه تنفيذ السياسات من خلال خادم وكيل لواجهة برمجة التطبيقات. في هذا المثال، يتم إنشاء عدة سياسات وإضافتها إلى تدفق خادم وكيل لواجهة برمجة التطبيقات.
• كيفية تنظيم مشروع خادم وكيل لواجهة برمجة التطبيقات على نظام الملفات، كما هو موضّح في مرجع إعدادات الخادم الوكيل لواجهة برمجة التطبيقات.
• معرفة عملية بـ XML وJSON وJavaScript. في هذا المثال، يمكنك إنشاء الخادم الوكيل لواجهة برمجة التطبيقات وسياساته باستخدام ملفات XML الموجودة على نظام الملفات.

إذا نزّلت عيّنة الرمز البرمجي، يمكنك العثور على جميع الملفات التي تمت مناقشتها في هذا الموضوع في مجلد عيّنة javascript-cookbook. توضّح الأقسام التالية عيّنة الرمز البرمجي بالتفصيل.

فهم تدفق الخادم الوكيل

لتنفيذ JavaScript في خادم وكيل لواجهة برمجة التطبيقات، عليك إرفاقه بتدفق باستخدام عملية إرفاق سياسة تُعرف باسم "خطوة". تحتوي سياسة من النوع Javascript (يُرجى ملاحظة الأحرف الكبيرة) ببساطة على مرجع لاسم ملف JavaScript. يمكنك توجيه السياسة إلى ملف JavaScript باستخدام العنصر ResourceURL.

على سبيل المثال، تشير السياسة التالية إلى ملف JavaScript باسم setHeader.js.

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

يمكنك إرفاق هذه السياسة بتدفق خادم وكيل لواجهة برمجة التطبيقات كما تفعل مع أي نوع سياسة آخر. من خلال إرفاق السياسة بتدفق الخادم الوكيل لواجهة برمجة التطبيقات، يمكنك تحديد مكان تنفيذ JavaScript. يتيح لك ذلك تنفيذ JavaScript الذي يتفاعل مع رسائل الطلب أو رسالة الردّ أثناء 'تدفق' هذه الرسائل من خلال الخادم الوكيل لواجهة برمجة التطبيقات. في هذا المثال، يتم تنفيذ كلا النصين البرمجيين JavaScript في تدفق الردّ، لأنّ السياسات تنفّذ إجراءَين: ضبط عناوين HTTP في رسالة الردّ و"تصغير" رسالة الردّ التي يعرضها Apigee Edge على التطبيق الذي أرسل الطلب.

إذا فتحت إعدادات التدفق هذه في واجهة الإدارة، ستظهر لك إعدادات التدفق أدناه.

اختر نقاط نهاية الخادم الوكيل > تلقائي > PostFlow في لوحة التنقّل .

يظهر أدناه إعداد XML المقابل لنقطة نهاية الخادم الوكيل المسماة "تلقائي" .

<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>. تستدعي كل خطوة إحدى السياسات التي تنشئها خلال بقية هذا الموضوع. ترفق هذه السياسات نصًا برمجيًا JavaScript بتدفق الخادم الوكيل لواجهة برمجة التطبيقات، ويحدد مكان الـ سياسة المرفقات وقت تنفيذ JavaScript.
• <Response> - يتضمّن العنصر <Response> أيضًا <Steps>. تستدعي هذه الخطوات أيضًا سياسات مسؤولة عن معالجة الردّ النهائي من الهدف (وهو في هذا المثال هدف خدمة المحاكاة في Apigee، يُرجى ملاحظة إعداد HTTPTargetConnection في تحت /apiproxy/targets/default.xml.)
• <HTTPProxyConnection> - يحدّد المضيف ومسار URI اللذين يحدّدان عنوان الشبكة الذي تستدعيه التطبيقات لاستخدام واجهة برمجة التطبيقات هذه.
  
• <RouteRule> - يحدّد هذا العنصر إعداد TargetEndpoint الذي يستدعيه ProxyEndpoint.

إضافة رمز JavaScript إلى خادم وكيل

يتم تخزين JavaScript (مثل النصوص البرمجية Python وملفات Java JAR وملفات XSLT وما إلى ذلك) كـ موارد. عندما تبدأ العمل باستخدام JavaScript، من الأسهل تخزين ملفات JavaScript في الخادم الوكيل لواجهة برمجة التطبيقات. مع تقدّمك، يجب أن يكون JavaScript عامًا وقابلاً لإعادة الاستخدام قدر الإمكان، ثم يتم تخزينه على مستوى البيئة أو المؤسسة. يمنعك ذلك من تخزين ملفات JavaScript نفسها في خوادم وكيلة متعددة لواجهة برمجة التطبيقات، ما قد يصبح غير قابل للإدارة بسرعة.

للتعرّف على كيفية تخزين الموارد على مستوى المؤسسة والبيئة، يُرجى الاطّلاع على ملفات الموارد.

للتجربة:

للحصول على تعليمات حول نشر الخادم الوكيل واستدعائه، يُرجى الاطّلاع على ملف README لكتاب الطبخ JavaScript.

استيراد الخادم الوكيل لواجهة برمجة التطبيقات ونشره

بعد إجراء التغييرات، يمكنك حفظ الخادم الوكيل لواجهة برمجة التطبيقات في أداة إنشاء الخادم الوكيل لواجهة برمجة التطبيقات في واجهة الإدارة.

أو يمكنك تنفيذ الأمر التالي في الدليل /api-platform-samples/doc-samples/javascript-cookbook.

$ sh deploy.sh

اختبار JavaScript

نفِّذ الأمر التالي في الدليل /api-platform-samples/doc-samples/javascript-cookbook.

$ sh invoke.sh

يتم استخدام علامة curl‏ -v في النص البرمجي للواجهة لعرض عناوين HTTP في رسالة الردّ التي تم تعديلها بواسطة JavaScript.

يمكنك إرسال طلب مباشرةً على النحو التالي:

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

إذا تم تنفيذ JavaScript بشكل صحيح، سيظهر لك ردّ على النحو التالي:

< 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"}

يمكنك الآن تعديل JavaScript لتجربة عناصر جديدة، وإعادة نشر الخادم الوكيل لواجهة برمجة التطبيقات، والتحقق من الـ نتائج من خلال إرسال الطلب نفسه. احرص دائمًا على نشر الخادم الوكيل لواجهة برمجة التطبيقات الذي يحتوي على JavaScript لتطبيق التغييرات.

أخطاء النص البرمجي

ستظهر لك حتمًا أخطاء عند كتابة JavaScript. يظهر أدناه تنسيق أخطاء JavaScript التي سيصدرها خادم وكيل لواجهة برمجة التطبيقات.

{  
   "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"
      }
   }
}

حالات استخدام JavaScript

في Apigee Edge، عادةً ما يكون هناك أكثر من طريقة لتنفيذ وظائف معيّنة. استخدِم السياسات الجاهزة قدر الإمكان، وتجنَّب إغراء كتابة جميع منطق الخادم الوكيل لواجهة برمجة التطبيقات في JavaScript. على الرغم من أنّ Apigee Edge يستفيد من JavaScript المجمّع لتحسين الأداء، من غير المرجّح أن يكون أداء JavaScript جيدًا مثل أداء السياسات. قد يكون من الصعب صيانة JavaScript وتحديد الأخطاء فيه. استخدِم JavaScript للوظائف الفريدة التي تلبي متطلباتك.

إذا كان الأداء يمثّل مشكلة بالنسبة إلى الوظائف المخصّصة، استخدِم Java قدر الإمكان.

ملخّص

في موضوع كتاب الطبخ هذا، تعرّفت على كيفية تضمين JavaScript في إعدادات خادم وكيل لواجهة برمجة التطبيقات لتنفيذ سلوك مخصّص. يوضّح السلوك المخصّص الذي تنفّذه العيّنات كيفية الحصول على المتغيّرات وضبطها، وكيفية تحليل JSON وإنشاء رسائل ردّ مخصّصة.