فهم توافق Edge مع وحدات Node.js

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

ما هو إصدار Node.js المتوافق مع Apigee Edge؟

يتوافق Edge حاليًا مع الإصدار 0.10.32 من Node.js.

ما هي وحدات Node.js العادية المتوافقة مع Edge؟

استخدِم الجدول التالي لتحديد وحدات Node.js العادية المضمّنة في Edge. في بعض الحالات، لا تتوفّر الوحدات المضمّنة إلا بشكل جزئي. هذه الوحدات مدمجة في Node.js.

الوحدة الحالة ملاحظات
assert متاح
buffer متاح
child_process محدود سيتم عرض استثناء في حال محاولة إنشاء عملية فرعية. ومع ذلك، يمكن استخدام "fork" لإنشاء نصوص برمجية فرعية.
cluster غير مفعّل تعرض الطريقة cluster.isMaster القيمة "صحيح" دائمًا، ولا يتم تنفيذ الطرق الأخرى. يتم نشر نسخة واحدة من كل نص برمجي Node.js إلى كل معالج رسائل Edge.
crypto متاح
dns متاح
domain متاح
dgram محدود لن تتمكّن تطبيقات Node.js في بيئة Apigee من الوصول إلى الخدمات على الإنترنت عبر بروتوكول UDP بسبب بنية الشبكة.
events متاح
fs محدود يقتصر الوصول إلى نظام الملفات على الدليل الذي تم تشغيل البرنامج النصي منه، أي الدليل /resources/node. يمكن أن تقرأ نصوص Node.js البرمجية الملفات وتكتبها داخل هذا الدليل، مثلاً كمساحة مؤقتة، ولكن لا توجد ضمانات بشأن مدة بقاء الملفات.
http متاح يتم تحديد المضيف الظاهري والمسار للطلبات الواردة في خادم وكيل API، وليس من خلال وحدة HTTP. لمزيد من المعلومات، يُرجى الاطّلاع على التعرّف على إمكانية استخدام وحدتَي http وhttps.
https متاح يتصرف خادم "https" بشكل مطابق لخادم "http". يمكنك الاطّلاع على مقالة "التعرّف على إمكانية استخدام وحدتَي http وhttps" للحصول على مزيد من المعلومات.
module متاح
net محدود ستؤدي محاولات الاستماع إلى اتصالات بروتوكول التحكم في الإرسال الواردة إلى إنشاء استثناء.
path متاح
module متاح
process التوافق الجزئي لا تتوفّر وظائف لمعالجة رقم تعريف المستخدم والانتساب في المجموعة ودليل العمل.
punycode متاح
querystring متاح
readline غير مفعّل لا يوجد إدخال موحّد للنصوص البرمجية التي يتم تشغيلها على Apigee Edge.
repl غير مفعّل لا يوجد إدخال موحّد للنصوص البرمجية التي يتم تشغيلها على Apigee Edge.
module متاحة
STDIO متاح

يتم توجيه الإخراج والخطأ العاديين إلى ملف سجلّ ضمن البنية الأساسية لبرنامج Apigee Edge. يمكنك عرض هذه السجلات من خلال النقر على الزر سجلات Node.js في واجهة مستخدم إدارة Apigee Edge لخادم وكيل واجهة برمجة التطبيقات.

لا يوجد إدخال موحّد للنصوص البرمجية التي يتم تشغيلها على Apigee Edge. ومع ذلك، يمكنك تمرير وسيطات باستخدام عنصر ScriptTarget الخاص بـ TargetEndpoint. راجِع الإعداد المتقدّم لـ ScriptTarget للحصول على مزيد من المعلومات.
stream متاح
string_decoder متاح
timers متاحة
tls متاح تعمل مَعلمات بروتوكول أمان طبقة النقل (TLS) بالطريقة نفسها التي تعمل بها في Node.js العادي. راجِع استخدام وحدة Node.js لبروتوكول أمان طبقة النقل (SSL) على Apigee Edge للحصول على التفاصيل.
tty غير مفعّل لا يوجد إدخال موحّد للنصوص البرمجية التي يتم تشغيلها على Apigee Edge.
url متاح
util متاح
vm متاح
zlib متاح

