قالب های پیام

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

این مبحث نحوه استفاده از قالب‌های پیام در پروکسی‌های 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 (داخل آکولاد) در زمان اجرا ارزیابی و در رشته‌ی payload جایگزین می‌شود. بنابراین، برای مثال، اگر user.name=jdoe ، خروجی پیام حاصل در payload به صورت زیر خواهد بود: 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> از قالب‌بندی پیام پشتیبانی می‌کنند:

• سربرگ
• پارامتر پرس و جو
• فرم‌پارام
• بار مفید
• نسخه
• فعل
• مسیر
• کد وضعیت
• عبارت دلیل

مجدداً توجه داشته باشید که متغیرهای جریان در یک الگوی پیام باید در داخل آکولاد قرار گیرند .

وقتی این سیاست اجرا می‌شود:

• عناصر 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 نسخه ۱۶.۰۸.۱۷ ، نمی‌توانستید از آکولاد برای اشاره به متغیرها در داخل JSON payloads استفاده کنید. در آن نسخه‌های قدیمی‌تر، باید از ویژگی‌های variablePrefix و variableSuffix برای مشخص کردن کاراکترهای جداکننده استفاده می‌کردید و از آنها برای قرار دادن نام متغیرها استفاده می‌کردید، مانند این:

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

اگرچه Apigee توصیه می‌کند که از سینتکس جدیدترِ آکولاد استفاده کنید، سینتکس قدیمی‌تر هنوز هم کار می‌کند.

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

Edge مجموعه‌ای از توابع را ارائه می‌دهد که می‌توانید در قالب‌های پیام برای escape کردن، کدگذاری، هش کردن و قالب‌بندی متغیرهای رشته‌ای از آنها استفاده کنید.

توابع الگوی پیام به تفصیل در مرجع توابع الگوی پیام شرح داده شده‌اند.

مثال: 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()

یک مورد استفاده جالب: فرض کنید برنامه backend شما یک پاسخ JSON برمی‌گرداند که شامل کاراکترهای escape معتبر است. برای مثال:

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

سپس، فرض کنید می‌خواهید این پیام را در یک payload سفارشی به فراخواننده کلاینت برگردانید. روش معمول برای انجام این کار، استخراج پیام از payload پاسخ هدف و استفاده از 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 وجود دارد که متغیر استخراج شده را به payload پاسخ (پاسخ پروکسی) اضافه می‌کند:

<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 کاراکترهای نقل قول escape شده را در اطراف بخشی از پیام حذف کرد. این بدان معناست که پاسخی که به کلاینت برگردانده می‌شود JSON نامعتبر است. واضح است که این چیزی نیست که شما در نظر داشتید!

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

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

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

توابع هش

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

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

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

نحو

استدلال‌ها

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

مثال‌ها

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

sha256Hex('abc')

نتیجه:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

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

var str = 'abc';
sha256Hex(str)

نتیجه:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

توابع هش Base64

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

نحو

استدلال‌ها

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

مثال‌ها

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

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 - یک عبارت منظم.
• مقدار - مقداری که قرار است جایگزین تمام تطابق‌های regex درون رشته شود.

مثال‌ها

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

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

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

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

نحو

replaceFirst(string,regex,value)

استدلال‌ها

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

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

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

نحو

استدلال‌ها

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

یادداشت‌های استفاده

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

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

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

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

مثال‌ها

فرض کنید یک متغیر جریان به نام food با این مقدار وجود دارد: "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

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

یک عدد صحیح تصادفی از نوع long integer برمی‌گرداند.

نحو

randomLong(args)

استدلال‌ها

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

مثال

{random()}

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

5211338197474042880

مولد متن منظم (Regex)

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

نحو

xeger(regex)

استدلال

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

مثال

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

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

نتیجه مثال:

9857253

تابع ادغام صفر

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

نحو

firstnonnull(var1,varnn>)

استدلال

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

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

مثال‌ها

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

الگو	وار1	وار۲	وار۳	نتیجه
{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.

نوع داده - (اختیاری) نوع بازگشتی مورد نظر برای پرس و جو را مشخص می‌کند. می‌تواند nodeset، node، number، boolean، string باشد. مقدار پیش‌فرض nodeset است. مقدار پیش‌فرض معمولاً انتخاب درستی است.

مثال ۱

فرض کنید این متغیرهای زمینه‌ای یک رشته 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> را برمی‌گرداند. این مقدار در متغیر context به نام extracted_tag قرار می‌گیرد.

مثال ۲

اگر فقط مقدار گره را می‌خواهید، از تابع text() به صورت زیر استفاده کنید:

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

در نتیجه‌ی این عملیات، متغیر زمینه‌ای extracted_tag ​​برابر با 250397 تنظیم می‌شود.

اگر چندین گره انتخاب شوند، نتیجه xpath() تمام مقادیر انتخاب شده است که با یک کاما به هم متصل شده‌اند.

مثال ۳: فضاهای نام 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)}

مثال ۴: تعیین نوع خروجی دلخواه

پارامتر سوم که اختیاری است و به تابع xpath() ارسال می‌شود، نوع خروجی مورد نظر برای کوئری را مشخص می‌کند.

برخی از کوئری‌های XPath می‌توانند مقادیر عددی یا بولی را برگردانند. برای مثال، count() یک عدد را برمی‌گرداند. این یک کوئری معتبر XPath است:

count(//Record/Fields/Pair)

این پرس‌وجوی معتبر یک مقدار بولی برمی‌گرداند:

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

در این موارد، تابع xpath() را با پارامتر سومی که آن نوع را مشخص می‌کند، فراخوانی کنید:

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

اگر پارامتر سوم شامل علامت دونقطه باشد، به عنوان یک آرگومان فضای نام تفسیر می‌شود. در غیر این صورت، به عنوان نوع بازگشتی مورد نظر در نظر گرفته می‌شود. در این حالت، اگر پارامتر سوم یکی از مقادیر معتبر نباشد (با نادیده گرفتن حروف بزرگ و کوچک)، تابع xpath() به طور پیش‌فرض یک مجموعه گره (nodeset) را برمی‌گرداند.

تابع مسیر در JSON

یک عبارت JSON Path را روی یک متغیر JSON اعمال می‌کند.

نحو

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

استدلال‌ها

• (الزامی) json-path : (رشته) یک عبارت مسیر JSON.
• (الزامی) json-var : (رشته) یک متغیر جریان یا رشته حاوی JSON.
• (اختیاری) want-array : (رشته) اگر این پارامتر روی 'true' تنظیم شود و اگر مجموعه نتیجه یک آرایه باشد، تمام عناصر آرایه بازگردانده می‌شوند. اگر روی هر مقدار دیگری تنظیم شود یا اگر این پارامتر حذف شود، فقط عنصر صفرم یک آرایه مجموعه نتیجه بازگردانده می‌شود. اگر مجموعه نتیجه یک آرایه نباشد، در صورت وجود، این پارامتر سوم نادیده گرفته می‌شود.

مثال ۱

اگر الگوی پیام این باشد:

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' فراخوانی کنید، همانطور که در مثال بعدی نشان داده شده است.

مثال ۲

اگر الگوی پیام این باشد:

{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']