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

מוצג המסמך של Apigee Edge.
עוברים אל מסמכי תיעוד של Apigee X. מידע

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

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

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

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

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

דוגמה

לדוגמה, המדיניות של הקצאת הודעה מאפשרת להשתמש בתבנית הודעה בתוך הרכיב <Payload>:

<AssignMessage name="set-dynamic-content">
  <AssignTo createNew="false" type="response"></AssignTo>
  <Set>
    <Payload contentType="application/json">
      {"name":"Alert", "message":"You entered an invalid username: {user.name}"}
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

בדוגמה שלמעלה, הערך של משתנה הזרימה user.name (בסוגריים מסולסלים) יהיה מוערך ומוחלף במחרוזת המטען הייעודי (payload) בזמן הריצה. לדוגמה, אם user.name=jdoe, פלט ההודעה שתתקבל במטען הייעודי (Payload) יהיה: You entered an invalid username: jdoe. אם אי אפשר לפענח את המשתנה, נוצר מחרוזת ריקה.

דוגמה

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

<AssignMessage name='AM-QuotaViolationMessage'>
  <Description>message for quota exceeded</Description>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <Set>
    <Headers>
      <Header name='X-Quota-Reset'>{ratelimit.Quota-1.expiry.time}</Header>
      <Header name='X-Quota-Allowed'>{ratelimit.Quota-1.allowed.count}</Header>
      <Header name='X-Quota-Available'>{ratelimit.Quota-1.available.count}</Header>
    </Headers>
    <Payload contentType='application/json'>{
  "error" : {
    "message" : "you have exceeded your quota",
    "clientId" : "{request.queryparam.apikey}"
  }
}
    </Payload>
    <StatusCode>429</StatusCode>
    <ReasonPhrase>Quota Exceeded</ReasonPhrase>
  </Set>
</AssignMessage>

במדיניות AssignMessage, הרכיבים הבאים של <Set> יצירת תבניות הודעה לתמיכה ברכיב:

• שם
• QueryParam
• FormParam
• PayLoad
• גרסה
• פועל
• נתיב
• StatusCode
• ReasonPhrase

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

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

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

דוגמה

