نماذج الرسائل

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

يناقش هذا الموضوع كيفية استخدام نماذج الرسائل في الخوادم الوكيلة لواجهة برمجة التطبيقات كما يوفر مرجعًا للدالة.

ما هو نموذج الرسالة؟

يسمح لك نموذج الرسالة بإجراء استبدال سلسلة متغيرة في عناصر معينة في السياسة وTargetEndpoint. وتتيح لك هذه الميزة، متى كانت متاحة، تعبئة السلاسل ديناميكيًا عند تنفيذ الخادم الوكيل.

يمكنك تضمين أي مجموعة من مراجع متغيرات التدفق والنصوص الحرفية في نموذج رسالة. يجب وضع أسماء متغيرات التدفق بين أقواس معقوفة، بينما يتم إخراج أي نص غير موجود بين الأقواس المعقوفة كنص حرفي.

راجِع أيضًا المقالة أين يمكنك استخدام نماذج الرسائل؟

مثال

على سبيل المثال، تتيح لك سياسة "تخصيص الرسالة" استخدام نموذج رسالة داخل العنصر <Payload> كما يلي:

<AssignMessage name="set-dynamic-content">
  <AssignTo createNew="false" type="response"></AssignTo>
  <Set>
    <Payload contentType="application/json">
      {"name":"Alert", "message":"You entered an invalid username: {user.name}"}
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

في المثال أعلاه، سيتم تقييم قيمة متغير التدفق user.name (في الأقواس المعقوفة) واستبدالها في سلسلة حمولة البيانات في وقت التشغيل. لذلك، على سبيل المثال، إذا تم user.name=jdoe، سيكون ناتج الرسالة الناتج في الحمولة على النحو التالي: You entered an invalid username: jdoe. إذا تعذر حل المتغير، فسيتم إخراج سلسلة فارغة.

مثال

وعند تجاوز حصة ما، من الممارسات الجيدة إعادة رسالة ذات معنى إلى المتصل. يشيع استخدام هذا النمط مع "قاعدة خطأ" لتقديم مخرجات بهدف تقديم معلومات للمتصل حول مخالفة الحصة. في سياسة "تخصيص الرسالة" التالية، يتم استخدام نماذج الرسائل لتعبئة معلومات الحصص بشكل ديناميكي في العديد من عناصر XML:

<AssignMessage name='AM-QuotaViolationMessage'>
  <Description>message for quota exceeded</Description>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <Set>
    <Headers>
      <Header name='X-Quota-Reset'>{ratelimit.Quota-1.expiry.time}</Header>
      <Header name='X-Quota-Allowed'>{ratelimit.Quota-1.allowed.count}</Header>
      <Header name='X-Quota-Available'>{ratelimit.Quota-1.available.count}</Header>
    </Headers>
    <Payload contentType='application/json'>{
  "error" : {
    "message" : "you have exceeded your quota",
    "clientId" : "{request.queryparam.apikey}"
  }
}
    </Payload>
    <StatusCode>429</StatusCode>
    <ReasonPhrase>Quota Exceeded</ReasonPhrase>
  </Set>
</AssignMessage>

في سياسة AssignMessage، تتيح العناصر التالية في العنصر <Set> تصميم نمط الرسالة:

• العنوان
• QueryParam
• FormParam
• PayLoad
• الإصدار
• فِعل
• المسار
• StatusCode
• ReasonPhrase

وتجدر الإشارة مرة أخرى إلى أن متغيرات التدفق في نموذج الرسالة يجب تضمينها بين أقواس معقوفة.

حالات تنفيذ هذه السياسة:

• وتتلقى عناصر العنوان قيم متغيرات التدفق المحددة.
• تتضمّن الحمولة مزيجًا من النصوص الحرفية والمتغيّرات (تتم تعبئة client_id ديناميكيًا).
• لا يحتوي كل من "StatusCode" و"WhyTerm" إلا على نص حرفي فقط، ولكن، تدعم هذه العناصر أيضًا صياغة الرسالة إذا كنت ترغب في استخدامها.

مثال

في تعريف TargetEndpoint للخادم الوكيل، تتوافق العناصر الثانوية في <SSLInfo> مع نماذج الرسائل. وباتباع نفس النمط المستخدم في النُهج، يتم استبدال متغيرات التدفق في الأقواس المعقوفة عند تنفيذ الخادم الوكيل.

<TargetEndpoint name="default">
  …
  <HTTPTargetConnection>
    <SSLInfo>
        <Enabled>{myvars.ssl.enabled}</Enabled>
        <ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled>
        <KeyStore>{myvars.ssl.keystore}</KeyStore>
        <KeyAlias>{myvars.ssl.keyAlias}</KeyAlias>
        <TrustStore>{myvars.ssl.trustStore}</TrustStore>
    </SSLInfo>

  </HTTPTargetConnection>
  …
</TargetEndpoint>

أين يمكنك استخدام نماذج الرسائل؟

تتوافق نماذج الرسائل مع العديد من السياسات، بالإضافة إلى عناصر معيَّنة تُستخدَم في إعدادات TargetEndpoint.

السياسات التي تقبل نماذج الرسائل

