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

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

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

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

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

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

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

דוגמה

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

<AssignMessage name="AM-set-payload-with-dynamic-content">
  <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. אם אי אפשר לפתור את המשתנה, הפלט הוא מחרוזת ריקה.

דוגמה

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

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

  • <Header>
  • <QueryParam>
  • <FormParam>
  • <PayLoad>
  • <Version>
  • <Verb>
  • <Path>
  • <StatusCode>

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

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

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

דוגמה

בהגדרת proxy <TargetEndpoint>, רכיבי צאצא של <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.

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

בטבלה הבאה מפורטים כללי המדיניות והרכיבים או רכיבי הצאצא הנתמכים:

מדיניות רכיבים/רכיבי צאצא
מדיניות AccessControl ‫<SourceAddress>, למאפיין mask ולכתובת ה-IP.
מדיניות AssignMessage <Set> רכיבי צאצא: Payload, ‏ ContentType, ‏ Verb, ‏ Version, ‏ Path, ‏ StatusCode, ‏ Headers, ‏ QueryParams, ‏ FormParams

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

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

מדיניות CORS

<AllowHeaders>

<AllowMethods>

<AllowOrigins>

<ExposeHeaders>
מדיניות ExtractVariables <JsonPath>
‫GenerateJWS policy
VerifyJWS policy

‫<Payload> (GenerateJWS policy בלבד)

<AdditionalHeaders><Claim>

* הרכיבים האלה תומכים בתבנית הודעה רק כשמגדירים type=map.
‫GenerateJWT policy
VerifyJWT policy		 <AdditionalClaims><Claim>

<AdditionalHeaders><Claim>

* הרכיבים האלה תומכים בתבנית הודעה רק כשמגדירים type=map.
מדיניות HTTPModifier <Set> רכיבי צאצא:
  • <ContentType>
  • <Verb>
  • <Version>
  • <Path>
  • <StatusCode>
  • <Headers>
  • <QueryParams>
  • <FormParams>

<Add> רכיבי צאצא:

  • <Headers>
  • <QueryParams>
  • <FormParams>
מדיניות MessageLogging

<CloudLogging><Message>

<Syslog><Message>

<File><Message>
OASValidation policy רכיב <OASResource>
מדיניות RaiseFault

רכיבי <Set>:

  • <ContentType>
  • <FormParams>
  • <Headers>
  • <QueryParams>
  • <StatusCode>
  • <Path>
  • <Payload>
  • <Verb>
  • <Version>

רכיבי <Add>:

  • <FormParams>
  • <Headers>
  • <QueryParams>
מדיניות SAMLAssertion <Template>

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

רכיבי <Set>:

  • <ContentType>
  • <FormParams>
  • <Headers>
  • <QueryParams>
  • <StatusCode>
  • <Path>
  • <Payload>
  • <Verb>
  • <Version>

רכיבי <Add>:

  • <FormParams>
  • <Headers>
  • <QueryParams>

‫<HTTPTargetConnection>/<URL>: ראו תבניות לכתובות URL.

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

<HTTPTargetConnection> רכיבים רכיבי צאצא שתומכים בתבניות של הודעות
<SSLInfo> <Enabled>, <KeyAlias>, <KeyStore>, <TrustStore>, <ClientAuthEnabled>, <CLRStore>
<LocalTargetConnection> <ApiProxy>, <ProxyEndpoint>, <Path>
<Path> לא רלוונטי
<URL> אין רכיבי צאצא. מידע על השימוש מופיע במאמר בנושא תבניות של כתובות URL.

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

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

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

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

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

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

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

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

מותר:

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

אסור: 

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

פונקציות מוטמעות אינן נתמכות

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

{substring({timeFormat('yyyy-MM-dd','1494390266')},0,4)}

תוחמים מחרוזות מילוליות בפונקציות של תבניות במירכאות בודדות

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

לדוגמה, 
{replaceAll('BEARER: 1234','^Bearer ','TOKEN:')}

לא מומלץ להשתמש בתווים מיוחדים במחרוזות מילוליות

לא משתמשים בתווים מיוחדים, כמו ':',‏ '/',‏ '\',‏ '<' או '>', במחרוזות מילוליות. התווים האלה עלולים לגרום לשגיאות. אם מחרוזת ליטרלית דורשת תווים מיוחדים, צריך להקצות את הערך למשתנה באמצעות מדיניות Python או JavaScript ואז להשתמש במשתנה בתבנית.

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

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

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

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

Test message. id = Unknown

תבניות של כתובות URL