בהגדרה של נקודת קצה (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>

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

תבניות של הודעות נתמכות בכמה כללי מדיניות, וגם ברכיבים מסוימים שנעשה בהם שימוש בהגדרות של יעד הקצה (endpoint).

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

מדיניות	רכיבים ורכיבי צאצא שתומכים בתבניות של הודעות
מדיניות בקרת גישה	<SourceAddress>, עבור המאפיין mask וגם כתובת IP.
המדיניות של AssignMessage	<Set> רכיבי צאצא: Payload, ContentType, Verb, גרסה, Path, StatusCode, ReasonReason, Headers, QueryParams, FormParams <Add> רכיבי צאצא: Headers, QueryParams, FormParams <AssignVariable> רכיב צאצא: <Template>
המדיניות בנושא תוספי יתרונות מרכזיים	<Input>
המדיניות בנושא exportVariables	<JsonPath>
יצירת מדיניות מסוג GenerateJWS אימות המדיניות JWS	<Payload> (מדיניות GenerateJWS בלבד) <AdditionalHeaders><Claim> * הרכיבים האלה תומכים בתבניות הודעות רק כאשר type=map.
מדיניות GenerateJWT אימות המדיניות JWT	<AdditionalClaims><Claim> <AdditionalHeaders><Claim> * הרכיבים האלה תומכים בתבניות הודעות רק כאשר type=map.
מדיניות LDAP	<SearchQuery>
המדיניות של MessageLogging	<Syslog><Message> <File><Message>
המדיניות בנושא OAS Validation	רכיב <OASResource>
המדיניות של UploadFault	רכיבי <Set>: Payload, ContentType, Verb, גרסה, Path, StatusCode, ReasonPhrase, Headers, QueryParams, FormParams רכיבי <Add>: Headers, QueryParams, FormParams
מדיניות SAMLAssertion	<Template> * רק כשהחתימה של המדיניות היא <GenerateSAMLAssertion>
המדיניות בנושא ServiceCallout	רכיבי <Set>: Payload, ContentType, Verb, גרסה, Path, StatusCode, ReasonReason, /Headers, QueryParams, FormParams רכיבי <Add>: Headers, QueryParams, FormParams <HTTPTargetConnection>/<URL>: חשוב לשים לב שהחלק הראשון של המחרוזת חייב להיות http או https.

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

רכיבי HTTPTargetConnection	אלמנטים של ילדים שתומכים בתבניות של הודעות
SSLInfo	מופעל, KeyAlias, KeyStore, TrustStore, ClientAuthEnabled, CLRStore
LocalTargetConnection	ApiProxy, ProxyEndpoint
נתיב	לא רלוונטי

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

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

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

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

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

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

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

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

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

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

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

דוגמה: 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 שמכילה תווי Escape חוקיים. לדוגמה:

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

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

לפניכם מדיניות 'הקצאת הודעות' שמוסיפה את המשתנה שחולץ למטען הייעודי (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>

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

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

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

לדוגמה, במדיניות 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) ומחזירים את ייצוג המחרוזת של אותו גיבוב.

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

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

תחביר

תפקיד	תיאור
md5Hex(string)	הפונקציה מחשבת גיבוב MD5 שמבוטא כמספר הקסדצימלי.
sha1Hex(string)	הפונקציה מחשבת גיבוב SHA1 שמבוטא כמספר הקסדצימלי.
sha256Hex(string)	הפונקציה מחשבת גיבוב SHA256 שמבוטא כמספר הקסדצימלי.
sha384Hex(string)	הפונקציה מחשבת גיבוב SHA384 שמבוטא כמספר הקסדצימלי.
sha512Hex(string)	הפונקציה מחשבת גיבוב SHA512 שמבוטא כמספר הקסדצימלי.

ארגומנטים

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

דוגמאות

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

sha256Hex('abc')

תוצאה:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

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

var str = 'abc';
sha256Hex(str)

תוצאה:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

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

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

תחביר

תפקיד	תיאור
md5Base64(string)	הפונקציה מחשבת גיבוב MD5 שמבוטא כערך בקידוד Base64.
sha1Base64(string)	הפונקציה מחשבת גיבוב SHA1 שמבוטא כערך בקידוד Base64.
sha256Base64(string)	הפונקציה מחשבת גיבוב SHA256 שמבוטא כערך בקידוד Base64.
sha384Base64(string)	הפונקציה מחשבת גיבוב SHA384 שמבוטא כערך בקידוד Base64.
sha512Base64(string)	הפונקציה מחשבת גיבוב SHA512 שמבוטא כערך בקידוד Base64.

ארגומנטים

string – פונקציות הגיבוב (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.

ארגומנטים

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>

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

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

תחביר

תפקיד	תיאור
toUpperCase(string)	המרת מחרוזת לאותיות רישיות.
toLowerCase(string)	ממירים מחרוזת לאותיות קטנות.

ארגומנטים

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)

ארגומנטים

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

דוגמאות

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

שם המשתנה	ערך
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

החלפת הפונקציה הראשונה

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

תחביר

replaceFirst(string,regex,value)

ארגומנטים

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

פונקציות Escape וקידוד של תווים

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

תחביר

תפקיד	תיאור
escapeJSON(string)	לוכסן הפוך בתווי בריחה (escape) במירכאות כפולות.
escapeXML(string)	מחליפה סוגריים זוויתיים, גרש, מירכאות כפולות וסימני אמפרסנד בישויות ה-XML המתאימות. לשימוש במסמכי XML 1.0.
escapeXML11(string)	פועל באותו אופן כמו escapeXML, אבל בישויות XML v1.1. ראו 'הערות לשימוש' שבהמשך.
encodeHTML(string)	הפונקציה מקודדת גרש, סוגריים זוויתיים ואמפרסנד.

ארגומנטים

string - המחרוזת שיש לסמן בתו בריחה (escape). הוא יכול להיות מחרוזת מילולית או משתנה של זרימת מחרוזת.

הערות שימוש

XML 1.1 יכול לייצג תווי בקרה מסוימים, אבל הוא לא יכול לייצג בייט ריק או נקודות קוד מוחלט של Unicode ללא התאמה, גם לאחר 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)}

התוצאה:

"bread" & "butter"

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

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

תחביר

תפקיד	תיאור
timeFormat(format,str)	הפונקציה מחזירה את התאריך בפורמט של אזור הזמן המקומי.
timeFormatMs(format,str)	הפונקציה מחזירה את התאריך בפורמט של אזור הזמן המקומי.
timeFormatUTC(format,str)	הפונקציה מחזירה את התאריך בפורמט UTC.
timeFormatUTCMs(format,str)	הפונקציה מחזירה את התאריך בפורמט UTC.

ארגומנטים

• format – מחרוזת בפורמט של תאריך/שעה. הוא יכול להיות מחרוזת מילולית או משתנה של מחרוזת.
• str – משתנה זרימה של מחרוזת או מחרוזת שמכילים ערך זמן. הערך יכול להיות בשניות-החל מ-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 באמצעות פונקציית הגיבוב (hash) SHA-224.
hmacSha256(key,valueToSign[,keyencoding[,outputencoding]])	הקוד מקודד HMAC באמצעות פונקציית הגיבוב (hash) SHA-256.
hmacSha384(key,valueToSign[,keyencoding[,outputencoding]])	הפונקציה מקודדת HMAC באמצעות פונקציית הגיבוב (hash) SHA-384.
hmacSha512(key,valueToSign[,keyencoding[,outputencoding]])	הקוד מקודד HMAC באמצעות פונקציית הגיבוב (hash) 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

פונקציית גנרטור ארוך אקראי

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

תחביר

randomLong(args)

ארגומנטים

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

דוגמה

{random()}

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

5211338197474042880

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

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

תחביר

xeger(regex)

ארגומנט

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

דוגמה

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

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

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

9857253

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

דוגמה 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: (מחרוזת) משתנה זרימה או מחרוזת שמכילה 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']