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

أنت تعرض مستندات 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 بشكل ديناميكي).
• يتضمن رمز الحالة وعبارة السبب نصًا حرفيًا فقط؛ مع ذلك، تدعم هذه العناصر أيضًا نماذج الرسائل إذا كنت ترغب في استخدامها.

مثال

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

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

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

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

السياسة	العناصر والعناصر الثانوية التي تتوافق مع نماذج الرسائل
سياسة AccessControl	<SourceAddress>، للسمة mask عنوان IP.
سياسة assignMessage	<Set> العناصر الفرعية: Payload، وContentType، وVerb، و Version، وPath، وStatusCode، وreason التقديم، وHeaders، وQueryParams، وformParams عناصر <Add> الفرعية: Headers وQueryParams وformParams العنصر الثانوي <AssignVariable>: <Template>
سياسة ExtensionCallout	<Input>
سياسة استخراج المتغيّرات	<JsonPath>
سياسة GenerateJWS سياسة VerifyJWS	<Payload> (سياسة GenerateJWS فقط) <AdditionalHeaders><Claim> * لا تتوافق هذه العناصر مع نموذج الرسالة إلا عندما تكون type=map.
سياسة إنشاء JWT سياسة VerifyJWT	<AdditionalClaims><Claim> <AdditionalHeaders><Claim> * لا تتوافق هذه العناصر مع نموذج الرسالة إلا عندما تكون type=map.
سياسة LDAP	<SearchQuery>
سياسة تسجيل الرسائل النصية	<Syslog><Message> <File><Message>
سياسة التحقق من صحة OAS	عنصر واحد (<OASResource> )
سياسة SpamFault	عناصر <Set>: البيانات الأساسية، ContentType، الفعل، الإصدار، المسار، رمز الحالة، العبارة السبب، العناوين، QueryParams، FormParams عناصر <Add>: العناوين، QueryParams، وformParams
سياسة SAMLAssertion	<Template> * فقط عندما يكون توقيع السياسة هو <GenerateSAMLAssertion>
سياسة ServiceCallout	عناصر <Set>: البيانات الأساسية، ContentType، الفعل، الإصدار، المسار، رمز الحالة، العبارة السبب، /العناوين، QueryParams، FormParams عناصر <Add>: العناوين، QueryParams، وformParams <HTTPTargetConnection>/<URL>: تجدر الإشارة إلى أنّ الجزء الأول من السلسلة يجب أن يكون http أو https.

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

عناصر HTTPTargetConnection	العناصر الثانوية التي تتوافق مع نماذج الرسائل
SSLInfo	مُفعَّل، KeyAlias ، KeyStore، 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 قبل الإصدار 16.08.17 من Cloud، لا يمكنك استخدام الأقواس المتعرجة للإشارة إلى المراجع المتغيرة ضمن حمولات JSON. في تلك الإصدارات الأقدم، يجب استخدام السمتَين variablePrefix وvariableSuffix لتحديد المحدد، واستخدمها للالتفاف أسماء المتغيرات، كما يلي:

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

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

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

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

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

مثال: toLowCase()

استخدام دالة 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 - السلسلة المطلوب إفلاتها. يمكن أن تكون سلسلة حرفية أو متغير تدفق سلسلة.

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

يمكن أن يمثّل 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"

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

عرض تمثيل سلسلة للوقت، بتنسيق المنطقة الزمنية المحلية، أو بالتوقيت العالمي المنسق (UTC).

البنية

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

الوسيطات

• 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 - (مطلوبة) لتحديد الرسالة المطلوب توقيعها. يجب أن تكون سلسلة.
• 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 متتالي يمكن استخدامه مع عملية توقيع الإصدار 4 من AWS يستخدم المثال سياسة 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

تنشئ المعرّف الفريد العالمي وتعرضه.

البنية

createUuid()

الوسيطات

بلا عُري

مثال

{createUuid()}

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

ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8

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

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

البنية

randomLong(args)

الوسيطات

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

مثال

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

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