רכיב URL תומך בתבניות לפי אותו תחביר כמו רכיבים אחרים.

בדוגמה הזו מוצגת כתובת URL שנבנתה באמצעות משתנים:

<URL>{targeturl}</URL>

בדוגמה הזו מוצג ערך ברירת מחדל לפרוטוקול:

<URL>{protocol:https}://{site:google.com}/path</URL>

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

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

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

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

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

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

דוגמה: 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) של תגובת היעד ולהשתמש ב-AssignMessage כדי להוסיף אותה לתגובת פרוקסי מותאמת אישית (כלומר, לשלוח אותה בחזרה ללקוח).

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

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

עכשיו, הנה מדיניות AssignMessage תקינה לחלוטין שמוסיפה את המשתנה שחולץ למטען הייעודי (payload) של התגובה (התגובה של ה-proxy):

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

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

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

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

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

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

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

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

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

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

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

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

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

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

תחביר

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

ארגומנטים

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

דוגמאות

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

sha256Hex('abc')

תוצאה:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

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

var str = 'abc';
sha256Hex(str)

תוצאה:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

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

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

תחביר

תפקיד תיאור
md5Base64(string) מחשבת גיבוב MD5 שמבוטא כערך בקידוד Base64.
sha1Base64(string) מחשבת גיבוב SHA1 שמבוטא כערך בקידוד Base64.
sha256Base64(string) מחשבת גיבוב SHA256 שמוצג כערך בקידוד Base64.
sha384Base64(string) מחשבת גיבוב SHA384 שמוצג כערך בקידוד Base64.
sha512Base64(string) מחשבת גיבוב 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

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

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

תחביר

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

הפונקציה Replace First

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

תחביר

replaceFirst(string,regex,value)

ארגומנטים

  • ‫string: מחרוזת ליטרלית (מוקפת במירכאות בודדות) או משתנה של זרימת מחרוזת שבהן יתבצעו ההחלפות.
  • ‫regex: ביטוי רגולרי.
  • ‫value: הערך שיחליף את ההתאמות של הביטוי הרגולרי במחרוזת.

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

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

תחביר

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

ארגומנטים

string: המחרוזת שצריך להוסיף לה תווי Escape. יכול להיות מחרוזת מילולית (מוקפת במירכאות בודדות) או משתנה של זרימת מחרוזת.

הערות שימוש

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

התוצאות:

&quot;bread&quot; &amp; &quot;butter&quot;

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

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

תחביר

תפקיד תיאור
timeFormat(format,str)

הפונקציה מחזירה את התאריך בפורמט UTC.

‫DEPRECATED: מחזירה את התאריך בפורמט של אזור הזמן המקומי.
timeFormatMs(format,str)

הפונקציה מחזירה את התאריך בפורמט UTC.

‫DEPRECATED: מחזירה את התאריך בפורמט של אזור הזמן המקומי.
timeFormatUTC(format,str) הפונקציה מחזירה את התאריך בפורמט UTC.
timeFormatUTCMs(format,str) הפונקציה מחזירה את התאריך בפורמט 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.
  • אם יש ארגומנט אחד, הוא נחשב לערך המינימלי של החישוב.
  • אם יש ארגומנט שני, הוא נחשב כערך המקסימלי של החישוב.

דוגמה

{randomLong()}

התוצאה תהיה בערך כזו:

5211338197474042880

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

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

תחביר

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

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

{xpath(xpathexpression,xml,ns1)}

דוגמה 3: ציון סוג ההחזרה הרצוי

הפרמטר השלישי האופציונלי שמועבר לפונקציה 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

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

דוגמה 2

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

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

‫the_json_variable מכיל:

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

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

["A","B"]

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

דוגמה 3

אם the_json_variable מכיל:

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

‫the_query מכיל:

$.config.quota[?(@.operation=="ManageOrder")].appname

התוצאה של תבנית ההודעה: {jsonPath(the_query,the_json_variable,true)} היא ["A","B"]

שימוש במשתנה בשאילתה מאפשר לכם ליצור שאילתה בזמן ריצה, באמצעות נתונים דינמיים. אפשר לעשות את זה באמצעות הרכיב <AssignVariable> במדיניות AssignMessage.

לדוגמה, נניח שהמשתנה operationname מכיל את הערך ManageOrder. המדיניות הבאה תגדיר את the_query לשאילתה שמוצגת למעלה. 

<AssignMessage>
    <AssignVariable>
      <Name>the_query</Name>
      <Template>$.config.quota[?(@.operation=="{operationname}")].appname</Template>
    </AssignVariable>
  </AssignMessage>