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

כרגע מוצג התיעוד של 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 ו-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.

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

מדיניות רכיבים ורכיבי צאצא שתומכים בתבניות של הודעות
מדיניות בקרת גישה <SourceAddress>, למאפיין mask ולכתובת ה-IP.
המדיניות של AssignedMessage רכיבי צאצא של <Set>: Payload, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, Headers, QueryParams, FormParams

רכיבי צאצא של <Add>: Headers, QueryParams, FormParams

<AssignVariable> רכיב צאצא: <Template>

המדיניות בנושא תוספי יתרונות מרכזיים <Input>
המדיניות בנושא חילוץ משתנים <JsonPath>
המדיניות של GenerateJWS
המדיניות בנושא אימותJWS
<Payload> (מדיניות GenerateJWS בלבד)

<AdditionalHeaders><Claim>

* הרכיבים האלה תומכים בתבנית הודעה רק כאשר type=map.

מדיניות GenerateJWT
המדיניות בנושא אימותJWT
<AdditionalClaims><Claim>

<AdditionalHeaders><Claim>

* הרכיבים האלה תומכים בתבנית הודעה רק כאשר type=map.

מדיניות LDAP <SearchQuery>
המדיניות בנושא MessageLogging <Syslog><Message>

<File><Message>

המדיניות בנושא OASValidation רכיב <OASResource>
מדיניות RaiseFault רכיבי <Set>: Payload, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, כותרות, QueryParams, FormParams

רכיבי <Add>: Headers, QueryParams, FormParams

מדיניות SAMLAssertion <Template>

* רק אם חתימת המדיניות היא <GenerateSAMLAssertion>

המדיניות בנושא יתרונות מרכזיים של שירות רכיבי <Set>: Payload, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, /Headers, QueryParams, FormParams

רכיבי <Add>: Headers, QueryParams, FormParams

<HTTPTargetConnection>/<URL>: שימו לב שהחלק הראשון של המחרוזת חייב להיות http או https.

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

רכיבי HTTPTargetConnection רכיבי צאצא שתומכים בתבניות של הודעות
SSLInfo Enabled, 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 לפני גרסה 16.08.17 של Cloud, אפשר לא להשתמש בסוגריים מסולסלים כדי לציין הפניות משתנה במטענים ייעודיים (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."
}

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

לדוגמה, במדיניות הבאה של 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) הקסדצימליות

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

תחביר

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

ארגומנטים

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

דוגמאות

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

sha256Hex('abc')

תוצאה:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

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

var str = 'abc';
sha256Hex(str)

תוצאה:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

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

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

תחביר

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

ארגומנטים

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

דוגמאות

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

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

החלפת הפונקציה All all

מחילה ביטוי רגולרי על מחרוזת ולכל התאמה, מחליפה את ההתאמה בערך חלופי.

תחביר

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 - הערך שיחליף התאמות לביטוי רגולרי (regex) בתוך המחרוזת.

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

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

תחביר

תפקיד תיאור
EscapeJSON(string) לוכסן הפוך-מסמן מירכאות כפולות.
EscapeXML(string) מחליף סוגריים זוויתיים, גרש, מירכאות כפולות וסימני אמפרסנד (&) בישויות ה-XML המתאימות. לשימוש במסמכי XML 1.0.

EscapeXML11(string) פועלת באותו אופן כמו EscapeXML, אלא רק לישויות XML בגרסה 1.1. עיינו בהמשך בהערות על שימוש.
encodeHTML(string) קידוד של גרש, סוגריים זוויתיים ואמפרסנד.

ארגומנטים

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

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

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

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

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

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

דוגמאות

נניח שיש משתנה זרימה בשם food עם הערך הזה: "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.

ארגומנטים

  • 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
    

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

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

    תחביר

    randomLong(args)
    

    ארגומנטים

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

    דוגמה

    {random()}
    

    תתקבל תוצאה כזו:

    5211338197474042880
    

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

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

    תחביר

    xeger(regex)
    

    ארגומנט

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

    דוגמה

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

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

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

    9857253
    

    פונקציית כיווץ עם null

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

    תחביר

    firstnonnull(var1,varn)
    

    ארגומנט

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

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

    דוגמאות

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

    תבנית 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 על משתנה 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']