سياسة JavaScript

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

الأدوات المستخدمة

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

لمحة

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

إحدى حالات الاستخدام التي لا ننصح بها لسياسة JavaScript هي التسجيل. تكون سياسة تسجيل الرسائل أنسب بكثير للتسجيل في منصات تسجيل تابعة لجهات خارجية، مثل Splunk وSumo وLoggly، ويمكنك تحسين أداء خادم وكيل واجهة برمجة التطبيقات من خلال تنفيذ سياسة تسجيل الرسائل في PostClientFlow، التي يتم تنفيذها بعد إرسال الردّ إلى العميل.

تتيح لك سياسة JavaScript تحديد ملف مصدر JavaScript لتنفيذه، أو يمكنك تضمين رمز JavaScript مباشرةً في إعدادات السياسة باستخدام العنصر <Source>. في كلتا الحالتين، يتم تنفيذ رمز JavaScript البرمجي عند تنفيذ الخطوة التي تم ربط السياسة بها. بالنسبة إلى خيار ملف المصدر، يتم دائمًا تخزين رمز المصدر في موقع عادي ضمن حزمة الخادم الوكيل: apiproxy/resources/jsc. يمكنك أيضًا تخزين رمز المصدر في ملف موارد على مستوى البيئة أو المؤسسة. للحصول على التعليمات، يُرجى الاطّلاع على ملفات الموارد. يمكنك أيضًا تحميل JavaScript من خلال محرر الخادم الوكيل في واجهة مستخدم Apigee.

يجب أن تتضمّن ملفات مصدر JavaScript دائمًا الامتداد .js.

يمكنك الاطّلاع على البرامج والإصدارات المتوافقة لمعرفة إصدار JavaScript المتوافق حاليًا.

فيديو

شاهِد فيديو قصيرًا للتعرّف على كيفية إنشاء إضافة سياسة مخصّصة باستخدام سياسة JavaScript.

نماذج

curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="target-rewrite">
    <DisplayName>target-rewrite</DisplayName>
    <Properties/>
    <ResourceURL>jsc://js-example.js</ResourceURL>
</Javascript>

مرجع العنصر

يصف مرجع العناصر عناصر وسياسات JavaScript.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript async="false"
        continueOnError="false" enabled="true" timeLimit="200"
        name="JavaScript-1">
    <DisplayName>JavaScript 1</DisplayName>
    <Properties>
        <Property name="propName">propertyValue</Property>
    </Properties>
    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
    </SSLInfo>
    <IncludeURL>jsc://a-javascript-library-file</IncludeURL>
    <ResourceURL>jsc://my-javascript-source-file</ResourceURL>
    <Source>insert_js_code_here</Source>

</Javascript>

سمات <Javascript>

<Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">

السمات التالية خاصة بهذه السياسة.

يصف الجدول التالي السمات المشتركة بين جميع العناصر الرئيسية للسياسة:

&lt;DisplayName&gt; عنصر

استخدِمه مع السمة name لتصنيف السياسة في إدارة خادم وكيل لواجهة المستخدم باسم مختلف بلغة طبيعية.

<DisplayName>Policy Display Name</DisplayName>

العنصر <IncludeURL>

تحدّد هذه السمة ملف مكتبة JavaScript سيتم تحميله كعنصر تابع لملف JavaScript الرئيسي المحدّد باستخدام العنصر <ResourceURL> أو <Source>. سيتم تقييم النصوص البرمجية بالترتيب الذي تم إدراجها به في السياسة. يمكن أن يستخدم الرمز البرمجي الكائنات والطرق والسمات الخاصة بنموذج كائن JavaScript.

تضمين أكثر من مورد واحد يعتمد على JavaScript مع عناصر <IncludeURL> إضافية

<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>

مثال

يمكنك الاطّلاع على المثال الأساسي في قسم الأمثلة.

العنصر <Property>

تحدّد هذه السمة إحدى السمات التي يمكنك الوصول إليها من رمز JavaScript البرمجي في وقت التشغيل.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>

السمات

مثال

يمكنك الاطّلاع على المثال في قسم النماذج.

العنصر <ResourceURL>

تحدّد هذه السمة ملف JavaScript الرئيسي الذي سيتم تنفيذه في مسار واجهة برمجة التطبيقات. يمكنك تخزين هذا الملف في نطاق خادم وكيل لواجهة برمجة التطبيقات (ضمن /apiproxy/resources/jsc في حزمة خادم وكيل لواجهة برمجة التطبيقات أو في قسم "البرامج النصية" في جزء "المستكشف" في محرر خادم وكيل لواجهة برمجة التطبيقات)، أو في نطاقات المؤسسة أو البيئة لإعادة الاستخدام في عدة خوادم وكيلة لواجهة برمجة التطبيقات، كما هو موضح في ملفات الموارد. يمكن أن يستخدم الرمز البرمجي الكائنات والطرق والسمات الخاصة بنموذج كائن JavaScript.

<ResourceURL>jsc://my-javascript.js</ResourceURL>

مثال

يمكنك الاطّلاع على المثال الأساسي في قسم الأمثلة.

العنصر <Source>

