תבניות של הודעות

אתם צופים במסמכי העזרה של Apigee Edge.
כניסה למסמכי העזרה של Apigee X. info

כאן מוסבר איך משתמשים בתבניות הודעות בשרתי proxy ל-API, ומופיעה הפניה לפונקציה.

מהי תבנית של הודעה?

תבנית הודעה מאפשרת לבצע החלפה של מחרוזת משתנה ברכיבים מסוימים של מדיניות ו-TargetEndpoint. התכונה הזו, במקומות שבהם היא נתמכת, מאפשרת לאכלס מחרוזות באופן דינמי כששרת proxy מופעל.

אפשר לכלול כל שילוב של הפניות למשתני תהליך וטקסט מילולי בתבנית של הודעה. שמות של משתני תהליך חייבים להיות מוקפים בסוגריים מסולסלים, וכל טקסט שלא מוקף בסוגריים מסולסלים יופיע כטקסט מילולי.

מידע נוסף זמין במאמר איפה אפשר להשתמש בתבניות של הודעות?

דוגמה

לדוגמה, המדיניות 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>

בדוגמה שלמעלה, הערך של משתנה התהליך user.name (בסוגריים מסולסלים) ייבדק ויוחלי במחרוזת של עומס העבודה בזמן הריצה. לדוגמה, אם user.name=jdoe, הפלט של ההודעה שיתקבל במטען הייעודי (payload) יהיה: 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
• גרסה
• פועל
• נתיב
• StatusCode
• ReasonPhrase

שוב, חשוב לזכור שמשתני תהליך בתבנית של הודעה צריכים להיות מוקפים בסוגריים מסולסלים.

כשהמדיניות הזו פועלת:

• רכיבי הכותרת מקבלים ערכים של משתני התהליך שצוינו.
• המטען הייעודי כולל שילוב של טקסט מילולי ומשתנים (ה-client_id מאוכלס באופן דינמי).
• השדות StatusCode ו-ReasonPhrase כוללים רק טקסט מילולי, אבל אפשר להשתמש בהם גם ליצירת תבניות של הודעות.

דוגמה

בהגדרה של TargetEndpoint בשרת proxy, רכיבי הצאצא של <SSLInfo> תומכים ביצירת תבניות של הודעות. בהתאם לאותו דפוס שבו נעשה שימוש במדיניות, משתני התהליך בסוגריים מסולסלים מוחלפים כשהשרת proxy מופעל.

<TargetEndpoint name="default">
  …
  <HTTPTargetConnection>
    <SSLInfo>
        <Enabled>{myvars.ssl.enabled}</Enabled>
        <ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled>
        <KeyStore>{myvars.ssl.keystore}</KeyStore>
        <KeyAlias>{myvars.ssl.keyAlias}</KeyAlias>
        <TrustStore>{myvars.ssl.trustStore}</TrustStore>
    </SSLInfo>

  </HTTPTargetConnection>
  …
</TargetEndpoint>

איפה אפשר להשתמש בתבניות של הודעות?

תבניות הודעות נתמכות בכמה מדיניות, וגם באלמנטים מסוימים שמשמשים בהגדרה של TargetEndpoint.

כללי מדיניות שמאפשרים להשתמש בתבניות של הודעות

רכיבי TargetEndpoint שמקבלים תבניות של הודעות

תחביר של תבנית הודעה

בקטע הזה מוסבר מהם הכללים שצריך לפעול לפיהם כדי להשתמש בתבניות של הודעות.

שימוש בסוגריים מסולסלים כדי לציין משתנים

צריך להקיף את שמות המשתנים בסוגריים מסולסלים { }. אם המשתנה לא קיים, תוחזר מחרוזת ריקה בפלט. עם זאת, אפשר לציין ערכי ברירת מחדל בתבניות של ההודעות (ערכים שיוחלפו אם המשתנה לא יפתר). מידע נוסף זמין במאמר הגדרת ערכי ברירת מחדל בתבניות של הודעות.