وحدات إضافية متوافقة

يسرد هذا القسم وحدات إضافية غير متوافقة مع Node.js العادي، ولكنها متوافقة مع Trireme وTrireme التي تعمل على Apigee Edge. ‫Trireme هي حاوية Node.js مفتوحة المصدر تعمل على Apigee Edge. وهي مصمَّمة لتشغيل نصوص Node.js البرمجية داخل آلة Java الافتراضية (JVM). تتوفّر كل هذه الوحدات على NPM.

الوحدة الوصف
apigee-access تتيح تطبيقات Node.js التي تعمل على منصة Apigee Edge طريقة للوصول إلى وظائف خاصة بـ Apigee. يمكنك استخدام هذه الوحدة النمطية لإجراء ما يلي: الوصول إلى متغيرات التدفق وتعديلها، واسترداد البيانات من وحدة التخزين الآمنة، واستخدام خدمات ذاكرة التخزين المؤقت على Edge والحصة وبروتوكول OAuth. راجِع أيضًا استخدام وحدة apigee-access.
trireme-support تتيح لتطبيقات Node.js الاستفادة من الميزات الخاصة بـ Trireme. في الوقت الحالي، تتوفّر ميزة واحدة فقط، وهي تحميل وحدات Node.js البرمجية المضمّنة في Java. ملاحظة: loadJars غير متاح في Edge Cloud.
trireme-xslt تعرض هذه السمة تجريدًا لمعالجة XLST. وهي مصمَّمة خصيصًا لمنصة Trireme للسماح بمعالجة XSLT بكفاءة عند تشغيل تطبيقات Node.js على Java.
trireme-jdbc يتيح الوصول إلى JDBC من Node.js. ملاحظة: لا تتوفّر هذه الميزة في "الحوسبة الطرفية". بالنسبة إلى Edge Private Cloud، يمكنك وضع ملفات JDPC JAR في مسار الفئة واستخدام هذه الوحدة.

التوافق مع وحدات Node.js الشائعة الاستخدام

القيود المفروضة على نصوص Node.js البرمجية

يُرجى العِلم أنّ Edge يفرض قيودًا معيّنة على نصوص Node.js البرمجية، مثل ما يلي:

  • لا يمكن لتطبيقات Node.js في بيئة Apigee Edge الوصول إلى الخدمات على الإنترنت عبر بروتوكول UDP بسبب بنية شبكة Edge.
  • يقتصر الوصول إلى نظام الملفات على الدليل الذي تم تشغيل نص Node.js فيه، أي الدليل /resources/node. يمكن لنصوص Node.js البرمجية قراءة الملفات وكتابتها في هذا الدليل، مثلاً كمساحة مؤقتة، ولكن لا توجد ضمانات بشأن مدة بقاء الملفات.
  • تؤدي محاولات الاستماع إلى اتصالات TCP الواردة إلى إنشاء استثناء.
  • لا تتوفّر وظائف لتعديل رقم تعريف المستخدم والانتساب في المجموعة ودليل العمل.
  • بالنسبة إلى الإدخال العادي، يقتصر الأمر على تمرير الوسيطات باستخدام عنصر ScriptTarget في TargetEndpoint. لمزيد من المعلومات، راجِع الإعدادات المتقدّمة لـ ScriptTarget.
  • بالنسبة إلى الإخراج العادي، يقتصر استخدامك على زر "سجلات Node.js" في واجهة مستخدم إدارة Edge للوكيل. يمكنك أيضًا استخدام الأمر "apigeetool getlogs". لمزيد من المعلومات، اطّلِع على نشر تطبيق Node.js مستقل.
  • الوحدات التي تعتمد على الرمز البرمجي الأصلي غير متاحة.
  • لا تتوافق الوحدات التي تعتمد على ميزات EcmaScript 6، مثل Promises وGenerators.
  • لا تتوافق علامات وقت التشغيل Node.js، مثل "harmony-proxies".

ضبط قيود اتصال عناوين IP على Edge for Private Cloud

