قالب های پیام

شما در حال مشاهده اسناد 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 استفاده می شوند پشتیبانی می شوند.

خط‌مشی‌هایی که الگوهای پیام را می‌پذیرند

سیاست عناصر و عناصر فرزند که از الگوهای پیام پشتیبانی می کنند
خط مشی AccessControl <SourceAddress> ، برای ویژگی mask و آدرس IP.
خط مشی AssignMessage عناصر فرزند <Set> : Payload، ContentType، Verb، Version، Path، StatusCode، ReasonPhrase، Headers، QueryParams، FormParams

عناصر فرزند <Add> : Headers، QueryParams، FormParams

عنصر فرزند <AssignVariable> : <Template>

خط مشی ExtensionCallout <Input>
سیاست ExtractVariables <JsonPath>
خط مشی GenerateJWS
بررسی سیاست JWS		 <Payload> (فقط خط مشی GenerateJWS )

<AdditionalHeaders><Claim>

* این عناصر فقط زمانی که type=map از الگوی پیام پشتیبانی می کنند.

ایجاد خط مشی JWT
سیاست JWT را تأیید کنید		 <AdditionalClaims><Claim>

<AdditionalHeaders><Claim>

* این عناصر فقط زمانی که type=map از الگوی پیام پشتیبانی می کنند.

خط مشی LDAP <SearchQuery>
خط مشی MessageLogging <Syslog><Message>

<File><Message>

خط مشی اعتبارسنجی OAS عنصر <OASResource>
خط مشی RaiseFault عناصر <Set> : Payload، ContentType، Verb، Version، Path، StatusCode، ReasonPhrase، Headers، QueryParams، FormParams

عناصر <Add> : Headers، QueryParams، FormParams

سیاست اظهارنامه SAMLA <Template>

* فقط زمانی که امضای خط مشی <GenerateSAMLAssertion> باشد

خط مشی ServiceCallout عناصر <Set> : Payload، ContentType، Verb، Version، Path، StatusCode، ReasonPhrase، /Headers، QueryParams، FormParams

عناصر <Add> : Headers، QueryParams، FormParams

<HTTPTargetConnection>/<URL> : توجه داشته باشید که قسمت اول رشته باید http یا https باشد.

عناصر TargetEndpoint که الگوهای پیام را می پذیرند

عناصر HTTPTargetConnection عناصر کودک که از الگوهای پیام پشتیبانی می کنند
SSInfo فعال، KeyAlias، KeyStore، TrustStore، ClientAuthEnabled، CLRStore
LocalTargetConnection ApiProxy، ProxyEndpoint
مسیر هنگام استفاده از یک عنصر LoadBalancer، عنصر Path فعال است و یک الگوی پیام را می پذیرد.

نحو الگوی پیام

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

از بریس های فرفری برای نشان دادن متغیرها استفاده کنید

نام متغیرها را در پرانتزهای مجعد { } قرار دهید. اگر متغیر وجود نداشته باشد، یک رشته خالی در خروجی برگردانده می شود. با این حال، می‌توانید مقادیر پیش‌فرض را در قالب‌های پیام (مقادی که در صورت حل نشدن متغیر جایگزین می‌شوند) تعیین کنید. به تنظیم مقادیر پیش فرض در الگوهای پیام مراجعه کنید.

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

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

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

توابع هش

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

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

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

نحو

تابع توضیحات
md5Hex(string) یک هش MD5 را محاسبه می کند که به صورت یک عدد هگزادسیمال بیان می شود.
sha1Hex(string) یک هش SHA1 را محاسبه می کند که به صورت یک عدد هگزادسیمال بیان می شود.
sha256Hex(string) یک هش SHA256 را محاسبه می کند که به صورت یک عدد هگزادسیمال بیان می شود.
sha384Hex(string) یک هش SHA384 را محاسبه می کند که به صورت یک عدد هگزادسیمال بیان می شود.
sha512Hex(string) یک هش SHA512 را محاسبه می کند که به صورت یک عدد هگزادسیمال بیان می شود.