חשוב לזכור שאפשר להקיף את כל מחרוזת תבנית ההודעה במירכאות, אבל זה לא חובה. לדוגמה, שתי תבניות ההודעות הבאות זהות:

<Set>
    <Headers>
        <Header name="x-h1">"Hello {user.name}"</Header>
        <Header name="x-h1">Hello {user.name}</Header>
    </Headers>
</Set>

הגדרת ערכי ברירת מחדל בתבניות של הודעות

אם לא ניתן לפתור משתנה לפי תבנית, Edge מחליף אותו במחרוזת ריקה. עם זאת, אפשר לציין ערך ברירת מחדל באופן הבא:

<Header name="x-h1">Test message. id = {request.header.id:Unknown}</Header>

בדוגמה שלמעלה, אם לא ניתן לפתור את המשתנה request.header.id, הערך שלו יוחלף ב-Unknown. לדוגמה:

Test message. id = Unknown

לא ניתן להשתמש ברווחים בביטויים של פונקציות

אסור להשתמש ברווחים בשום מקום בביטויים של פונקציות בתבניות של הודעות. לדוגמה:

מותר:

{substring(alpha,0,4)}
{createUuid()}
{randomLong(10)}

אסור:

{substring( alpha, 0, 4 )}
{ createUuid( ) }
{randomLong( 10 )}

תחביר מדור קודם למטענים ייעודיים (payloads) של JSON

בגרסאות Edge לפני הגרסה 16.08.17 של Cloud, לא ניתן היה להשתמש בסוגריים מסולסלים כדי לציין הפניות למשתנים בתוך עומסי נתונים של JSON. בגרסאות הקודמות האלה, צריך להשתמש במאפיינים variablePrefix ו-variableSuffix כדי לציין תווים מפרידים, ולהשתמש בהם כדי לעטוף את שמות המשתנים, כך:

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

מומלץ להשתמש בתחביר החדש של סוגריים מסולסלים ב-Apigee, אבל אפשר להמשיך להשתמש בתחביר הישן.

שימוש בפונקציות של תבניות הודעות

ב-Edge יש קבוצה של פונקציות שאפשר להשתמש בהן בתבניות של הודעות כדי לסמן תווים לבריחה (escape), לקודד, לחשב גיבוב ולעצב משתני מחרוזות.

הפונקציות של תבניות ההודעות מתוארות בפירוט במאמר חומר עזר בנושא פונקציות של תבניות הודעות.

דוגמה: toLowerCase()

משתמשים בפונקציה המובנית toLowerCase() כדי להמיר משתנה מחרוזת לאותיות קטנות:

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

אם משתנה התהליך foo.bar יתקבל, התווים שלו יהיו כולם באותיות קטנות. אם foo.bar לא נפתר, ערך ברירת המחדל FOO מוחלף ומומר לתוים קטנים. לדוגמה:

Test header: foo

דוגמה: escapeJSON()‎

הנה תרחיש לדוגמה: נניח שאפליקציית הקצה העורפי מחזירה תגובת JSON שמכילה תווים תקינים של בריחה. לדוגמה:

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

נניח שאתם רוצים להחזיר את ההודעה הזו למבצע הקריאה החוזרת של הלקוח בתוכן מטען מותאם אישית. הדרך הרגילה לעשות זאת היא לחלץ את ההודעה ממטען התגובה של היעד ולהשתמש ב-Assign Message כדי להוסיף אותה לתשובת שרת proxy בהתאמה אישית (כלומר, לשלוח אותה חזרה ללקוח).

זוהי מדיניות החילוץ של המשתנים שמחלצת את המידע של user_message למשתנה שנקרא standard.systemMessage:

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

זוהי מדיניות תקפה לחלוטין להקצאת הודעות שמוסיפה את המשתנה שחולץ לעומס התגובה (תגובת שרת ה-proxy):

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

לצערנו, יש בעיה. המדיניות של חילוץ המשתנים הסירה את תווים האשף של המרכאות סביב חלק מההודעה. פירוש הדבר הוא שהתגובה שהוחזרה ללקוח היא JSON לא תקין. ברור שזה לא מה שרצית.

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

