الگوهای پیام

درحال مشاهده اسناد 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 (در آکولاد) در زمان اجرا ارزیابی و در رشته بار داده جای‌گذاری خواهد شد. بنابراین، برای مثال، اگر 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>

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

الگوهای پیام در چندین خط‌مشی و همچنین عناصر خاصی که در پیکربندی 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 استفاده کنید. در آن نسخه‌های قدیمی‌تر، برای مشخص کردن نویسه‌های جداکننده باید از مشخصه‌های 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."
}

سپس، فرض کنیم می‌خواهید این پیام را در یک بار سفارشی به تماس‌گیرنده مشتری برگردانید. روش معمول برای انجام این کار استخراج پیام از بار پاسخ هدف و استفاده از «اختصاص پیام» برای افزودن آن به پاسخ کارگزار نیابتی سفارشی (یعنی ارسال آن به کارخواه) است.

در اینجا خط‌مشی «استخراج متغیرها» را می‌بینید که اطلاعات user_message را در متغیری به‌نام standard.systemMessage استخراج می‌کند:

<ExtractVariables name="EV-BackendErrorResponse">
    <DisplayName>EV-BackendErrorResponse</DisplayName>
    <JSONPayload>
        <Variable name="standard.systemMessage">
            <JSONPath>$.user_message</JSONPath>
        </Variable>
    </JSONPayload>
</ExtractVariables>

اکنون، در اینجا یک خط‌مشی «تخصیص پیام» کاملاً معتبر وجود دارد که متغیر استخراج‌شده را به بار پاسخ (پاسخ پراکسی) اضافه می‌کند:

<AssignMessage name="AM-SetStandardFaultResponse">
    <DisplayName>AM-SetStandardFaultResponse</DisplayName>
    <Set>
        <Payload contentType="application/json">
           {
              "systemMessage": "{standard.systemMessage}"
           }
        </Payload>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

متأسفانه مشکلی وجود دارد. خط‌مشی «استخراج متغیرها» نویسه‌های نقل‌قول گریزدار را در اطراف بخشی از پیام برداشت. این یعنی پاسخی که به کارخواه برگردانده شده است JSON نامعتبر است. این قطعاً چیزی نیست که شما درنظر داشتید!

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

برای دور زدن این مشکل، می‌توانید خط‌مشی «اختصاص پیام» را تغییر دهید تا از تابع الگوی پیام استفاده کند که نقل‌قول‌های درون JSON را برای شما فرار می‌کند. این تابع، escapeJSON()، هرگونه نقل‌قول یا نویسه‌های ویژه دیگری را که در یک عبارت JSON رخ می‌دهد، گریزداده می‌کند:

<AssignMessage name="AM-SetStandardFaultResponse">
    <DisplayName>AM-SetStandardFaultResponse</DisplayName>
    <Set>
        <Payload contentType="application/json">
           {
              "systemMessage": "{escapeJSON(standard.systemMessage)}"
           }
        </Payload>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

این تابع از نقل‌قول‌های جاسازی‌شده گریز می‌کند و درنتیجه JSON معتبری ایجاد می‌کند که دقیقاً همان چیزی است که می‌خواستید:

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

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

برای مثال، در خط‌مشی AssignMessage زیر، از تابع toLowerCase() در الگوی پیام استفاده شده است:

<AssignMessage name="AM-Set-Custom-Response">
    <AssignTo createNew="false" type="response"/>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <Set>
       <Headers>
         <Header name="x-h1">Test header: {Hello, toLowerCase(user.name)}</Header>
       </Headers>
    </Set>
</AssignMessage>

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

توابع درهم‌سازی

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

توابع درهم‌سازی شانزده‌شانزدهی

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

نحو

آرگومان‌ها

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

مثال‌ها

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

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

مثال‌ها

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

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

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

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

نحو

replaceFirst(string,regex,value)

آرگومان‌ها

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

توابع کدبندی و فرار از نویسه

کارکردهایی که نویسه‌های خاص را در یک رشته فرار یا کدبندی می‌کنند.

نحو

آرگومان‌ها

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

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

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

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

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

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

مثال‌ها

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

{escapeHTML(food)}

نتایج در:

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

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

نحو

آرگومان‌ها

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

مثال‌ها

این مثال از خط‌مشی «تخصیص پیام» برای محاسبه 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

مولد نوشتار عبارت باقاعده

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

نحو

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 - (اختیاری) نوع برگشتی موردنظر برای پُرسمان را مشخص می‌کند. می‌تواند مجموعه گره، گره، عدد، بولی، رشته باشد. به‌طور پیش‌فرض روی مجموعه گره‌ها تنظیم می‌شود. پیش‌فرض معمولاً انتخاب درستی است.

مثال ۱

فرض کنید این متغیرهای زمینه‌ای رشته XML و عبارت XPath را تعریف می‌کنند:

xml = "<tag><tagid>250397</tagid><readerid>1</readerid><rssi>74</rssi><date>2019/06/15</date></tag>"
xpath = "/tag/tagid"

و تابع xpath() در خط‌مشی «تخصیص پیام» به‌صورت زیر استفاده می‌شود:

<AssignMessage>
  <AssignVariable>
    <Name>extracted_tag</Name>
    <Template>{xpath(xpath,xml)}</Template>
  </AssignVariable>
</AssignMessage><

این تابع مقدار <tagid>250397</tagid> را برمی‌گرداند. این مقدار در متغیر زمینه‌ای به‌نام 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>

برای فضای نام‌های اضافی، می‌توانید حداکثر ۱۰ پارامتر اضافی به تابع 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() به‌طور پیش‌فرض مجموعه گره‌ها را برمی‌گرداند.

تابع «مسیر JSON»

عبارت «مسیر JSON» را روی متغیر 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']