כרגע מוצג התיעוד של 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
רכיבי צאצא של
|
המדיניות בנושא תוספי יתרונות מרכזיים |
<Input> |
המדיניות בנושא חילוץ משתנים | <JsonPath>
|
המדיניות של GenerateJWS המדיניות בנושא אימותJWS |
<Payload> (מדיניות GenerateJWS בלבד)
* הרכיבים האלה תומכים בתבנית הודעה רק כאשר type=map. |
מדיניות GenerateJWT המדיניות בנושא אימותJWT |
<AdditionalClaims><Claim>
* הרכיבים האלה תומכים בתבנית הודעה רק כאשר type=map. |
מדיניות LDAP | <SearchQuery> |
המדיניות בנושא MessageLogging | <Syslog><Message>
|
המדיניות בנושא OASValidation | רכיב
|
מדיניות RaiseFault | רכיבי <Set> : Payload, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, כותרות, QueryParams, FormParams
רכיבי |
מדיניות SAMLAssertion | <Template>
* רק אם חתימת המדיניות היא |
המדיניות בנושא יתרונות מרכזיים של שירות | רכיבי <Set> : Payload, ContentType, Verb, Version, Path, StatusCode, ReasonPhrase, /Headers, QueryParams, FormParams
רכיבי
|
רכיבי 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)}
תוצאות ב:
"bread" & "butter"
פונקציות של פורמט שעה
החזרת ייצוג מחרוזת של השעה בפורמט של אזור הזמן המקומי או לפי שעון 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
הפונקציות מחזירות את התוצאות הבאות:
- key – (חובה) מציין את המפתח הסודי, מקודד כמחרוזת, המשמש לחישוב ה-HMAC.
- valueToSign – (חובה) מציין את ההודעה שיש לחתום. הוא צריך להיות מחרוזת.
- keyencoding – (אופציונלי) מחרוזת המפתח הסודית תפוענח בהתאם לקידוד שצוין. ערכים חוקיים:
hex
,base16
,base64
,utf-8
. ברירת המחדל:utf-8
- outputencoding – (אופציונלי) מציינת את אלגוריתם הקידוד שישמש לפלט.
הערכים התקינים:
hex
,base16
,base64
. הערכים לא תלויי-רישיות.hex
ו-base16
הם מילים נרדפות. ברירת המחדל:base64
פעולה | פלט |
---|---|
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. |
ארגומנטים
דוגמאות
בדוגמה הזו נעשה שימוש במדיניות 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']