כדי לעקוף את הבעיה הזו, אפשר לשנות את המדיניות 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>

הפונקציה מוסיפה תווים לבריחה (escape) לתוך המירכאות המוטמעות, וכתוצאה מכך נוצרת מחרוזת JSON תקינה, וזה בדיוק מה שרציתם:

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

תבנית הודעה היא תכונה של החלפת מחרוזת דינמית שאפשר להשתמש בה בכללי מדיניות מסוימים ובהגדרות של TargetEndpoint. פונקציות של תבניות הודעות מאפשרות לבצע פעולות מועילות כמו גיבוב, מניפולציה במחרוזות, בריחה מתווים ועוד בתוך תבנית הודעה.

לדוגמה, במדיניות AssignMessage הבאה, הפונקציה toLowerCase() משמשת בתבנית של הודעה:

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

בנושא הזה מתוארות הפונקציות של תבניות ההודעות, הארגומנטים שלהן והפלט שלהן. בנושא הזה נניח שאתם מכירים את תבניות ההודעות ואת ההקשרים שבהם הן משמשות.

פונקציות גיבוב (hash)

חישוב ערך גיבוב והחזרת הייצוג של המחרוזת של הגיבוב.

פונקציות גיבוב (hash) הקסדצימליות

חישוב ערך גיבוב והחזרת הייצוג של המחרוזת של הגיבוב כמספר הקסדצימלי.

תחביר

ארגומנטים

string – פונקציות הגיבוב מקבלות ארגומנט מחרוזת יחיד, שממנו מחושב אלגוריתם הגיבוב. הארגומנט יכול להיות מחרוזת לטינית או משתנה של מחרוזת זרימה.

דוגמאות

קריאה לפונקציה:

sha256Hex('abc')

תוצאה:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

קריאה לפונקציה:

var str = 'abc';
sha256Hex(str)

תוצאה:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

פונקציות גיבוב Base64

חישוב ערך גיבוב והחזרת הייצוג של המחרוזת של הגיבוב הזה כערך בקידוד Base64.

תחביר

ארגומנטים

string – פונקציות הגיבוב מקבלות ארגומנט מחרוזת יחיד, שממנו מחושב אלגוריתם הגיבוב. הארגומנט יכול להיות מחרוזת לטינית או משתנה מחרוזת של זרימת נתונים.

דוגמאות

קריאה לפונקציה:

sha256Base64('abc')

תוצאה:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

קריאה לפונקציה:

var str = 'abc';
sha256Base64(str)

תוצאה:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

פונקציות מחרוזת

ביצוע פעולות על מחרוזות בתוך תבנית הודעה.

פונקציות לקידוד Base64

קידוד ופענוח של מחרוזות באמצעות סכימה של קידוד Base64.

תחביר

ארגומנטים

string – המחרוזת שרוצים לקודד או לפענח. יכול להיות מחרוזת לטינית או משתנה של מחרוזת זרימה.

דוגמה

<AssignMessage name="AM-Set-Custom-Response">
    <AssignTo createNew="false" type="response"/>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <Set>
       <Headers>
         <Header name="x-h1">Hello, {decodeBase64('d29ybGQK')}</Header>
       </Headers>
    </Set>
</AssignMessage>

פונקציות של המרת מקרים

המרת מחרוזת לאותיות רישיות או לאותיות קטנות בלבד.

תחביר

ארגומנטים

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 – (אופציונלי) האינדקס הסופי במחרוזת. אם לא מציינים ערך, הערך של אינדקס הסיום הוא סוף המחרוזת.

דוגמאות

בדוגמאות הבאות, נניח שהמשתנים הבאים קיימים בתהליך:

אלה התוצאות של קריאות הפונקציה שמשתמשות במשתנים האלה:

פונקציית החלפת הכול

הפונקציה מחילה ביטוי רגולרי על מחרוזת, ובמקרים של התאמה, מחליפה את ההתאמה בערך חלופי.

תחביר

replaceAll(string,regex,value)

