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

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

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

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

يتيح لك نموذج الرسالة إجراء استبدال السلسلة المتغيرة في عناصر معيّنة من السياسة و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 هي 1، ستكون قيمة الرسالة الناتجة في الحمولة هي 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>

في ما يلي سياسة Assign Message صالحة تمامًا تضيف المتغيّر الذي تم استخراجه إلى حمولة الرد (رد الخادم الوكيل):

<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

الوسيطات

• المفتاح: (مطلوب) يحدّد المفتاح السري، الذي تم ترميزه كسلسلة، والمستخدَم لحساب 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 المتتالي المستخدَم لحساب توقيع 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,varnn>)

الوسيطة

استبدِل 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 أو node أو number أو boolean أو string. القيمة التلقائية هي 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 Path

تطبيق تعبير JSON Path على متغيّر JSON

البنية

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

الوسيطات

• (مطلوب) json-path: (سلسلة) تعبير JSON Path.
• (مطلوب) 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']