يمكن أن تحظر Edge for Private Cloud وصول رمز Node.js إلى عناوين IP التي تبدأ بـ "10."، "192.168"، والمضيف المحلي. إذا حاولت الوصول إلى عناوين IP هذه، سيظهر لك خطأ بالشكل التالي:

{ [Error: connect EINVAL] message: 'connect EINVAL', code: 'EINVAL', errno: 'EINVAL', syscall: 'connect' }

يمكنك تعديل هذه القيود من خلال ضبط السمة conf_nodejs_connect.ranges.denied في الملف message-processors.properties لكل معالج رسائل. تكون القيمة التلقائية لهذه السمة كما يلي:

  • Edge 4.17.05 والإصدارات الأقدم: conf_nodejs_connect.ranges.denied=10.0.0.0/8,192.168.0.0/16,127.0.0.1/32
  • Edge 4.17.09 والإصدارات الأحدث: conf_nodejs_connect.ranges.denied= (ما يعني عدم وجود قيود)

لضبط هذه السمة، اتّبِع الخطوات التالية:

  1. افتح ملف message-processor.properties في محرِّر. إذا لم يكن الملف متوفّرًا، أنشئه:
    > vi /<inst_root>/apigee/customer/application/message-processor.properties
  2. اضبط السمة على القيمة المطلوبة. على سبيل المثال، لرفض الوصول إلى localhost فقط:
    conf_nodejs_connect.ranges.denied=127.0.0.1/32
  3. احفظ التغييرات.
  4. تأكَّد من أنّ ملف الخصائص يملكه المستخدم "apigee":
    > chown apigee:apigee /<inst_root>/apigee/customer/application/message-processor.properties
  5. أعِد تشغيل "معالج الرسائل" (Message Processor):
    > /<inst_root>/apigee/apigee-service/bin/apigee-service edge-message-processor restart

فهم التوافق مع وحدتَي http وhttps

يجب أن تستخدم جميع تطبيقات Node.js التي تعمل في Apigee Edge الوحدة http أو https للاستماع إلى الطلبات الواردة. إذا أردت نشر نص برمجي لا يستمع إلى الطلبات الواردة، سيتم تنفيذه والخروج منه ببساطة.

تأخذ طريقة listen في الوحدتين http وhttps في Node.js رقم منفذ كمعلَمة. على سبيل المثال:

svr.listen(process.env.PORT || 9000, function() {
   console.log('The server is running.');
});

وسيطة "المنفذ" هذه مطلوبة في Node.js، ولكنّ Apigee Edge تتجاهل هذه المَعلمة. بدلاً من ذلك، يحدّد خادم وكيل واجهة برمجة التطبيقات الذي يتم فيه تنفيذ نص Node.js البرمجي "المضيف الافتراضي" الذي يستمع إليه، ويستخدم تطبيق Node.js المضيفات الافتراضية نفسها، تمامًا مثل أي خادم وكيل آخر في Apigee Edge.

تحتوي كل بيئة في Apigee على مضيف افتراضي واحد على الأقل. يحدّد المضيف الظاهري إعدادات HTTP الخاصة بالاتصال بمؤسسة Apigee. تتشارك جميع خوادم API الوكيلة في بيئة ما المضيفات الافتراضية نفسها. يتوفّر تلقائيًا مضيفان افتراضيان لكل بيئة: default وsecure. لمزيد من المعلومات، يُرجى الاطّلاع على الحصول على المضيف الافتراضي ودورة حياة تطوير واجهة برمجة التطبيقات.

ينشئ الأمر apigeetool deploynodeapp برنامج تضمين لخادم وكيل Apigee Edge حول تطبيق Node.js. عند نشر تطبيق Node.js، يستمع التطبيق إلى المضيف الافتراضي الظاهري المحدّد للبيئة. سيكون عنوان URL لتطبيق Node.js دائمًا http://{org_name}-{env_name}.apigee.net.

التعامل مع الطلبات الواردة

مثل تطبيقات Apigee Edge الأخرى، إذا تم إعداد تطبيق الخادم الوكيل للاستماع على المضيف الافتراضي secure، سيقبل الطلبات الواردة باستخدام HTTPS.