ארגומנטים

• string – מחרוזת ליסטרית או משתנה מחרוזת זרימה שבהם מבצעים החלפות.
• regex – ביטוי רגולרי.
• value – הערך שבעזרתו מחליפים את כל ההתאמות לביטוי הרגולרי במחרוזת.

דוגמאות

בדוגמאות הבאות, נניח שהמשתנים הבאים קיימים בתהליך:

אלה התוצאות של קריאות הפונקציה שמשתמשות במשתנים האלה:

פונקציית Replace First

החלפה של המופע הראשון בלבד של ההתאמה לביטוי הרגולרי שצוין במחרוזת.

תחביר

replaceFirst(string,regex,value)

ארגומנטים

• string – מחרוזת ליסטרית או משתנה מחרוזת זרימה שבהם מבצעים החלפות.
• regex – ביטוי רגולרי.
• value – הערך שמשמש להחלפת התאמות של ביטוי רגולרי במחרוזת.

פונקציות בריחה (escape) וקידוד של תווים

פונקציות שמוסיפות תו בריחה (escape) או מקודדות תווים מיוחדים במחרוזת.

תחביר

ארגומנטים

string – המחרוזת שרוצים להימלט ממנה. יכול להיות מחרוזת לטינית או משתנה של מחרוזת זרימה.

הערות לגבי שימוש

ב-XML 1.1 אפשר לייצג תווי בקרה מסוימים, אבל אי אפשר לייצג את הבייט האפס או נקודות קוד של סמלי Unicode חלופיים לא מותאמים, גם אחרי הוספת תווים להימלטות. הפונקציה escapeXML11() מסירה תווים שלא מתאימים לטווח הבא:

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

הפונקציה escapeXML11() מוסיפה תו בריחה (escape) לתווים בטווח הבא:

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

דוגמאות

נניח שמשתנה תהליך שנקרא food קיים עם הערך הזה: "bread" & "butter". לאחר מכן, הפונקציה:

{escapeHTML(food)}

התוצאה:

פונקציות של פורמט זמן

הפונקציה מחזירה ייצוג מחרוזת של השעה, בפורמט של אזור הזמן המקומי או של שעון UTC.

תחביר

ארגומנטים

• format – מחרוזת של פורמט תאריך/שעה. יכול להיות מחרוזת לטינית או משתנה מחרוזת.
• str – מחרוזת או משתנה מחרוזת של זרימה שמכיל ערך זמן. הערך יכול להיות בשניות מאז תחילת המילניום או באלפיות שנייה מאז תחילת המילניום עבור timeFormatMs.

דוגמאות

נניח את הערכים הבאים ונניח שהשעון המקומי הוא שעון החוף המערבי:

• epoch_time_ms = 1494390266000
• epoch_time = 1494390266
• fmt1 = yyyy-MM-dd
• fmt2 = yyyy-MM-dd HH-mm-ss
• fmt3 = yyyyMMddHHmmss

הפונקציות מחזירות את התוצאות הבאות:

פונקציה	פלט
timeFormatMs(fmt1,epoch_time_ms)	2017-05-09
timeFormat(fmt1,epoch_time)	2017-05-09
timeFormat(fmt2,epoch_time)	2017-05-09 21:24:26
timeFormat(fmt3,epoch_time)	20170509212426
timeFormatUTC(fmt1,epoch_time)	2017-05-10
timeFormatUTC(fmt2,epoch_time)	2017-05-10 04:24:26
timeFormatUTC(fmt3,epoch_time)	20170510042426

פונקציות חישוב של HMAC

פונקציות החישוב של HMAC מספקות חלופה לשימוש במדיניות HMAC כדי לחשב HMAC. הפונקציות האלה שימושיות לביצוע חישוב HMAC ברצף, למשל כשהפלט של HMAC אחד משמש כמפתח ל-HMAC שני.

תחביר

