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

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

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

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

تجربة السمات والبيانات

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

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

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

أو يمكنك تنفيذ الأمر التالي في الدليل /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 وإنشاء رسائل استجابة مخصّصة.