السياسة	العناصر والعناصر الفرعية التي تتوافق مع نماذج الرسائل
سياسة AccessControl	<SourceAddress>، للسمة mask وعنوان IP.
سياسة AssignMessage	العناصر الفرعية لـ <Set>: حمولة البيانات، ContentType، فعل، إصدار، مسار، رمز الحالة، REASONResult، العناوين، QueryParams، FormParams العناصر الفرعية في <Add>: العناوين وQueryParams وformParams العنصر الفرعي <AssignVariable>: <Template>
سياسة وسائل الشرح للإضافة	<Input>
سياسة المتغيّرات لاستخراج البيانات	<JsonPath>
سياسة GenerateJWS سياسة CheckJWS	<Payload> (سياسة GenerateJWS فقط) <AdditionalHeaders><Claim> * تتوافق هذه العناصر مع نموذج الرسالة فقط عندما تكون type=map.
سياسة GenerateJWT سياسة التحقّق من JWT	<AdditionalClaims><Claim> <AdditionalHeaders><Claim> * تتوافق هذه العناصر مع نموذج الرسالة فقط عندما تكون type=map.
سياسة LDAP	<SearchQuery>
سياسة MessageLogging	<Syslog><Message> <File><Message>
سياسة التحقّق من OAS	عنصر <OASResource>
سياسة KeepFault	عناصر <Set>: حمولة البيانات، نوع المحتوى، فعل، إصدار، مسار، رمز الحالة، reasonResult، العناوين، QueryParams، FormParams عناصر <Add>: العناوين وQueryParams وForformParams
سياسة SAMLAssertion	<Template> * فقط عندما يكون توقيع السياسة هو <GenerateSAMLAssertion>
سياسة وسائل الشرح للخدمة	عناصر <Set>: حمولة البيانات، ContentType، فعل، إصدار، مسار، رمز الحالة، reasonResult، /Headers، QueryParams، FormParams عناصر <Add>: العناوين وQueryParams وForformParams <HTTPTargetConnection>/<URL>: يجب أن يكون الجزء الأول من السلسلة http أو https.

عناصر TargetEndpoint التي تقبل نماذج الرسائل

عناصر HTTPTargetConnection	العناصر الثانوية التي تتوافق مع نماذج الرسائل
SSLInfo	مفعَّل، الاسم المستعار للمفتاح، ملف المفاتيح، TrustStore، ClientAuthEnabled، CLRStore
LocalTargetConnection	ApiProxy وProxyEndpoint
المسار	لا ينطبق

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

يوضِّح هذا القسم القواعد التي يجب اتّباعها لاستخدام نماذج الرسائل.

استخدام الأقواس المعقوفة للإشارة إلى المتغيرات

ضمِّن أسماء المتغيرات في الأقواس المعقوفة { }. وفي حال عدم توفّر المتغيّر، يتم عرض سلسلة فارغة في الإخراج، ولكن يمكنك تحديد قيم تلقائية في نماذج الرسائل (القيم التي يتم استبدالها إذا لم يتم حل المتغيّر). راجِع إعداد القيم التلقائية في نماذج الرسائل.

وتجدر الإشارة إلى أنه يُسمح بتضمين سلسلة نموذج الرسالة بالكامل بين علامتَي اقتباس، ولكنه اختياري. على سبيل المثال، نموذجا الرسائل التاليان متعادلان:

<Set>
    <Headers>
        <Header name="x-h1">"Hello {user.name}"</Header>
        <Header name="x-h1">Hello {user.name}</Header>
    </Headers>
</Set>

ضبط القيم التلقائية في نماذج الرسائل

إذا تعذر حل متغير نموذج، فإن Edge تستبدل سلسلة فارغة. ومع ذلك، يمكنك تحديد قيمة تلقائية على النحو التالي:

<Header name="x-h1">Test message. id = {request.header.id:Unknown}</Header>

في النموذج أعلاه، إذا تعذّر حلّ المتغيّر request.header.id، سيتم استبدال قيمته بالقيمة Unknown. مثال:

Test message. id = Unknown

لا يُسمح باستخدام المسافات في تعبيرات الدوال.

لا يُسمح باستخدام المسافات في أي مكان في تعبيرات دوال نماذج الرسائل. مثال:

مسموح به:

{substring(alpha,0,4)}
{createUuid()}
{randomLong(10)}

غير مسموح به:

{substring( alpha, 0, 4 )}
{ createUuid( ) }
{randomLong( 10 )}

البنية القديمة لحمولات JSON

في إصدارات Edge قبل إصدار Cloud 16.08.17، لم يكن بإمكانك استخدام الأقواس المعقوفة للإشارة إلى المراجع المتغيّرة ضمن حمولات JSON. في تلك الإصدارات الأقدم، كان عليك استخدام السمتَين variablePrefix وvariableSuffix لتحديد أحرف المحدِّد واستخدامها لإحاطة أسماء المتغيرات، على النحو التالي:

<Set>
  <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
    {"name":"foo", "type":"@variable_name#"}
  </Payload>
</Set>

على الرغم من أن Apigee توصي باستخدام بناء الجملة الأحدث للأقواس المعقوفة، إلا أن بناء الجملة الأقدم لا يزال يعمل.

