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

أنت تعرض مستندات Apigee Edge.
انتقل إلى مستندات Apigee X. معلومات

ستتعرف في هذا الموضوع على كيفية استخدام 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 المسماة "تلقائية" يتم عرضه أدناه.

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

فيما يلي ملخص لعناصر التدفق.

• &lt;Request&gt; - <الطلب> عنصرًا من عدة عناصر &lt;Step&gt; عناصر. تستدعي كل خطوة إحدى السياسات التي تنشئها خلال بقية هذا الموضوع. تُرفِق هذه السياسات ملف JavaScript بتدفق الخادم الوكيل لواجهة برمجة التطبيقات، ومكان مرفق سياسة يحدد وقت تنفيذ JavaScript.
• &lt;Response&gt; - <Response>. تضم العنصر أيضًا <الخطوات>. وتستدعي هذه الخطوات أيضًا السياسات المسؤولة عن معالجة النتيجة النهائية استجابة من الهدف (وهو في هذا المثال هدف محاكاة خدمة Apigee - يُرجى ملاحظة إعداد HTTPTargetConnection ضمن /apiproxy/targets/default.xml).
• &lt;HTTPProxyConnection&gt; - لتحديد المضيف ومسار معرّف الموارد المنتظم (URI) الذي تحديد عنوان الشبكة الذي تطلبه التطبيقات لاستهلاك واجهة برمجة التطبيقات هذه.
  
• &lt;RouteRule&gt;: يحدد هذا العنصر أي عنصر TargetEndpoint يتم استدعاء الإعداد من خلال ProxyEndpoint.

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

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

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

جرّبه الآن

للحصول على إرشادات حول نشر الخادم الوكيل والاتصال به، يمكنك الاطلاع على دليل طهي JavaScript.

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

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

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

$ sh deploy.sh

اختبار JavaScript

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

$ sh invoke.sh

يتم استخدام علامة curl -v في نص Shell لعرض عناوين 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 وإنشاء استجابة مخصّصة الرسائل.