תפקיד	תיאור
hmacSha224(key,valueToSign[,keyencoding[,outputencoding]])	חישוב HMAC באמצעות פונקציית הגיבוב SHA-224.
hmacSha256(key,valueToSign[,keyencoding[,outputencoding]])	קידוד HMAC באמצעות פונקציית הגיבוב SHA-256.
hmacSha384(key,valueToSign[,keyencoding[,outputencoding]])	קידוד של HMAC באמצעות פונקציית הגיבוב SHA-384.
hmacSha512(key,valueToSign[,keyencoding[,outputencoding]])	קידוד של HMAC באמצעות פונקציית הגיבוב SHA-512.
hmacMd5(key,valueToSign[,keyencoding[,outputencoding]])	הפונקציה מקודדת HMAC באמצעות פונקציית הגיבוב MD5.
hmacSha1(key, valueToSign [,keyencoding[,outputencoding]])	קידוד של HMAC באמצעות אלגוריתם ההצפנה SHA-1.

ארגומנטים

• key – (חובה) מציין את המפתח הסודי, שמקודד כמחרוזת, המשמש לחישוב ה-HMAC.
• valueToSign – (חובה) מציין את ההודעה שרוצים לחתום עליה. הוא צריך להיות מחרוזת.
• keyencoding – (אופציונלי) מחרוזת המפתח הסודי תקודד לפי הקידוד שצוין. הערכים התקפים: hex, base16, base64, utf-8. ברירת המחדל: utf-8
• outputencoding – (אופציונלי) מציין את אלגוריתם הקידוד שבו יש להשתמש בפלט. הערכים התקפים: hex, ‏ base16, ‏ base64. הערכים לא תלויי רישיות. הערכים hex ו-base16 הם מונחים נרדפים. ברירת המחדל: base64

דוגמאות

בדוגמה הזו נעשה שימוש במדיניות AssignMessage כדי לחשב HMAC-256 ולהקצות אותו למשתנה תהליך:

<AssignMessage name='AM-HMAC-1'>
  <AssignVariable>
    <Name>valueToSign</Name>
    <Template>{request.header.apikey}.{request.header.date}</Template>
  </AssignVariable>
  <AssignVariable>
    <Name>hmac_value</Name>
    <Template>{hmacSha256(private.secretkey,valueToSign)}</Template>
  </AssignVariable>
</AssignMessage>

הדוגמה הזו ממחישה איך ליצור HMAC מדורג שאפשר להשתמש בו בתהליך החתימה של 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

פונקציית Random Long Generator

הפונקציה מחזירה מספר שלם ארוך אקראי.

תחביר

randomLong(args)

ארגומנטים

• אם לא מציינים ארגומנטים, הפונקציה מחזירה מספר שלם ארוך אקראי, כפי שמחושב על ידי הכיתה Java SecureRandom.
• אם יש ארגומנט אחד, הוא נחשב לערך המינימלי של החישוב.
• אם קיים ארגומנטים שני, הוא מטופל כערך המקסימלי של החישוב.

דוגמה

{random()}

תיצור משהו כזה:

5211338197474042880

מחולל טקסטים של ביטוי רגולרי (regex)

יצירת מחרוזת טקסט שתואמת לביטוי רגולרי נתון.

תחביר

xeger(regex)

ארגומנט

regex – ביטוי רגולרי.

דוגמה

בדוגמה הזו נוצרת מחרוזת של שבע ספרות ללא אפסים:

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

תוצאה לדוגמה:

9857253

פונקציית coalescing של Null

הפונקציה firstnonnull() מחזירה את הערך של הארגומנט הימני ביותר שאינו null.

תחביר

firstnonnull(var1,varn)

ארגומנט

var1 – משתנה הקשר.

var_n – משתנה הקשר אחד או יותר. אפשר להגדיר את הארגומנט הימני ביותר למחרוזת כדי לספק ערך חלופי (ערך שיוגדר אם אף אחד מהארגומנטים שבצד ימין לא יוגדר).

דוגמאות

בטבלה הבאה מוסבר איך משתמשים בפונקציה:

