قالب های پیام

شما در حال مشاهده اسناد Apigee Edge هستید.
به مستندات Apigee X بروید . اطلاعات

این مبحث نحوه استفاده از الگوهای پیام در پراکسی های API را مورد بحث قرار می دهد و یک مرجع تابع ارائه می دهد.

قالب پیام چیست؟

یک الگوی پیام به شما امکان می دهد تا در برخی از عناصر خط مشی و TargetEndpoint جایگزین رشته متغیر را انجام دهید. این ویژگی، در صورت پشتیبانی، به شما امکان می‌دهد رشته‌ها را به صورت پویا در هنگام اجرای یک پروکسی پر کنید.

شما می توانید هر ترکیبی از مراجع متغیر جریان و متن تحت اللفظی را در قالب پیام قرار دهید. نام متغیرهای جریان باید در پرانتزهای فرفری محصور شود، در حالی که هر متنی که در پرانتز فرفری نباشد به عنوان متن تحت اللفظی خروجی می شود.

همچنین ببینید کجا می توانید از الگوهای پیام استفاده کنید؟

مثال

به عنوان مثال، خط مشی Assign Message به شما امکان می دهد از یک الگوی پیام در عنصر <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>

در مثال بالا، مقدار متغیر flow user.name (در پرانتزهای فرفری) ارزیابی شده و در زمان اجرا در رشته payload جایگزین می‌شود. بنابراین، برای مثال، اگر user.name=jdoe ، پیام خروجی در محموله به صورت زیر خواهد بود: You entered an invalid username: jdoe . اگر متغیر قابل حل نباشد، یک رشته خالی خروجی می شود.

مثال

هنگامی که از یک سهمیه فراتر رفت، این تمرین خوبی است که یک پیام معنادار به تماس گیرنده برگردانید. این الگو معمولاً با یک "قانون خطا" برای ارائه خروجی برای دادن اطلاعات تماس گیرنده در مورد نقض سهمیه استفاده می شود. در خط مشی Assign Message زیر، از الگوهای پیام برای پر کردن اطلاعات سهمیه به صورت پویا در چندین عنصر 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
• نسخه
• فعل
• مسیر
• کد وضعیت
• عبارت Reason

مجدداً، توجه داشته باشید که متغیرهای جریان در یک الگوی پیام باید در پرانتزهای فرفری محصور شوند .

هنگامی که این سیاست اجرا می شود:

• عناصر Header مقادیر متغیرهای جریان مشخص شده را دریافت می کنند.
• Payload شامل ترکیبی از متن تحت اللفظی و متغیرها است ( 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 قبل از انتشار Cloud 16.08.17 ، نمی‌توانید از بریس‌های فرفری برای نشان دادن مراجع متغیر در بارهای JSON استفاده کنید. در آن نسخه‌های قدیمی‌تر، باید از ویژگی‌های variablePrefix و variableSuffix برای تعیین کاراکترهای جداکننده استفاده کنید و از آن‌ها برای قرار دادن نام متغیرها مانند موارد زیر استفاده کنید:

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

اگرچه Apigee توصیه می‌کند که از نحو جدیدتر curly-brace استفاده کنید، نحو قدیمی‌تر همچنان کار می‌کند.

استفاده از توابع الگوی پیام

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 برای اضافه کردن آن به یک پاسخ پراکسی سفارشی استفاده کنید (یعنی ارسال آن به مشتری).

در اینجا خط مشی Extract Variables آمده است که اطلاعات 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>

متاسفانه مشکلی هست خط مشی Extract Variables کاراکترهای نقل قول فرار را در اطراف بخشی از پیام حذف کرد. این بدان معنی است که پاسخی که به مشتری بازگردانده می شود JSON نامعتبر است. واضح است که این چیزی نیست که شما قصد دارید!

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

برای حل این مشکل، می توانید خط مشی Assign Message را تغییر دهید تا از یک تابع الگوی پیام استفاده کنید که از نقل قول ها در 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>

این مبحث توابع قالب پیام، آرگومان‌ها و خروجی‌های آن‌ها را توضیح می‌دهد. این مبحث فرض می‌کند که شما با قالب‌های پیام و زمینه‌هایی که در آن استفاده می‌شوند آشنا هستید.

توابع هش

یک مقدار هش را محاسبه کنید و نمایش رشته آن هش را برگردانید.

توابع هش هگزادسیمال

یک مقدار هش را محاسبه کنید و نمایش رشته آن هش را به صورت یک عدد هگزادسیمال برگردانید.

نحو

استدلال ها

رشته - توابع Hash یک آرگومان رشته واحد را می گیرند که الگوریتم هش بر اساس آن محاسبه می شود. آرگومان می تواند یک رشته تحت اللفظی یا یک متغیر جریان رشته باشد.

نمونه ها

فراخوانی تابع:

sha256Hex('abc')

نتیجه:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

فراخوانی تابع:

var str = 'abc';
sha256Hex(str)

نتیجه:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

توابع هش Base64

یک مقدار هش را محاسبه کنید و نمایش رشته آن هش را به عنوان یک مقدار کدگذاری شده Base64 برگردانید.

نحو

استدلال ها

رشته - توابع Hash یک آرگومان رشته واحد را می گیرند که الگوریتم هش بر اساس آن محاسبه می شود. آرگومان می تواند یک رشته تحت اللفظی یا یک متغیر جریان رشته باشد.

نمونه ها

فراخوانی تابع:

sha256Base64('abc')

نتیجه:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

فراخوانی تابع:

var str = 'abc';
sha256Base64(str)

نتیجه:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

توابع رشته

انجام عملیات بر روی رشته ها در قالب پیام.

توابع رمزگذاری Base64

رشته ها را با استفاده از طرح رمزگذاری Base64 رمزگذاری و رمزگشایی کنید.

نحو

استدلال ها

رشته - رشته ای برای رمزگذاری یا رمزگشایی. می تواند یک رشته تحت اللفظی یا یک متغیر جریان رشته باشد.

مثال

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

توابع تبدیل مورد

یک رشته را به تمام حروف بزرگ یا کوچک تبدیل کنید.

نحو

استدلال ها

رشته - رشته ای برای تبدیل. می تواند یک رشته تحت اللفظی یا یک متغیر جریان رشته باشد.

مثال

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

استدلال ها

• رشته - یک رشته تحت اللفظی یا متغیر جریان رشته که در آن جایگزین می شود.
• regex - یک عبارت منظم.
• value - مقداری که برای جایگزینی همه تطابقات regex درون رشته است.

نمونه ها

برای مثال های زیر، فرض کنید این متغیرهای جریان وجود دارند:

در اینجا نتایج فراخوانی تابعی که از این متغیرها استفاده می کنند آورده شده است:

تابع First را جایگزین کنید

تنها اولین رخداد مطابقت عبارت منظم مشخص شده را در رشته جایگزین می کند.

نحو

replaceFirst(string,regex,value)

استدلال ها

• رشته - یک رشته تحت اللفظی یا متغیر جریان رشته که در آن جایگزین می شود.
• regex - یک عبارت منظم.
• مقدار - مقدار جایگزینی regex با رشته مطابقت دارد.

توابع فرار کاراکتر و رمزگذاری

توابعی که از کاراکترهای خاص در یک رشته فرار می کنند یا کدگذاری می کنند.

نحو

استدلال ها

رشته - رشته برای فرار. می تواند یک رشته تحت اللفظی یا یک متغیر جریان رشته باشد.

نکات استفاده

XML 1.1 می تواند کاراکترهای کنترلی خاصی را نشان دهد، اما نمی تواند بایت های پوچ یا نقاط کد جانشین Unicode جفت نشده را حتی پس از فرار نمایش دهد. تابع ()escapeXML11 کاراکترهایی را که در محدوده های زیر قرار نمی گیرند حذف می کند:

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

تابع escapeXML11() از کاراکترها در محدوده های زیر فرار می کند:

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

نمونه ها

فرض کنید یک متغیر جریان به نام غذا با این مقدار وجود دارد: "bread" & "butter" . سپس، تابع:

{escapeHTML(food)}

منجر به:

توابع قالب زمان

یک نمایش رشته ای از زمان را که در منطقه زمانی محلی یا UTC قالب بندی شده است، برگردانید.

نحو

استدلال ها

• قالب - رشته فرمت تاریخ/زمان. می تواند یک رشته واقعی یا یک متغیر رشته باشد.
• 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

تابع ژنراتور طولانی تصادفی

یک عدد صحیح طولانی تصادفی را برمی‌گرداند.

نحو

randomLong(args)

استدلال ها

• اگر هیچ آرگومانی مشخص نشده باشد، تابع یک عدد صحیح طولانی تصادفی را برمی‌گرداند که توسط کلاس Java SecureRandom محاسبه شده است.
• اگر یک آرگومان وجود داشته باشد، به عنوان حداقل مقدار محاسبه در نظر گرفته می شود.
• اگر آرگومان دوم وجود داشته باشد، به عنوان حداکثر مقدار محاسبه در نظر گرفته می شود.

مثال

{random()}

نتیجه ای شبیه به این می شود:

5211338197474042880

تولید کننده متن Regex

یک رشته متنی ایجاد کنید که با یک عبارت منظم داده شده مطابقت داشته باشد.

نحو

xeger(regex)

استدلال

regex - یک عبارت منظم.

مثال

این مثال یک رشته هفت رقمی بدون صفر تولید می کند:

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

نتیجه مثال:

9857253

تابع نول ادغام

تابع firstnonnull() مقدار آرگومان سمت چپ و غیر تهی را برمی گرداند.

نحو

firstnonnull(var1,varn)

استدلال

var1 - یک متغیر زمینه.

var _n - یک یا چند متغیر زمینه. می‌توانید آرگومان سمت راست را روی یک رشته تنظیم کنید تا یک مقدار بازگشتی (مقداری که اگر هیچ یک از آرگومان‌های سمت چپ تنظیم نشده باشد، تنظیم می‌شود).

نمونه ها

جدول زیر نحوه استفاده از تابع را نشان می دهد:

الگو	Var1	Var2	Var3	نتیجه
{firstnonnull(var1,var2)}	تنظیم نشده است	foo	N/A	foo
{firstnonnull(var1,var2)}	foo	bar	N/A	foo
{firstnonnull(var1,var2)}	foo	تنظیم نشده است	N/A	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)}	تنظیم نشده است	N/A	N/A	null
{firstnonnull(var1)}	foo	N/A	N/A	foo
{firstnonnull(var1,var2)}	""	bar	N/A	""
{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 Path را به متغیر JSON اعمال می کند.

نحو

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

استدلال ها

• (الزامی) json-path : (رشته) عبارت مسیر JSON.
• (لازم) json-var : (String) یک متغیر جریان یا رشته حاوی JSON.
• (اختیاری) want-array : (string) اگر این پارامتر روی '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']