استخدام وظائف نماذج الرسائل

يوفّر Edge مجموعة من الدوال التي يمكنك استخدامها داخل نماذج الرسائل للهروب من متغيرات السلسلة وترميزها وتجزئتها وتنسيقها.

يمكنك الاطّلاع على وصف تفصيلي لوظائف نموذج الرسالة في مرجع دالة نموذج الرسالة.

مثال: toLowerCase()

استخدِم دالة toLowerCase() المضمَّنة لتحويل متغيّر السلسلة إلى أحرف صغيرة:

<AssignMessage name="AM-Set-Custom-Response">
    <AssignTo createNew="false" type="response"/>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <Set>
        <Headers>
            <Header name="x-h1">Test header: {toLowerCase(foo.bar:FOO)}</Header>
        </Headers>
    </Set>
</AssignMessage>

إذا تم حلّ متغيّر مسار foo.bar، ستكون أحرفه كلها صغيرة. إذا لم يتم حل foo.bar، يتم استبدال القيمة التلقائية FOO وتحويلها إلى أحرف صغيرة. مثال:

Test header: foo

مثال: EscapeJSON()

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

{
      "code": "INVALID",
      "user_message": "Invalid value for \"logonId\" check your input."
}

ثم نقول أنك تريد إعادة هذه الرسالة إلى المتصل بالعميل في حمولة مخصصة. تتمثل الطريقة المعتادة لفعل ذلك في استخراج الرسالة من حمولة الاستجابة المستهدفة واستخدام "تعيين رسالة" لإضافتها إلى استجابة مخصصة للخادم الوكيل (أي إرسالها مرة أخرى إلى العميل).

في ما يلي سياسة "استخراج المتغيّرات" التي تستخرج معلومات user_message إلى متغيّر يُسمّى standard.systemMessage:

<ExtractVariables name="EV-BackendErrorResponse">
    <DisplayName>EV-BackendErrorResponse</DisplayName>
    <JSONPayload>
        <Variable name="standard.systemMessage">
            <JSONPath>$.user_message</JSONPath>
        </Variable>
    </JSONPayload>
</ExtractVariables>

إليك سياسة "تخصيص الرسالة" الصالحة تمامًا والتي تضيف المتغيّر المستخرَج إلى حمولة الاستجابة (استجابة الخادم الوكيل):

<AssignMessage name="AM-SetStandardFaultResponse">
    <DisplayName>AM-SetStandardFaultResponse</DisplayName>
    <Set>
        <Payload contentType="application/json">
           {
              "systemMessage": "{standard.systemMessage}"
           }
        </Payload>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

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

{
    "systemMessage": "Invalid value for "logonId" check your input."
}

لحل هذه المشكلة، يمكنك تعديل سياسة "تعيين الرسالة" لاستخدام وظيفة نموذج الرسالة التي تتخطى علامات الاقتباس داخل JSON نيابةً عنك. تعمل هذه الدالة، escapeJSON()، على إلغاء أي علامات اقتباس أو رموز خاصة أخرى تظهر في تعبير JSON:

<AssignMessage name="AM-SetStandardFaultResponse">
    <DisplayName>AM-SetStandardFaultResponse</DisplayName>
    <Set>
        <Payload contentType="application/json">
           {
              "systemMessage": "{escapeJSON(standard.systemMessage)}"
           }
        </Payload>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

تتجاهل الدالة علامات الاقتباس المضمّنة، ما يؤدي إلى إنشاء ملف JSON صالح، وهو ما تريده بالضبط:

{
      "systemMessage": "Invalid value for \"logonId\" check your input.",
}

نموذج الرسالة هو ميزة بديلة لسلسلة ديناميكية يمكنك استخدامها في سياسات معيّنة وفي تعريفات نقطة النهاية الهدف. تتيح لك دوال نموذج الرسالة إجراء عمليات مفيدة، مثل التجزئة ومعالجة السلاسل واستبعاد الأحرف وغير ذلك من العمليات داخل نموذج الرسالة.

على سبيل المثال، في سياسة AssignMessage التالية، يتم استخدام الدالة toLowerCase() في نموذج رسالة:

<AssignMessage name="AM-Set-Custom-Response">
    <AssignTo createNew="false" type="response"/>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <Set>
       <Headers>
         <Header name="x-h1">Test header: {Hello, toLowerCase(user.name)}</Header>
       </Headers>
    </Set>
</AssignMessage>

يصف هذا الموضوع دوال نموذج الرسالة ووسيطاتها ومخرجاتها. يفترض هذا الموضوع أنّك على دراية بنماذج الرسائل والسياقات التي تُستخدَم فيها.

دوال التجزئة

احتساب قيمة تجزئة وعرض تمثيل السلسلة لهذه التجزئة

دوال التجزئة السداسية العشرية

احسب قيمة تجزئة وعرض تمثيل السلسلة لتلك التجزئة كرقم سداسي عشري.

البنية