תבנית	Var1	Var2	Var3	תוצאה
{firstnonnull(var1,var2)}	לא מוגדר	foo	לא רלוונטי	foo
{firstnonnull(var1,var2)}	foo	bar	לא רלוונטי	foo
{firstnonnull(var1,var2)}	foo	לא מוגדר	לא רלוונטי	foo
{firstnonnull(var1,var2,var3)}	foo	bar	baz	foo
{firstnonnull(var1,var2,var3)}	לא מוגדר	bar	baz	bar
{firstnonnull(var1,var2,var3)}	לא מוגדר	לא מוגדר	baz	baz
{firstnonnull(var1,var2,var3)}	לא מוגדר	לא מוגדר	לא מוגדר	null
{firstnonnull(var1)}	לא מוגדר	לא רלוונטי	לא רלוונטי	null
{firstnonnull(var1)}	foo	לא רלוונטי	לא רלוונטי	foo
{firstnonnull(var1,var2)}	""	bar	לא רלוונטי	""
{firstnonnull(var1,var2,'fallback value')}	null	null	fallback value	fallback value

פונקציית XPath

החלת ביטוי XPath על משתנה XML.

תחביר

xpath(xpath_expression,xml_string,[datatype])

ארגומנטים

xpath_expression – ביטוי XPath.

xml_string – משתנה תהליך או מחרוזת שמכילה XML.

datatype – (אופציונלי) מציין את סוג ההחזרה הרצוי של השאילתה. הוא יכול להיות nodeset, ‏ node, ‏ number, ‏ boolean, ‏ string. ברירת המחדל היא 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 על משתנה JSON.

תחביר

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

ארגומנטים

• (חובה) json-path: (מחרוזת) ביטוי נתיב JSON.
• (חובה) json-var: (מחרוזת) משתנה תהליך או מחרוזת שמכילה JSON.
• (אופציונלי) want-array: (מחרוזת) אם הפרמטר הזה מוגדר כ-'true' ואם קבוצת התוצאות היא מערך, כל אלמנטים המערך יחזרו. אם מגדירים ערך אחר או אם משמיטים את הפרמטר הזה, המערכת מחזירה רק את הרכיב האפס במערך של קבוצת התוצאות. אם קבוצת התוצאות היא לא מערך, הפרמטר השלישי הזה, אם הוא קיים, יתעלם.

דוגמה 1

אם זו תבנית ההודעה:

The address is {jsonPath($.results[?(@.name == 'Mae West')].address.line1,the_json_variable)}

ו-the_json_variable מכיל:

{
  "results" : [
    {
      "address" : {
        "line1" : "18250 142ND AV NE",
        "city" : "Woodinville",
        "state" : "Washington",
        "zip" : "98072"
      },
      "name" : "Fred Meyer"
    },
    {
      "address" : {
        "line1" : "1060 West Addison Street",
        "city" : "Chicago",
        "state" : "Illinois",
        "zip" : "60613"
      },
      "name" : "Mae West"
    }
  ]
} 

התוצאה של הפונקציה היא:

The address is 1060 West Addison Street

שימו לב שבמקרה הזה, קבוצת התוצאות היא רכיב יחיד (לא מערך של רכיבים). אם קבוצת התוצאות היא מערך, רק הרכיב האפס של המערך יוחזר. כדי להחזיר את המערך המלא, צריך לבצע קריאה לפונקציה עם 'true' כפרמטר השלישי, כפי שמתואר בדוגמה הבאה.

דוגמה 2

אם זו תבנית ההודעה:

{jsonPath($.config.quota[?(@.operation=='ManageOrder')].appname,the_json_variable,'true')}

ו-the_json_variable מכיל:

{
  "results" : [
     {
      "config": {
        "quota": [
          {
            "appname": "A",
            "operation": "ManageOrder",
            "value": "900"
          },
          {
            "appname": "B",
            "operation": "ManageOrder",
            "value": "1000"
          },
          {
            "appname": "B",
            "operation": "SubmitOrder",
            "value": "800"
          }
        ]
      }
    }
  ]
} 

התוצאה של הפונקציה היא:

['A','B']