استدلال ها

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

نمونه ها

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

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 بیان شده است.

استدلال ها

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

نمونه ها

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

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 را برمی گرداند.

استدلال ها

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

مثال 

<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) یک رشته را به حروف کوچک تبدیل کنید.


استدلال ها

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

مثال 

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

استدلال ها

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

نمونه ها

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

نام متغیر ارزش
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

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

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

نحو 

replaceFirst(string,regex,value)

استدلال ها

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

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

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

نحو

تابع توضیحات
escapeJSON (رشته) بک اسلش-گریز از دو نقل قول.
escapeXML (رشته) براکت های زاویه، آپستروف، دو نقل قول و آمپرسند را با موجودیت های XML مربوطه جایگزین می کند. برای اسناد XML 1.0 استفاده کنید.

escapeXML11 (رشته) مانند escapeXML کار می کند، اما برای موجودیت های XML v1.1. نکات استفاده را در زیر ببینید.
encodeHTML (رشته) آپوستروف، براکت های زاویه ای و آمپرسند را رمزگذاری می کند.

استدلال ها

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

نکات استفاده

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

منجر به:

&quot;bread&quot; &amp; &quot;butter&quot;

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

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

نحو

تابع توضیحات
timeFormat(format,str) تاریخ قالب بندی شده در منطقه زمانی محلی را برمی گرداند.
timeFormatMs(format,str) تاریخ قالب بندی شده در منطقه زمانی محلی را برمی گرداند.
timeFormatUTC(format,str) تاریخ قالب بندی شده در UTC را برمی گرداند.
timeFormatUTCMs(format,str) تاریخ قالب بندی شده در 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']
     ،

    شما در حال مشاهده اسناد 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 استفاده می شوند پشتیبانی می شوند.

    خط‌مشی‌هایی که الگوهای پیام را می‌پذیرند

    سیاست عناصر و عناصر فرزند که از الگوهای پیام پشتیبانی می کنند
    خط مشی AccessControl <SourceAddress> ، برای ویژگی mask و آدرس IP.
    خط مشی AssignMessage عناصر فرزند <Set> : Payload، ContentType، Verb، Version، Path، StatusCode، ReasonPhrase، Headers، QueryParams، FormParams

    عناصر فرزند <Add> : Headers، QueryParams، FormParams

    عنصر فرزند <AssignVariable> : <Template>

    خط مشی ExtensionCallout <Input>
    سیاست ExtractVariables <JsonPath>
    خط مشی GenerateJWS
    بررسی سیاست JWS    		 <Payload> (فقط خط مشی GenerateJWS )

    <AdditionalHeaders><Claim>

    * این عناصر فقط زمانی که type=map از الگوی پیام پشتیبانی می کنند.

    ایجاد خط مشی JWT
    سیاست JWT را تأیید کنید    		 <AdditionalClaims><Claim>

    <AdditionalHeaders><Claim>

    * این عناصر فقط زمانی که type=map از الگوی پیام پشتیبانی می کنند.

    خط مشی LDAP <SearchQuery>
    خط مشی MessageLogging <Syslog><Message>

    <File><Message>

    خط مشی اعتبارسنجی OAS عنصر <OASResource>
    خط مشی RaiseFault عناصر <Set> : Payload، ContentType، Verb، Version، Path، StatusCode، ReasonPhrase، Headers، QueryParams، FormParams

    عناصر <Add> : Headers، QueryParams، FormParams

    سیاست اظهارنامه SAMLA <Template>

    * فقط زمانی که امضای خط مشی <GenerateSAMLAssertion> باشد

    خط مشی ServiceCallout عناصر <Set> : Payload، ContentType، Verb، Version، Path، StatusCode، ReasonPhrase، /Headers، QueryParams، FormParams

    عناصر <Add> : Headers، QueryParams، FormParams

    <HTTPTargetConnection>/<URL> : توجه داشته باشید که قسمت اول رشته باید http یا https باشد.

    عناصر TargetEndpoint که الگوهای پیام را می پذیرند

    عناصر HTTPTargetConnection عناصر کودک که از الگوهای پیام پشتیبانی می کنند
    SSInfo فعال، KeyAlias، KeyStore، TrustStore، ClientAuthEnabled، CLRStore
    LocalTargetConnection ApiProxy، ProxyEndpoint
    مسیر هنگام استفاده از یک عنصر LoadBalancer، عنصر Path فعال است و یک الگوی پیام را می پذیرد.

    نحو الگوی پیام

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

    از بریس های فرفری برای نشان دادن متغیرها استفاده کنید

    نام متغیرها را در پرانتزهای مجعد { } قرار دهید. اگر متغیر وجود نداشته باشد، یک رشته خالی در خروجی برگردانده می شود. با این حال، می‌توانید مقادیر پیش‌فرض را در قالب‌های پیام (مقادی که در صورت حل نشدن متغیر جایگزین می‌شوند) تعیین کنید. به تنظیم مقادیر پیش فرض در الگوهای پیام مراجعه کنید.

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

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

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

    توابع هش

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

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

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

    نحو

    تابع توضیحات
    md5Hex(string) یک هش MD5 را محاسبه می کند که به صورت یک عدد هگزادسیمال بیان می شود.
    sha1Hex(string) یک هش SHA1 را محاسبه می کند که به صورت یک عدد هگزادسیمال بیان می شود.
    sha256Hex(string) یک هش SHA256 را محاسبه می کند که به صورت یک عدد هگزادسیمال بیان می شود.
    sha384Hex(string) یک هش SHA384 را محاسبه می کند که به صورت یک عدد هگزادسیمال بیان می شود.
    sha512Hex(string) یک هش SHA512 را محاسبه می کند که به صورت یک عدد هگزادسیمال بیان می شود.

    استدلال ها

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

    نمونه ها

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

    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 بیان شده است.

    استدلال ها

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

    نمونه ها

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

    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 را برمی گرداند.

    استدلال ها

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

    مثال 

    <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) یک رشته را به حروف کوچک تبدیل کنید.


    استدلال ها

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

    مثال 

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

    استدلال ها

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

    نمونه ها

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

    نام متغیر ارزش
    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

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

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

    نحو 

    replaceFirst(string,regex,value)

    استدلال ها

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

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

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

    نحو

    تابع توضیحات
    escapeJSON (رشته) بک اسلش-گریز از دو نقل قول.
    escapeXML (رشته) براکت های زاویه، آپستروف، دو نقل قول و آمپرسند را با موجودیت های XML مربوطه جایگزین می کند. برای اسناد XML 1.0 استفاده کنید.

    escapeXML11 (رشته) مانند escapeXML کار می کند، اما برای موجودیت های XML v1.1. نکات استفاده را در زیر ببینید.
    encodeHTML (رشته) آپوستروف، براکت های زاویه ای و آمپرسند را رمزگذاری می کند.

    استدلال ها

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

    نکات استفاده

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

    منجر به:

    &quot;bread&quot; &amp; &quot;butter&quot;

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

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

    نحو

    تابع توضیحات
    timeFormat(format,str) تاریخ قالب بندی شده در منطقه زمانی محلی را برمی گرداند.
    timeFormatMs(format,str) تاریخ قالب بندی شده در منطقه زمانی محلی را برمی گرداند.
    timeFormatUTC(format,str) تاریخ قالب بندی شده در UTC را برمی گرداند.
    timeFormatUTCMs(format,str) تاریخ قالب بندی شده در 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']
       ،

      شما در حال مشاهده اسناد 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 استفاده می شوند پشتیبانی می شوند.

      خط‌مشی‌هایی که الگوهای پیام را می‌پذیرند

      سیاست عناصر و عناصر فرزند که از الگوهای پیام پشتیبانی می کنند
      خط مشی AccessControl <SourceAddress> ، برای ویژگی mask و آدرس IP.
      خط مشی AssignMessage عناصر فرزند <Set> : Payload، ContentType، Verb، Version، Path، StatusCode، ReasonPhrase، Headers، QueryParams، FormParams

      عناصر فرزند <Add> : Headers، QueryParams، FormParams

      عنصر فرزند <AssignVariable> : <Template>

      خط مشی ExtensionCallout <Input>
      سیاست ExtractVariables <JsonPath>
      خط مشی GenerateJWS
      بررسی سیاست JWS      		 <Payload> (فقط خط مشی GenerateJWS )

      <AdditionalHeaders><Claim>

      * این عناصر فقط زمانی که type=map از الگوی پیام پشتیبانی می کنند.

      ایجاد خط مشی JWT
      سیاست JWT را تأیید کنید      		 <AdditionalClaims><Claim>

      <AdditionalHeaders><Claim>

      * این عناصر فقط زمانی که type=map از الگوی پیام پشتیبانی می کنند.

      خط مشی LDAP <SearchQuery>
      خط مشی MessageLogging <Syslog><Message>

      <File><Message>

      خط مشی اعتبارسنجی OAS عنصر <OASResource>
      خط مشی RaiseFault عناصر <Set> : Payload، ContentType، Verb، Version، Path، StatusCode، ReasonPhrase، Headers، QueryParams، FormParams

      عناصر <Add> : Headers، QueryParams، FormParams

      سیاست اظهارنامه SAMLA <Template>

      * فقط زمانی که امضای خط مشی <GenerateSAMLAssertion> باشد

      خط مشی ServiceCallout عناصر <Set> : Payload، ContentType، Verb، Version، Path، StatusCode، ReasonPhrase، /Headers، QueryParams، FormParams

      عناصر <Add> : Headers، QueryParams، FormParams

      <HTTPTargetConnection>/<URL> : توجه داشته باشید که قسمت اول رشته باید http یا https باشد.

      عناصر TargetEndpoint که الگوهای پیام را می پذیرند

      عناصر HTTPTargetConnection عناصر کودک که از الگوهای پیام پشتیبانی می کنند
      SSInfo فعال، KeyAlias، KeyStore، TrustStore، ClientAuthEnabled، CLRStore
      LocalTargetConnection ApiProxy، ProxyEndpoint
      مسیر هنگام استفاده از یک عنصر LoadBalancer، عنصر Path فعال است و یک الگوی پیام را می پذیرد.

      نحو الگوی پیام

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

      از بریس های فرفری برای نشان دادن متغیرها استفاده کنید

      نام متغیرها را در پرانتزهای مجعد { } قرار دهید. اگر متغیر وجود نداشته باشد، یک رشته خالی در خروجی برگردانده می شود. با این حال، می‌توانید مقادیر پیش‌فرض را در قالب‌های پیام (مقادی که در صورت حل نشدن متغیر جایگزین می‌شوند) تعیین کنید. به تنظیم مقادیر پیش فرض در الگوهای پیام مراجعه کنید.

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

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

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

      توابع هش

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

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

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

      نحو

      تابع توضیحات
      md5Hex(string) یک هش MD5 را محاسبه می کند که به صورت یک عدد هگزادسیمال بیان می شود.
      sha1Hex(string) یک هش SHA1 را محاسبه می کند که به صورت یک عدد هگزادسیمال بیان می شود.
      sha256Hex(string) یک هش SHA256 را محاسبه می کند که به صورت یک عدد هگزادسیمال بیان می شود.
      sha384Hex(string) یک هش SHA384 را محاسبه می کند که به صورت یک عدد هگزادسیمال بیان می شود.
      sha512Hex(string) یک هش SHA512 را محاسبه می کند که به صورت یک عدد هگزادسیمال بیان می شود.

      استدلال ها

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

      نمونه ها

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

      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 بیان شده است.

      استدلال ها

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

      نمونه ها

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

      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 را برمی گرداند.

      استدلال ها

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

      مثال 

      <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) یک رشته را به حروف کوچک تبدیل کنید.


      استدلال ها

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

      مثال 

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

      استدلال ها

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

      نمونه ها

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

      نام متغیر ارزش
      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

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

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

      نحو 

      replaceFirst(string,regex,value)

      استدلال ها

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

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

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

      نحو

      تابع توضیحات
      escapeJSON (رشته) بک اسلش-گریز از دو نقل قول.
      escapeXML (رشته) براکت های زاویه، آپستروف، دو نقل قول و آمپرسند را با موجودیت های XML مربوطه جایگزین می کند. برای اسناد XML 1.0 استفاده کنید.

      escapeXML11 (رشته) مانند escapeXML کار می کند، اما برای موجودیت های XML v1.1. نکات استفاده را در زیر ببینید.
      encodeHTML (رشته) آپوستروف، براکت های زاویه ای و آمپرسند را رمزگذاری می کند.

      استدلال ها

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

      نکات استفاده

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

      منجر به:

      &quot;bread&quot; &amp; &quot;butter&quot;

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

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

      نحو

      تابع توضیحات
      timeFormat(format,str) تاریخ قالب بندی شده در منطقه زمانی محلی را برمی گرداند.
      timeFormatMs(format,str) تاریخ قالب بندی شده در منطقه زمانی محلی را برمی گرداند.
      timeFormatUTC(format,str) تاریخ قالب بندی شده در UTC را برمی گرداند.
      timeFormatUTCMs(format,str) تاریخ قالب بندی شده در 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']
         ،

        شما در حال مشاهده اسناد 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 استفاده می شوند پشتیبانی می شوند.

        خط‌مشی‌هایی که الگوهای پیام را می‌پذیرند

        سیاست عناصر و عناصر فرزند که از الگوهای پیام پشتیبانی می کنند
        خط مشی AccessControl <SourceAddress> ، برای ویژگی mask و آدرس IP.
        خط مشی AssignMessage عناصر فرزند <Set> : Payload، ContentType، Verb، Version، Path، StatusCode، ReasonPhrase، Headers، QueryParams، FormParams

        عناصر فرزند <Add> : Headers، QueryParams، FormParams

        عنصر فرزند <AssignVariable> : <Template>

        خط مشی ExtensionCallout <Input>
        سیاست ExtractVariables <JsonPath>
        خط مشی GenerateJWS
        بررسی سیاست JWS        		 <Payload> (فقط خط مشی GenerateJWS )

        <AdditionalHeaders><Claim>

        * این عناصر فقط زمانی که type=map از الگوی پیام پشتیبانی می کنند.

        ایجاد خط مشی JWT
        سیاست JWT را تأیید کنید        		 <AdditionalClaims><Claim>

        <AdditionalHeaders><Claim>

        * این عناصر فقط زمانی که type=map از الگوی پیام پشتیبانی می کنند.

        خط مشی LDAP <SearchQuery>
        خط مشی MessageLogging <Syslog><Message>

        <File><Message>

        خط مشی اعتبارسنجی OAS عنصر <OASResource>
        خط مشی RaiseFault عناصر <Set> : Payload، ContentType، Verb، Version، Path، StatusCode، ReasonPhrase، Headers، QueryParams، FormParams

        عناصر <Add> : Headers، QueryParams، FormParams

        سیاست اظهارنامه SAMLA <Template>

        * فقط زمانی که امضای خط مشی <GenerateSAMLAssertion> باشد

        خط مشی ServiceCallout عناصر <Set> : Payload، ContentType، Verb، Version، Path، StatusCode، ReasonPhrase، /Headers، QueryParams، FormParams

        عناصر <Add> : Headers، QueryParams، FormParams

        <HTTPTargetConnection>/<URL> : توجه داشته باشید که قسمت اول رشته باید http یا https باشد.

        عناصر TargetEndpoint که الگوهای پیام را می پذیرند

        عناصر HTTPTargetConnection عناصر کودک که از الگوهای پیام پشتیبانی می کنند
        SSInfo فعال، KeyAlias، KeyStore، TrustStore، ClientAuthEnabled، CLRStore
        LocalTargetConnection ApiProxy، ProxyEndpoint
        مسیر هنگام استفاده از یک عنصر LoadBalancer، عنصر Path فعال است و یک الگوی پیام را می پذیرد.

        نحو الگوی پیام

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

        از بریس های فرفری برای نشان دادن متغیرها استفاده کنید

        نام متغیرها را در پرانتزهای مجعد { } قرار دهید. اگر متغیر وجود نداشته باشد، یک رشته خالی در خروجی برگردانده می شود. با این حال، می‌توانید مقادیر پیش‌فرض را در قالب‌های پیام (مقادی که در صورت حل نشدن متغیر جایگزین می‌شوند) تعیین کنید. به تنظیم مقادیر پیش فرض در الگوهای پیام مراجعه کنید.

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

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

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

        توابع هش

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

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

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

        نحو

        تابع توضیحات
        md5Hex(string) یک هش MD5 را محاسبه می کند که به صورت یک عدد هگزادسیمال بیان می شود.
        sha1Hex(string) یک هش SHA1 را محاسبه می کند که به صورت یک عدد هگزادسیمال بیان می شود.
        sha256Hex(string) یک هش SHA256 را محاسبه می کند که به صورت یک عدد هگزادسیمال بیان می شود.
        sha384Hex(string) یک هش SHA384 را محاسبه می کند که به صورت یک عدد هگزادسیمال بیان می شود.
        sha512Hex(string) یک هش SHA512 را محاسبه می کند که به صورت یک عدد هگزادسیمال بیان می شود.

        استدلال ها

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

        نمونه ها

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

        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 بیان شده است.

        استدلال ها

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

        نمونه ها

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

        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 را برمی گرداند.

        استدلال ها

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

        مثال 

        <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) یک رشته را به حروف کوچک تبدیل کنید.


        استدلال ها

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

        مثال 

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

        استدلال ها

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

        نمونه ها

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

        نام متغیر ارزش
        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

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

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

        نحو 

        replaceFirst(string,regex,value)

        استدلال ها

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

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

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

        نحو

        تابع توضیحات
        escapeJSON (رشته) بک اسلش-گریز از دو نقل قول.
        escapeXML (رشته) براکت های زاویه، آپستروف، دو نقل قول و آمپرسند را با موجودیت های XML مربوطه جایگزین می کند. برای اسناد XML 1.0 استفاده کنید.

        escapeXML11 (رشته) مانند escapeXML کار می کند، اما برای موجودیت های XML v1.1. نکات استفاده را در زیر ببینید.
        encodeHTML (رشته) آپوستروف، براکت های زاویه ای و آمپرسند را رمزگذاری می کند.

        استدلال ها

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

        نکات استفاده

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

        منجر به:

        &quot;bread&quot; &amp; &quot;butter&quot;

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

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

        نحو

        تابع توضیحات
        timeFormat(format,str) تاریخ قالب بندی شده در منطقه زمانی محلی را برمی گرداند.
        timeFormatMs(format,str) تاریخ قالب بندی شده در منطقه زمانی محلی را برمی گرداند.
        timeFormatUTC(format,str) تاریخ قالب بندی شده در UTC را برمی گرداند.
        timeFormatUTCMs(format,str) تاریخ قالب بندی شده در 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']