الدالة	الوصف
md5Hex(string)	تحسب تجزئة MD5 ويتم التعبير عنها كرقم سداسي عشري.
sha1Hex(string)	تحسب تجزئة SHA1 كرقم سداسي عشري.
sha256Hex(string)	تحتسب تجزئة SHA256 كرقم سداسي عشري.
sha384Hex(string)	تحتسب تجزئة SHA384 كرقم سداسي عشري.
sha512Hex(string)	تحسب تجزئة SHA512 كرقم سداسي عشري.

الوسيطات

string - تستخدم دوال التجزئة وسيطة سلسلة واحدة يتم حساب خوارزمية التجزئة عليها. يمكن أن تكون الوسيطة سلسلة حرفية أو متغير تدفق سلسلة.

أمثلة

استدعاء الدالة:

sha256Hex('abc')

النتيجة:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

استدعاء الدالة:

var str = 'abc';
sha256Hex(str)

النتيجة:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

دوال التجزئة Base64

احتساب قيمة تجزئة وعرض تمثيل السلسلة لتلك التجزئة كقيمة مشفرة باستخدام Base64

البنية

الدالة	الوصف
md5Base64(string)	تحسب تجزئة MD5 معبرًا عنها بقيمة Base64 مرمّزة.
sha1Base64(string)	تحسب تجزئة SHA1 معبرًا عنها بقيمة Base64 مرمّزة.
sha256Base64(string)	تحسب تجزئة SHA256 معبرًا عنها بقيمة Base64 مرمّزة.
sha384Base64(string)	تحسب تجزئة SHA384 التي يتم التعبير عنها كمقيم بترميز Base64.
sha512Base64(string)	تحسب تجزئة SHA512 معبرًا عنها بقيمة Base64 المشفرة.

الوسيطات

string - تستخدم دوال التجزئة وسيطة سلسلة واحدة يتم حساب خوارزمية التجزئة عليها. يمكن أن تكون الوسيطة سلسلة حرفية أو متغيّر تدفق السلسلة.

أمثلة

استدعاء الدالة:

sha256Base64('abc')

النتيجة:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

استدعاء الدالة:

var str = 'abc';
sha256Base64(str)

النتيجة:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

دوال السلاسل

تنفيذ عمليات على السلاسل داخل نموذج رسالة

دوال ترميز Base64

ترميز وفك ترميز السلاسل باستخدام نظام ترميز Base64.

البنية

الدالة	الوصف
encodeBase64(string)	لترميز سلسلة باستخدام ترميز Base64. على سبيل المثال: encodeBase64(value)، عندما يتضمّن value abc، تعرض الدالة السلسلة: YWJj
decodeBase64(string)	تفكّ ترميز سلسلة Base64 المشفَّرة. على سبيل المثال: decodeBase64(value) عندما يتضمّن value aGVsbG8sIHdvcmxk، تعرض الدالة السلسلة hello, world.

الوسيطات

string - السلسلة المطلوب ترميزها أو فك ترميزها. يمكن أن يكون سلسلة حرفية أو متغيّرًا لتدفق السلسلة.

مثال

<AssignMessage name="AM-Set-Custom-Response">
    <AssignTo createNew="false" type="response"/>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <Set>
       <Headers>
         <Header name="x-h1">Hello, {decodeBase64('d29ybGQK')}</Header>
       </Headers>
    </Set>
</AssignMessage>

دوالّ تحويل الطلبات

تحويل سلسلة إلى أحرف كبيرة أو صغيرة بالكامل.

البنية

الدالة	الوصف
toUpperCase(string)	تحويل سلسلة إلى أحرف كبيرة.
toLowerCase(string)	تحويل السلسلة إلى أحرف صغيرة.

الوسيطات

string - السلسلة المطلوب تحويلها. يمكن أن يكون سلسلة حرفية أو متغيّرًا لتدفق السلسلة.

مثال

<AssignMessage name="AM-Set-Custom-Response">
    <AssignTo createNew="false" type="response"/>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <Set>
       <Headers>
         <Header name="x-h1">Hello, {toLowerCase(user.name)}</Header>
       </Headers>
    </Set>
</AssignMessage>

دالة السلسلة الفرعية

لعرض الأحرف بين فهرس البداية والنهاية للسلسلة المحددة.

البنية

substring(str,start_index,end_index)

الوسيطات

• str - سلسلة حرفية أو متغيّر لتدفق السلسلة.
• start_index - فهرس البدء في السلسلة.
• end_index - (اختياري) فهرس النهاية في السلسلة. وإذا لم يتم توفيره، يكون فهرس النهاية هو نهاية السلسلة.

أمثلة

وفيما يتعلق بالأمثلة التالية، لنفترض أن هناك متغيرات التدفق هذه:

اسم المتغيّر	القيمة
alpha	أ ب ت ث ج ح خ د ذ ر ز س ش ص ض ط ظ ع غ ف ق ك ل م ن ه و ي
seven	7

في ما يلي نتائج لاستدعاءات الدوال التي تستخدم هذه المتغيّرات:

تعبير نموذج الرسالة	النتيجة
{substring(alpha,22)}	WXYZ
hello {substring(alpha,22)}	hello WXYZ
{substring(alpha,-4)}	WXYZ
{substring(alpha,-8,-4)}	STUV
{substring(alpha,0,10)}	ABCDEFGHIJ
{substring(alpha,0,seven)}	ABCDEFG

