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

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

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

דוגמה

כשחורגים ממכסת השימוש, מומלץ להחזיר הודעה משמעותית למתקשר. התבנית הזו משמשת בדרך כלל עם כלל שגיאה כדי לספק פלט שנותן למתקשר מידע על חריגה מהמכסה. במדיניות הבאה של הקצאת הודעות, נעשה שימוש בתבניות של הודעות כדי לאכלס באופן דינמי מידע על מכסות בכמה רכיבי 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

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

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

• רכיבי הכותרת מקבלים ערכים של משתני התהליך שצוינו.
• המטען הייעודי (Payload) כולל שילוב של טקסט מילולי ומשתנים (הערך של 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 לפני Cloud release 16.08.17, אי אפשר להשתמש בסוגריים מסולסלים כדי לציין הפניות למשתנים במטענים ייעודיים (payloads) בפורמט JSON. בגרסאות הישנות יותר, היה צריך להשתמש במאפיינים variablePrefix ו-variableSuffix כדי לציין תווים להפרדה, ולהשתמש בהם כדי להקיף שמות של משתנים, כך:

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

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

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

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

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

דוגמה: toLowerCase()‎

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

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

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

Test header: foo

דוגמה: escapeJSON()

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

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

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

זו מדיניות Extract Variables ששולפת את המידע user_message למשתנה שנקרא standard.systemMessage:

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

עכשיו, הנה מדיניות Assign Message תקינה לחלוטין שמוסיפה את המשתנה שחולץ למטען הייעודי (payload) של התגובה (תגובת ה-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>

לצערי, יש בעיה. המדיניות Extract Variables (חילוץ משתנים) הסירה את תווי המירכאות עם התו הבורח סביב חלק מההודעה. המשמעות היא שהתגובה שמוחזרת ללקוח היא JSON לא תקין. ברור שלא לזה התכוונת!

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

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

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

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

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

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

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

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

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

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

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

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

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

תחביר

ארגומנטים

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

דוגמאות

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

sha256Hex('abc')

תוצאה:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

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

var str = 'abc';
sha256Hex(str)

תוצאה:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

פונקציות גיבוב (Hash) של Base64

מחשבת ערך גיבוב (hash) ומחזירה את הייצוג של הגיבוב כמחרוזת בקידוד 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 - המחרוזת שצריך להוסיף לה תווי escape. יכול להיות מחרוזת ליטרל או משתנה זרימה מסוג מחרוזת.

הערות שימוש

‫XML 1.1 יכול לייצג תווי בקרה מסוימים, אבל הוא לא יכול לייצג את בייט האפס או נקודות קוד של Unicode surrogate לא מזווגות, גם אחרי ביצוע escape. הפונקציה escapeXML11()‎ מסירה תווים שלא נכללים בטווחים הבאים:

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

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

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

דוגמאות

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

{escapeHTML(food)}

התוצאה היא:

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

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

תחביר

ארגומנטים

• ‫format – מחרוזת של פורמט תאריך או שעה. יכול להיות מחרוזת מילולית או משתנה מחרוזת.
• ‫str – מחרוזת או משתנה זרימה שמכיל ערך של זמן. הערך יכול להיות בשניות מאז תקופת ה-Epoch או באלפיות השנייה מאז תקופת ה-Epoch עבור 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

כלי ליצירת טקסט באמצעות ביטויים רגולריים

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

תחביר

xeger(regex)

ארגומנט

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

דוגמה

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

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

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

9857253

פונקציית איחוד של ערכי Null

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

תחביר

firstnonnull(var1,varnn>)

ארגומנט

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

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

דוגמאות

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

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

פונקציית XPath

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

תחביר

xpath(xpath_expression,xml_string,[datatype])

ארגומנטים

‫xpath_expression – ביטוי XPath.

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

‫datatype – (אופציונלי) מציין את סוג ההחזרה הרצוי של השאילתה. יכול להיות 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 Path

הפעולה מחילה ביטוי JSON Path על משתנה 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']