التعامل مع الطلبات الصادرة

بالإضافة إلى تلقّي حركة البيانات الواردة، يمكن لتطبيقات Node.js داخل Apigee Edge استخدام الوحدتَين http وhttps لإجراء طلبات صادرة مثل أي تطبيق Node.js آخر. تعمل هذه الوحدات النمطية كما هو معتاد داخل Node.js.

التعرّف على إمكانية استخدام وحدة tls

يتوافق Apigee Edge مع وحدة tls في Node.js. يستخدم هذا النموذج OpenSSL لتوفير بروتوكول أمان طبقة النقل (TLS) و/أو بروتوكول طبقة المقابس الآمنة (SSL) لتشفير عمليات نقل البيانات. يمكنك استخدام الوحدة tls لإنشاء اتصالات آمنة بخدمات الخلفية من تطبيقات Node.js التي تعمل على Edge.

لفهم طريقة عمل وحدة tls على Apigee Edge، من المهم معرفة كيفية استخدام virtual hosts على Apigee Edge. تحتوي كل بيئة في Apigee على مضيف افتراضي واحد على الأقل. يحدد المضيف الظاهري إعدادات HTTP للاتصال بمؤسسة Apigee. تتشارك جميع خوادم API الوكيلة في بيئة ما المضيفات الافتراضية نفسها. تتوفّر تلقائيًا مضيفان افتراضيان لكل بيئة: default وsecure. لمزيد من المعلومات حول المضيفين الافتراضيين، راجِع الحصول على مضيف افتراضي ودورة حياة تطوير واجهة برمجة التطبيقات.

لنلقِ نظرة الآن على كيفية تعامل Apigee Edge مع اتصالات بروتوكول أمان طبقة النقل (TLS) (طبقة المقابس الآمنة) للطلبات الواردة والصادرة في تطبيقات Node.js:

التعامل مع الطلبات الواردة

استنادًا إلى كيفية ضبط المضيفات الافتراضية لمؤسستك، يوفّر Edge الخيارات التالية:

  • إذا تم ضبط خادم وكيل لواجهة برمجة التطبيقات للاستماع على المضيف الافتراضي default، سيقبل الطلبات عبر HTTP.
  • إذا تم ضبط خادم وكيل لواجهة برمجة التطبيقات للاستماع على المضيف الظاهري secure، سيقبل الطلبات عبر HTTPS. سيكون عنوان URL ضمن النطاق apigee.net، وسيتم استخدام شهادة طبقة مقابس آمنة بأحرف بدل للنطاق *.apigee.net. وطالما أنّ التطبيقات ترسل طلبات إلى النطاق apigee.net، ستتم المصادقة على شهادة SSL بشكل طبيعي.

التعامل مع الطلبات الصادرة

يمكنك إرسال طلبات صادرة باستخدام الوحدة tls بالطريقة نفسها التي تستخدمها عادةً في Node.js. بشكل أساسي، عليك إضافة مفاتيح وشهادات من جهة العميل (ملفات .pem) إلى الدليل resources/node وتحميلها داخل النص البرمجي. للحصول على معلومات حول استخدام الوحدة tls وطُرقها، يمكنك الاطّلاع على مستندات وحدة Node.js tls.

إعدادات ScriptTarget المتقدّمة

في تعريف <TargetEndpoint>، يأخذ العنصر <ScriptTarget> مَعلمات اختيارية إضافية إلى جانب <ResourceURL>. يمكنك أيضًا تمرير وسيطات سطر الأوامر ومتغيرات البيئة إلى نص برمجي Node.js باستخدام المَعلمتَين <EnvironmentVariables> و<Arguments>: 
<TargetEndpoint name="default">
  <ScriptTarget>
     <ResourceURL>node://hello.js</ResourceURL>
     <EnvironmentVariables>
         <EnvironmentVariable name="NAME">VALUE</EnvironmentVariable> 
     </EnvironmentVariables>
     <Arguments>
         <Argument>ARG</Argument>
     </Arguments>
  </ScriptTarget>
</TargetEndpoint>