دالة استبدال الكل

لتطبيق تعبير عادي على سلسلة ولأي مطابقات، يستبدل المطابقة بقيمة بديلة.

البنية

replaceAll(string,regex,value)

الوسيطات

• string - سلسلة حرفية أو متغيّر تدفق السلسلة المطلوب إجراء الاستبدالات به.
• regex - تعبير عادي.
• value - القيمة المطلوب استبدالها بجميع مطابقات التعبير العادي ضمن السلسلة.

أمثلة

في ما يتعلق بالأمثلة التالية، لنفترض أن هناك متغيّرات التدفق التالية:

اسم المتغيّر	القيمة
header	Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993
regex1	"^Bearer "
replacement	"TOKEN: "

في ما يلي نتائج استدعاء الدوالّ التي تستخدم هذه المتغيّرات:

تعبير نموذج الرسالة	النتيجة
{replaceAll(header,"9993",'')}	Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-
{replaceAll(header,regex1,'')}	ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993
{replaceAll(header,regex1,replacement)}	TOKEN: ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993

استبدال الدالة الأولى

لاستبدال المرة الأولى فقط لمطابقة التعبير العادي المحدّد في السلسلة.

البنية

replaceFirst(string,regex,value)

الوسيطات

• string - سلسلة حرفية أو متغيّر تدفق السلسلة المطلوب إجراء الاستبدالات به.
• regex - تعبير عادي.
• value - القيمة المطلوب استبدالها بمطابقات التعبير العادي ضمن السلسلة.

دوال الترميز وتخطي الأحرف

دوالٍ تستبعد أحرفًا خاصة أو تشفّرها في سلسلة معيّنة.

البنية

الدالة	الوصف
EscapeJSON(string)	تتخطى الشرطة المائلة للخلف علامات الاقتباس المزدوجة.
EscapeXML(string)	تستبدل علامات الاقتباس والفواصل العليا وعلامات الاقتباس المزدوجة وعلامات العطف بكيانات XML ذات الصلة. تُستخدم مع مستندات XML 1.0
EscapeXML11(string)	تعمل هذه السياسة بالطريقة نفسها التي يتم بها تنفيذ EscapeXML، ولكن مع كيانات XML الإصدار 1.1. راجع ملاحظات الاستخدام أدناه.
encodeHTML(string)	لترميز الفاصلة العليا وأقواس الزاوية وعلامة العطف.

الوسيطات

string - السلسلة المطلوب Escape. يمكن أن يكون سلسلة حرفية أو متغيّرًا لتدفق السلسلة.

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

يمكن أن يمثّل XML 1.1 أحرف تحكّم معيّنة، ولكن لا يمكن أن يمثّل رمز البايت الفارغ أو نقاط الرموز البديلة لـ Unicode غير المقترنة، حتى بعد إنهاء الأحرف. تزيل الدالة EscapeXML11() الأحرف التي لا تناسب النطاقات التالية:

[#x1-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]

تتخطى الدالة escapeXML11() الأحرف في النطاقات التالية:

[#x1-#x8] | [#xB-#xC] | [#xE-#x1F] | [#x7F-#x84] | [#x86-#x9F]

أمثلة

لنفترض أن هناك متغيّر تدفق يُسمى food بالقيمة التالية: "bread" & "butter". بعد ذلك، الدالة:

{escapeHTML(food)}

النتائج في:

"bread" & "butter"

دوال تنسيق الوقت

يمكنك عرض تمثيل على شكل سلسلة للوقت، منسقًا حسب المنطقة الزمنية المحلية، أو بالتوقيت العالمي المنسّق.

البنية

الدالة	الوصف
timeFormat(format,str)	تعرض التاريخ المنسَّق في المنطقة الزمنية المحلية.
timeFormatMs(format,str)	تعرض التاريخ المنسَّق في المنطقة الزمنية المحلية.
timeFormatUTC(format,str)	تعرض التاريخ بالتنسيق العالمي المنسق.
timeFormatUTCMs(format,str)	تعرض التاريخ بالتنسيق العالمي المنسق.

الوسيطات

• format - سلسلة تنسيق الوقت/التاريخ. يمكن أن يكون سلسلة حرفية أو متغير سلسلة.
• str - متغيّر سلسلة أو متغيّر لتدفق السلسلة يحتوي على قيمة زمنية. يمكن أن تكون القيمة الثواني-cince-epoch أو بالملي ثانية-منذ-الحقبة بالنسبة إلى TimeFormatMs.

أمثلة

لنفترض أنّ القيم التالية هي المنطقة الزمنية المحلية، ونفترض أنّ المنطقة الزمنية المحلية هي المحيط الهادئ:

• epoch_time_ms = 1494390266000
• epoch_time = 1494390266
• fmt1 = yyyy-MM-dd
• fmt2 = yyyy-MM-dd HH-mm-ss
• fmt3 = yyyyMMddHHmmss

تعرض الدوال النتائج التالية:

الوظيفة	الناتج
timeFormatMs(fmt1,epoch_time_ms)	2017-05-09
timeFormat(fmt1,epoch_time)	2017-05-09
timeFormat(fmt2,epoch_time)	2017-05-09 21:24:26
timeFormat(fmt3,epoch_time)	20170509212426
timeFormatUTC(fmt1,epoch_time)	2017-05-10
timeFormatUTC(fmt2,epoch_time)	2017-05-10 04:24:26
timeFormatUTC(fmt3,epoch_time)	20170510042426

دوال حساب HMAC

توفّر وظائف حساب HMAC بديلاً لاستخدام سياسة HMAC لحساب نظام HMAC. تكون الدوالّ مفيدة عند إجراء عملية حسابية متتابعة لرمز HMAC، على سبيل المثال عندما يتم استخدام ناتج أحد رموز HMAC كمفتاح لعملية مصادقة HMAC ثانية.

البنية

الدالة	الوصف
hmacSha224(key,valueToSign[,keyencoding[,outputencoding]])	تحسب HMAC باستخدام وظيفة التجزئة SHA-224.
hmacSha256(key,valueToSign[,keyencoding[,outputencoding]])	لترميز HMAC باستخدام وظيفة التجزئة SHA-256.
hmacSha384(key,valueToSign[,keyencoding[,outputencoding]])	لترميز HMAC باستخدام وظيفة التجزئة SHA-384.
hmacSha512(key,valueToSign[,keyencoding[,outputencoding]])	لترميز HMAC باستخدام وظيفة التجزئة SHA-512.
hmacMd5(key,valueToSign[,keyencoding[,outputencoding]])	لترميز HMAC باستخدام دالة التجزئة MD5.
hmacSha1(key, valueToSign [,keyencoding[,outputencoding]])	لترميز HMAC باستخدام خوارزمية تشفير SHA-1.

الوسيطات

• key - (مطلوبة) تحدّد المفتاح السري، المُشفَّر كسلسلة، ويُستخدم لحساب HMAC.
• valueToSign - (مطلوب) يحدد الرسالة المراد توقيعها. يجب أن تكون القيمة سلسلة.
• keyencoding - (اختيارية) سيتم فك ترميز سلسلة المفتاح السري وفقًا لهذا الترميز المحدّد. القيم الصالحة: hex، base16، base64، utf-8. اللغة التلقائية: utf-8
• outputencoding - (اختياري) لتحديد خوارزمية الترميز المطلوب استخدامها في الإخراج. القيم الصالحة: hex، base16، base64. القيم غير حساسة لحالة الأحرف، وبالتالي فإنّ hex وbase16 مرادفان. اللغة التلقائية: base64

أمثلة

يستخدم هذا المثال سياسة AssignMessage لحساب HMAC-256 وتعيينه لمتغيّر مسار:

<AssignMessage name='AM-HMAC-1'>
  <AssignVariable>
    <Name>valueToSign</Name>
    <Template>{request.header.apikey}.{request.header.date}</Template>
  </AssignVariable>
  <AssignVariable>
    <Name>hmac_value</Name>
    <Template>{hmacSha256(private.secretkey,valueToSign)}</Template>
  </AssignVariable>
</AssignMessage>

يوضّح هذا المثال كيفية إنشاء رمز HMAC متتابع يمكن استخدامه مع عملية توقيع AWS Signature v4. يستخدم هذا المثال سياسة AssignMessage لإنشاء المستويات الخمسة من رمز HMAC المتتالي والمتتالي والتي يتم استخدامها لاحتساب توقيع للإصدار 4 من توقيع AWS:

<AssignMessage name='AM-HMAC-AWS-1'>
  <!-- 1 -->
  <AssignVariable>
    <Name>DateValue</Name>
    <Template>{timeFormatUTCMs('yyyyMMdd',system.timestamp)}</Template>
  </AssignVariable>
  <!-- 2 -->
  <AssignVariable>
    <Name>FirstKey</Name>
    <Template>AWS4{private.secret_aws_access_key}</Template>
  </AssignVariable>
  <!-- 3 -->
  <AssignVariable>
    <Name>DateKey</Name>
    <Template>{hmacSha256(FirstKey,DateValue,'utf-8','base16')}</Template>
  </AssignVariable>
  <!-- 4 -->
  <AssignVariable>
    <Name>DateRegionKey</Name>
    <Template>{hmacSha256(DateKey,aws_region,'base16','base16')}</Template>
  </AssignVariable>
  <!-- 5 -->
  <AssignVariable>
    <Name>DateRegionServiceKey</Name>
    <Template>{hmacSha256(DateRegionKey,aws_service,'base16','base16')}</Template>
  </AssignVariable>
  <!-- 6 -->
  <AssignVariable>
    <Name>SigningKey</Name>
    <Template>{hmacSha256(DateRegionServiceKey,'aws4_request','base16','base16')}</Template>
  </AssignVariable>
  <!-- 7 -->
  <AssignVariable>
    <Name>aws4_hmac_value</Name>
    <Template>{hmacSha256(SigningKey,stringToSign,'base16','base16')}</Template>
  </AssignVariable>
</AssignMessage>

الدوال الأخرى

إنشاء دالة UUID

تنشئ الأداة UUID وتعرضها.

البنية

createUuid()

الوسيطات

بلا عُري

مثال

{createUuid()}

مثال على النتيجة:

ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8

دالة المنشئ الطويل العشوائية

لعرض عدد صحيح طويل عشوائي.

البنية

randomLong(args)

الوسيطات

• إذا لم يتم تحديد أي وسيطات، تعرض الدالة عددًا صحيحًا طويلاً عشوائيًا، حسبما تُحتسبه فئة Java SecureSpam.
• في حالة وجود وسيطة واحدة، يتم التعامل معها على أنها أدنى قيمة للحساب.
• في حالة وجود وسيطة ثانية، يتم التعامل معها على أنها أقصى قيمة للحساب.

مثال

{random()}

النتائج إلى شيء مثل هذا:

5211338197474042880

أداة إنشاء نص التعبير العادي

إنشاء سلسلة نصية تطابق تعبيرًا عاديًا معيَّنًا

البنية

xeger(regex)

الوسيطة

regex - تعبير عادي.

مثال

ينشئ هذا المثال سلسلة من 7 أرقام بدون أصفار:

xeger('[1-9]{7}')

مثال على النتيجة:

9857253

دالة الدمج الخالية

تعرض الدالة firstnonnull() قيمة الوسيطة غير الفارغة في أقصى اليسار.

البنية

firstnonnull(var1,varn)

الوسيطة

var1 - متغير سياق.

var_n - متغيّر سياق واحد أو أكثر. يمكنك ضبط الوسيطة أقصى اليمين على سلسلة لتقديم قيمة احتياطية (قيمة سيتم ضبطها إذا لم يتم ضبط أي من الوسيطات اليسرى).

أمثلة

يوضح الجدول التالي كيفية استخدام الدالة:

نموذج	Var1	Var2	Var3	النتيجة
{firstnonnull(var1,var2)}	لم يتم الضبط.	foo	لا ينطبق	foo
{firstnonnull(var1,var2)}	foo	bar	لا ينطبق	foo
{firstnonnull(var1,var2)}	foo	لم يتم الضبط.	لا ينطبق	foo
{firstnonnull(var1,var2,var3)}	foo	bar	baz	foo
{firstnonnull(var1,var2,var3)}	لم يتم الضبط.	bar	baz	bar
{firstnonnull(var1,var2,var3)}	لم يتم الضبط.	لم يتم الضبط.	baz	baz
{firstnonnull(var1,var2,var3)}	لم يتم الضبط.	لم يتم الضبط.	لم يتم الضبط.	null
{firstnonnull(var1)}	لم يتم الضبط.	لا ينطبق	(لا ينطبق)	null
{firstnonnull(var1)}	foo	(لا ينطبق)	(لا ينطبق)	foo
{firstnonnull(var1,var2)}	""	bar	لا ينطبق	""
{firstnonnull(var1,var2,'fallback value')}	null	null	fallback value	fallback value

دالة XPath

يتيح هذا الخيار تطبيق تعبير XPath على متغيّر XML.

البنية

xpath(xpath_expression,xml_string,[datatype])

الوسيطات

xpath_expression - تعبير XPath.

xml_string - متغير تدفق أو سلسلة تحتوي على XML.

datatype - (اختيارية) تحدّد نوع العرض المطلوب لطلب البحث. ويمكن أن تكون مجموعة عُقد أو عقدة أو رقم أو قيمة منطقية أو سلسلة. يتم تكوينها افتراضيًا على مجموعة العُقد. عادةً ما يكون الخيار التلقائي هو الخيار الصحيح.

مثال 1

لنفترض أنّ متغيرات السياق التالية تحدّد سلسلة XML وتعبير XPath:

xml = "<tag><tagid>250397</tagid><readerid>1</readerid><rssi>74</rssi><date>2019/06/15</date></tag>"
xpath = "/tag/tagid"

ويتم استخدام الدالة xpath() في سياسة AssignMessage على النحو التالي:

<AssignMessage>
  <AssignVariable>
    <Name>extracted_tag</Name>
    <Template>{xpath(xpath,xml)}</Template>
  </AssignVariable>
</AssignMessage><

تُرجع الدالة القيمة <tagid>250397</tagid>. يتم وضع هذه القيمة في متغيّر السياق الذي يُسمى extracted_tag.

مثال 2

إذا كنت تريد قيمة العقدة فقط، فاستخدم الدالة text() على النحو التالي:

<AssignMessage>
  <AssignVariable>
    <Name>extracted_tag</Name>
    <Template>{xpath('/tag/tagid/text()',xml)}</Template>
  </AssignVariable>
</AssignMessage>

نتيجةً لهذه العملية، تم ضبط متغير السياق extracted_tag على 250397

إذا تم تحديد عُقد متعددة، تكون نتيجة xpath() هي جميع قيم التحديد، مع تسلسلها بفاصلة.

مثال 3: مساحات اسم XML

لتحديد مساحة اسم، عليك إلحاق مَعلمات إضافية، بحيث تكون كل منها سلسلة على شكل prefix:namespaceuri. على سبيل المثال، قد تكون دالة xpath() التي تحدد العنصر الفرعي لنص SOAP على النحو التالي:

<AssignMessage>
  <AssignVariable>
    <Name>soapns</Name>
    <Value>soap:http://schemas.xmlsoap.org/soap/envelope/</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>xpathexpression</Name>
    <Value>/soap:Envelope/soap:Body/*</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>extracted_element</Name>
    <Template>{xpath(xpathexpression,xml,soapns)}</Template>
  </AssignVariable>
</AssignMessage>

بالنسبة إلى مساحات الاسم الإضافية، يمكنك إضافة ما يصل إلى 10 معلَمات إضافية إلى الدالة xpath().

ويمكنك تحديد تعبير XPath بسيط كسلسلة محاطة بعلامات اقتباس مفردة:

{xpath('/tag/tagid/text()',xml)}

إذا كان تعبير XPath يتضمن بادئات مساحة الاسم (ونقطتين)، فستحتاج إلى تعيين تعبير XPath هذا إلى متغير وتحديد اسم المتغير بدلاً من التعبير مباشرة.

{xpath(xpathexpression,xml,ns1)}

المثال 4: تحديد نوع العرض المطلوب

تحدّد المَعلمة الثالثة الاختيارية التي يتم تمريرها إلى الدالة xpath() نوع الإرجاع المطلوب لطلب البحث.

يمكن أن تعرض بعض استعلامات XPath قيمًا رقمية أو منطقية. على سبيل المثال، تعرض الدالة count() رقمًا. هذا استعلام XPath صالح:

count(//Record/Fields/Pair)

يعرض هذا الاستعلام الصالح قيمة منطقية:

count(//Record/Fields/Pair)>0

في هذه الحالات، يمكنك استدعاء الدالة xpath() مع معلمة ثالثة تحدد هذا النوع:

{xpath(expression,xml,'number')}
{xpath(expression,xml,'boolean')}

إذا كانت المعلمة الثالثة تحتوي على نقطتين، فسيتم تفسيرها كوسيطة مساحة اسم. وإذا لم يكن متوفّرًا، يتم التعامل معه على أنّه نوع الإرجاع المطلوب. في هذه الحالة، إذا لم تكن المَعلمة الثالثة من القيم الصالحة (مع تجاهُل حالة الأحرف)، ستعرِض الدالة xpath() مجموعة عقدة تلقائيًا.

دالة مسار JSON

تطبِّق هذه الدالة تعبير مسار JSON على متغيّر JSON.

البنية

jsonPath(json-path,json-var,want-array)

الوسيطات

• (مطلوب) json-path: (سلسلة) تعبير مسار JSON.
• (مطلوبة) json-var: (سلسلة) متغيّر تدفق أو سلسلة تحتوي على JSON.
• (اختياري) want-array: (سلسلة) إذا تم ضبط هذه المعلَمة على 'true' وإذا كانت مجموعة النتائج مصفوفة، يتم عرض جميع عناصر الصفيف. في حال ضبطها على أي قيمة أخرى أو حذف هذه المَعلمة، سيتم عرض العنصر الصفري فقط لمصفوفة مجموعة النتائج. إذا لم تكن مجموعة النتائج مصفوفة، سيتم تجاهل هذه المعلَمة الثالثة، في حال توفّرها.

مثال 1

إذا كان هذا هو نموذج الرسالة:

The address is {jsonPath($.results[?(@.name == 'Mae West')].address.line1,the_json_variable)}

وتحتوي السمة the_json_variable على:

{
  "results" : [
    {
      "address" : {
        "line1" : "18250 142ND AV NE",
        "city" : "Woodinville",
        "state" : "Washington",
        "zip" : "98072"
      },
      "name" : "Fred Meyer"
    },
    {
      "address" : {
        "line1" : "1060 West Addison Street",
        "city" : "Chicago",
        "state" : "Illinois",
        "zip" : "60613"
      },
      "name" : "Mae West"
    }
  ]
} 

نتيجة الدالة هي:

The address is 1060 West Addison Street

لاحظ أنه في هذه الحالة، تكون مجموعة النتائج عنصرًا واحدًا (وليس مصفوفة من العناصر). وإذا كانت مجموعة النتائج عبارة عن مصفوفة، سيتم عرض العنصر الصفري فقط من الصفيفة. لعرض الصفيف الكامل، يجب استدعاء الدالة باستخدام 'true' باعتبارها المعلَمة الثالثة، كما هو موضّح في المثال التالي.

مثال 2

إذا كان هذا هو نموذج الرسالة:

{jsonPath($.config.quota[?(@.operation=='ManageOrder')].appname,the_json_variable,'true')}

وتحتوي السمة the_json_variable على:

{
  "results" : [
     {
      "config": {
        "quota": [
          {
            "appname": "A",
            "operation": "ManageOrder",
            "value": "900"
          },
          {
            "appname": "B",
            "operation": "ManageOrder",
            "value": "1000"
          },
          {
            "appname": "B",
            "operation": "SubmitOrder",
            "value": "800"
          }
        ]
      }
    }
  ]
} 

نتيجة الدالة هي:

['A','B']