تتيح لك إدراج JavaScript مباشرةً في إعدادات XML للسياسة. يتم تنفيذ رمز JavaScript الذي تم إدراجه عندما يتم تنفيذ السياسة في مسار واجهة برمجة التطبيقات.

مثال

<Javascript name='JS-ParseJsonHeaderFullString' timeLimit='200' >
  <Properties>
    <Property name='inboundHeaderName'>specialheader</Property>
    <Property name='outboundVariableName'>json_stringified</Property>
  </Properties>
  <Source>
var varname = 'request.header.' + properties.inboundHeaderName + '.values.string';
var h = context.getVariable(varname);
if (h) {
  h = JSON.parse(h);
  h.augmented = (new Date()).valueOf();
  var v = JSON.stringify(h, null, 2) + '\n';
  // further indent
  var r = new RegExp('^(\S*)','mg');
  v= v.replace(r,'    $1');
  context.setVariable(properties.outboundVariableName, v);
}
  </Source>
</Javascript>

عنصر <SSLInfo>

تحدّد هذه السمة الخصائص المستخدَمة لضبط بروتوكول أمان طبقة النقل (TLS) لجميع مثيلات برامج HTTP التي تم إنشاؤها بواسطة سياسة JavaScript.

    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
    </SSLInfo>

إنّ عملية إعداد بروتوكول أمان طبقة النقل (TLS) لبرنامج HTTP هي العملية نفسها التي تستخدمها لإعداد بروتوكول أمان طبقة النقل (TLS) لـ TargetEndpoint أو TargetServer. لمزيد من المعلومات، راجِع ضبط طبقة النقل الآمنة (TLS) من Edge إلى الخلفية.

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

لا تحتوي سياسة JavaScript على أي رمز فعلي. بدلاً من ذلك، تشير سياسة JavaScript إلى "مصدر" JavaScript وتحدّد الخطوة في مسار واجهة برمجة التطبيقات التي يتم فيها تنفيذ JavaScript. يمكنك تحميل النص البرمجي من خلال محرّر وكيل واجهة مستخدم الإدارة، أو يمكنك تضمينه في الدليل /resources/jsc في خوادم وكيل واجهة برمجة التطبيقات التي تطوّرها محليًا.

تصحيح أخطاء رمز سياسة JavaScript

استخدِم الدالة print() لإخراج معلومات تصحيح الأخطاء إلى لوحة إخراج المعاملات في &quot;أداة التتبُّع&quot;. للاطّلاع على التفاصيل والأمثلة، راجِع عبارات print() في تصحيح الأخطاء باستخدام JavaScript.

لعرض عبارات الطباعة في "سجلّ التتبُّع"، اتّبِع الخطوات التالية:

1. افتح &quot;أداة التتبُّع&quot; وابدأ جلسة تتبُّع لخادم وكيل يحتوي على سياسة JavaScript.
2. الاتصال بالخادم الوكيل
3. في &quot;أداة التتبُّع&quot;، انقر على الإخراج من جميع المعاملات لفتح لوحة الإخراج.

   

4. ستظهر بياناتك المطبوعة في هذه اللوحة.

يمكنك استخدام الدالة print() لعرض معلومات تصحيح الأخطاء في أداة التتبُّع. تتوفّر هذه الدالة مباشرةً من خلال نموذج عناصر JavaScript. لمزيد من التفاصيل، راجِع مقالة تصحيح أخطاء JavaScript باستخدام عبارات print()‎.

متغيّرات التدفق

لا تملأ هذه السياسة أي متغيّرات تلقائيًا، ولكن يمكنك ضبط (واسترداد) متغيّرات التدفق في رمز JavaScript من خلال استدعاء طرق في عنصر السياق. يبدو النمط النموذجي على النحو التالي:

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"))

كائن السياق هو جزء من نموذج كائن JavaScript في Apigee Edge.

مرجع الخطأ

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Example error response

{
  "fault": {
    "faultstring": "Execution of SetResponse failed with error: Javascript runtime error: "ReferenceError: "status" is not defined. (setresponse.js:6)\"",
    "detail": {
      "errorcode": "steps.javascript.ScriptExecutionFailed"
    }
  }
}

Example fault rule

<FaultRule name="JavaScript Policy Faults">
    <Step>
        <Name>AM-CustomErrorResponse</Name>
        <Condition>(fault.name Matches "ScriptExecutionFailed") </Condition>
    </Step>
    <Condition>(javascript.JavaScript-1.failed = true) </Condition>
</FaultRule>

المخطط

يتم تحديد كل نوع من أنواع السياسات من خلال مخطّط XML (.xsd). وللحصول على مرجع، تتوفّر مخطّطات السياسات على GitHub.

مواضيع ذات صلة

• نموذج كائن JavaScript
• للحصول على التعليمات ونماذج السياسات ونماذج JavaScript، يُرجى الاطّلاع على برمجة خوادم وكيلة لواجهات برمجة التطبيقات باستخدام JavaScript.

مقالات "منتدى Apigee"

يمكنك العثور على هذه المقالات ذات الصلة في منتدى Apigee:

• كيفية التعامل مع العناوين ذات القيم المتعددة في JavaScript؟