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

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

يتناول هذا الموضوع كيفية استخدام نماذج الرسائل في الوكلاء لـ API ويقدّم مرجعًا لدالّة.

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

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

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

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

مثال

على سبيل المثال، تتيح لك سياسة "تعيين الرسالة" استخدام نموذج رسالة ضمن العنصر <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 وReasonPhrase سوى نص حرفي، ولكن تتيح هذه العناصر أيضًا استخدام نماذج الرسائل إذا أردت ذلك.

مثال

في تعريف 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.

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

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

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

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

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

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

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

<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 قبل الإصدار 16.08.17 من Cloud، لا يمكنك استخدام الأقواس المتعرجة للإشارة إلى مراجع المتغيّرات ضمن حِزم بيانات 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."
}

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

في ما يلي سياسة استخراج المتغيّرات التي تستخرج معلومات 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.",
}

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

على سبيل المثال، في سياسة 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>

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

دوال التجزئة

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

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

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

البنية

الوسيطات

string: تأخذ وظائف التجزئة وسيطة سلسلة واحدة يتم حساب خوارزمية التجزئة استنادًا إليها. يمكن أن تكون الوسيطة سلسلة حرفية أو متغيّر تدفق سلسلة.

أمثلة

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

sha256Hex('abc')

النتيجة:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

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

var str = 'abc';
sha256Hex(str)

النتيجة:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

دوال تجزئة Base64

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

البنية

الوسيطات

string: تأخذ وظائف التجزئة وسيطة سلسلة واحدة يتم حساب خوارزمية التجزئة استنادًا إليها. يمكن أن تكون الوسيطة سلسلة حرفية أو متغيّر تدفق سلسلة.

أمثلة

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

sha256Base64('abc')

النتيجة:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

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

var str = 'abc';
sha256Base64(str)

النتيجة:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

دوال السلاسل

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

دوال ترميز Base64

ترميز السلاسل وفك ترميزها باستخدام مخطّط ترميز Base64

البنية

الوسيطات

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

دوال تحويل حالة الأحرف

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

البنية

الوسيطات

‫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 - (اختياري) مؤشر النهاية في السلسلة في حال عدم تقديمه، يكون الفهرس المنتهي هو نهاية السلسلة.

أمثلة

في الأمثلة التالية، لنفترض أنّ متغيّرات المسار هذه متوفّرة:

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

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

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

البنية

replaceAll(string,regex,value)

الوسيطات

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

أمثلة

في الأمثلة التالية، لنفترض أنّ متغيّرات المسار التالية متوفّرة:

في ما يلي نتائج طلبات الدالة التي تستخدِم هذه المتغيّرات:

دالة Replace First

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

البنية

replaceFirst(string,regex,value)

الوسيطات

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

دوال ترميز الأحرف وتجنُّبها

الدوالّ التي تتجنّب الرموز الخاصة أو تُشفّرها في سلسلة

البنية

الوسيطات

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

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

يمكن أن يمثّل تنسيق 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)}

يؤدي ذلك إلى:

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

عرض تمثيل سلسلة للوقت بتنسيق المنطقة الزمنية المحلية أو بالتوقيت العالمي المنسق

البنية

الوسيطات

• ‫format: سلسلة تنسيق التاريخ أو الوقت يمكن أن تكون سلسلة حرفية أو متغيّر سلسلة.
• ‫str: سلسلة أو متغيّر تدفق سلسلة يحتوي على قيمة زمنية. يمكن أن تكون القيمة بالثواني منذ بدء حساب الفترة أو بالملي ثانية منذ بدء حساب الفترة لمَعلمة 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: (مطلوبة) لتحديد الرسالة المطلوب توقيعها. يجب أن تكون سلسلة.
• ‫ترميز المفتاح - (اختياري) سيتم فك ترميز سلسلة المفتاح السري وفقًا لهذا الترميز المحدّد. القيم الصالحة هي: 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 المتسلسل المستخدَم لاحتساب توقيع لإصدار AWS Signature v4:

<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

دالة Random Long Generator

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

البنية

randomLong(args)

الوسيطات

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

مثال

{random()}

يؤدي ذلك إلى ظهور النتيجة التالية:

5211338197474042880

أداة إنشاء النصوص باستخدام التعبيرات العادية

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

البنية

xeger(regex)

الوسيطة

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

مثال

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

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: (اختياري) يحدِّد نوع العرض المطلوب للطلب. يمكن أن يكون مجموعة_العقد أو عقدة أو رقم أو منطقي أو سلسلة. يكون الإعداد التلقائي هو nodeset. وعادةً ما يكون الخيار التلقائي هو الخيار الصحيح.

مثال 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']