המדיניות בנושא ExtractVariables

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X. מידע

מה

המדיניות ceVariables מחלצת תוכן מבקשה או מתגובה ומגדירה את הערך של משתנה לתוכן הזה. אפשר לחלץ כל חלק מההודעה, כולל כותרות, נתיבי URI, מטענים ייעודיים (payloads) של JSON/XML, פרמטרים של טפסים ופרמטרים של שאילתות. כדי לעשות את זה, המערכת מחילה תבנית טקסט על תוכן ההודעה ומגדירה משתנה עם תוכן ההודעה שצוין, אחרי שהיא מוצאת התאמה.

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

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

סרטונים

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

טעימות

הדוגמאות של קוד המדיניות ממחישות איך לחלץ משתנים מהסוגים הבאים של פריטי המידע שנוצרו בתהליך הפיתוח (Artifact):

<ExtractVariables name="ExtractVariables-1">
   <DisplayName>Extract a portion of the url path</DisplayName>
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/accounts/{id}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

<AssignMessage async="false" continueOnError="false" enabled="true" name="AssignPayload">
 <DisplayName>AssignPayload</DisplayName>
  <Set>
   <Payload contentType="text/xml">
    <IdExtractedFromURI>{urirequest.id}</IdExtractedFromURI>
   </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="true" transport="http" type="request">newRequest</AssignTo>
</AssignMessage>

<ExtractVariables name="ExtractVariables-2">
   <DisplayName>Extract a value from a query parameter</DisplayName>
   <Source>request</Source>
   <QueryParam name="code">
      <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
   </QueryParam>
   <VariablePrefix>queryinfo</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
 <DisplayName>GetQP</DisplayName>
  <Set>
   <Payload contentType="text/xml">
    <ExtractQP>{queryinfo.dbncode}</ExtractQP>
   </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

<ExtractVariables name="ExtractVariables-2">
   <DisplayName>Extract a value from a query parameter</DisplayName>
   <Source>request</Source>
   <QueryParam name="w">
      <Pattern ignoreCase="true">{firstWeather}</Pattern>
   </QueryParam>
   <QueryParam name="w.2">
     <Pattern ignoreCase="true">{secondWeather}</Pattern>
   </QueryParam>
   <VariablePrefix>queryinfo</VariablePrefix>
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
 <DisplayName>GetQP</DisplayName>
  <Set>
   <Payload contentType="text/xml">
    <ExtractQP1>{queryinfo.firstWeather}</ExtractQP1>
    <ExtractQP2>{queryinfo.secondWeather}</ExtractQP2>
   </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

<ExtractVariables name='ExtractVariable-OauthToken'>
  <Source>request</Source>
  <Header name="Authorization">
    <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
  </Header>
  <VariablePrefix>clientrequest</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
 <DisplayName>GetHeader</DisplayName>
  <Set>
   <Payload contentType="text/xml">
    <ExtractHeader>{clientrequest.oauthtoken}</ExtractHeader>
   </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

<ExtractVariables name="ExtractVariables-3">
   <Source>response</Source>
   <JSONPayload>
      <Variable name="latitude" type="float">
         <JSONPath>$.results[0].geometry.location.lat</JSONPath>
      </Variable>
      <Variable name="longitude" type="float">
         <JSONPath>$.results[0].geometry.location.lng</JSONPath>
      </Variable>
   </JSONPayload>
   <VariablePrefix>geocoderesponse</VariablePrefix>
</ExtractVariables>

{
  "results": [{
    "geometry": {
      "location": {
        "lat": 37.42291810,
        "lng": -122.08542120
      },
      "location_type": "ROOFTOP",
      "viewport": {
        "northeast": {
          "lat": 37.42426708029149,
          "lng": -122.0840722197085
        },
        "southwest": {
          "lat": 37.42156911970850,
          "lng": -122.0867701802915
        }
      }
    }
  }]
}

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetJSONVar</DisplayName>
  <Add>
    <Headers>
      <Header name="latitude">{geocoderesponse.latitude}</Header>
    </Headers>
  </Add> 
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/> 
</AssignMessage>

<ExtractVariables name="ExtractVariables-4">
   <Source>response</Source>
   <XMLPayload>
      <Namespaces>
         <Namespace prefix="dir">urn:43BFF88D-D204-4427-B6BA-140AF393142F</Namespace>
      </Namespaces>
      <Variable name="travelmode" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/@mode</XPath>
      </Variable>
      <Variable name="duration" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/dir:duration/dir:value</XPath>
      </Variable>
      <Variable name="timeunit" type="string">
         <XPath>/dir:Directions/dir:route/dir:leg/dir:step/dir:duration/dir:text</XPath>
      </Variable>
   </XMLPayload>
   <VariablePrefix>directionsresponse</VariablePrefix>
</ExtractVariables>

<Directions xmlns="urn:43BFF88D-D204-4427-B6BA-140AF393142F">
   <status>OK</status>
   <route>
      <summary>I-40 W</summary>
      <leg>
         <step mode="DRIVING">
            <start_location>
               <lat>41.8507300</lat>
               <lng>-87.6512600</lng>
            </start_location>
            <end_location>
               <lat>41.8525800</lat>
               <lng>-87.6514100</lng>
            </end_location>
            <duration>
                <value>19</value>
                <text>minutes</text>
            </duration>
         </step>
      </leg>
   </route>
</Directions>

<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath">
  <DisplayName>GetXMLVar</DisplayName>
  <Add>
    <Headers>
      <Header name="tmode">{directionsresponse.travelmode}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

מידע על המדיניות בנושא extracts

מפתחי API בונים שרתי proxy של API שמתנהגים באופן שונה בהתאם לתוכן ההודעות, כולל כותרות, נתיבי URI, מטענים ייעודיים (payload) ופרמטרים של שאילתות. בדרך כלל, שרת ה-proxy מחלץ חלק מהתוכן הזה לשימוש בהצהרת תנאים. כדי לעשות זאת, צריך להשתמש במדיניות extracts.

כשמגדירים את המדיניות extracts, ניתן לבחור באפשרויות הבאות:

• שמות המשתנים להגדרה
• מקור המשתנים
• כמה משתנים צריך לחלץ ולהגדיר

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

במאמר ניתוח תוכן של הודעות ב-API באמצעות ניתוח נתונים בהתאמה אישית מוסבר איך אפשר להשתמש ב-extracts כדי ליצור דוחות Analytics מבוססי-תוכן.

היקף

למשתנים שמוגדרים עם המדיניות extracts יש היקף גלובלי. במילים אחרות, אחרי שבמדיניות extracts מוגדרת משתנה חדש, אפשר לגשת למשתנה הזה מכל מדיניות או קוד בכל שלב בתהליך (שמתרחש אחרי המדיניות ex Variables). האיסור הזה כולל:

• PreFlow: ProxyEndpoint ו-TargetEndpoint (בקשה ותגובה)
• PostFlow: ProxyEndpoint ו-TargetEndpoint (בקשה ותגובה)
• PostClientFlow: ProxyEndpoint (תגובה בלבד, באמצעות המדיניות בנושא רישום הודעות)
• תהליכי שגיאה

מידע על התאמה ועל יצירת משתנים

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

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

נתיבי URI תואמים, פרמטרים של שאילתות, כותרות, פרמטרים של טפסים ומשתנים

כשמחלצים מידע מנתיב URI, מפרמטרים של שאילתה, מכותרות, מפרמטרים של טופס וממשתנים, צריך להשתמש בתג <Pattern> כדי לציין תבנית אחת או יותר להתאמה. לדוגמה, הדוגמה הבאה של מדיניות מציגה דפוס תואם יחיד עבור נתיב ה-URI:

<ExtractVariables name="ExtractVariables-1">
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

בדוגמה הזו, המשתנה urirequest.pathSeg מוגדר למה שמופיע ב-proxy.pathsuffix אחרי '/a/'. לדוגמה, נניח שהנתיב הבסיסי של שרת ה-API של ה-API הוא /basepath/v1 . במקרה של בקשה נכנסת אל http://myCo.com/basepath/v1/a/b, המשתנה מוגדר ל-'b'.

ציון תבניות מרובות

אתם יכולים לציין כמה אותיות רישיות להתאמה, שתואמות לתגי <Pattern>, במקרים הבאים:

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

בדוגמה הבאה יוצרים מדיניות שמכילה שלוש תבניות תואמות לנתיב ה-URI:

<ExtractVariables name="ExtractVariables-1">
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
      <Pattern ignoreCase="true">/a/b/{pathSeg}</Pattern>
      <Pattern ignoreCase="true">/a/b/c/{pathSeg}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

נניח, לגבי שרת Proxy ל-API עם נתיב בסיס /basepath/v1 , כתובת ה-URL של הבקשה הנכנסת לשרת ה-proxy של ה-API היא בתבנית הבאה:

http://myCo.com/basepath/v1/a/b

בדוגמה הזו, הדפוס הראשון תואם ל-URI והמשתנה urirequest.pathSeg מוגדר ל-'b'.

אם כתובת ה-URL של הבקשה היא:

http://myCo.com/basepath/v1/a/b/c/d

...הדפוס השלישי תואם ואז המשתנה urirequest.pathSeg מוגדר כ-'d'.

ציון דפוסים עם משתנים מרובים

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

<ExtractVariables name="ExtractVariables-1">
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
      <Pattern ignoreCase="true">/a/b/{pathSeg}</Pattern>
      <Pattern ignoreCase="true">/a/{pathSeg1}/c/{pathSeg2}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

שוב, מתוך הנחה ששרת proxy ל-API עם נתיב הבסיס /basepath/v1, לכתובת ה-URL של הבקשה הנכנסת:

http://myCo.com/basepath/v1/a/b/c/d

...המשתנה urirequest.pathSeg1 מוגדר כ-'b' והמשתנה urirequest.pathSeg2 מוגדר כ-'d'.

התאמה של כמה מופעים בתבנית

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

http://myCo.com/basepath/v1/a/b/c/d?w=1&w=2

כדי להפנות לפרמטרים של השאילתה האלה במדיניות extracts, עליך להשתמש באינדקסים: למופע הראשון של פרמטר השאילתה אין אינדקס, למופע השני באינדקס 2, למופע השלישי באינדקס 3 וכו'. לדוגמה, המדיניות הבאה מחלצת את הערך של פרמטר השאילתה השני בשם "w" בבקשה:

<ExtractVariables name="ExtractVariables-1">
   <Source>request</Source>
   <QueryParam name="w.2">
      <Pattern ignoreCase="true">{secondW}</Pattern>
   </QueryParam>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

המשתנה urirequest.secondW מוגדר ל-'2'. אם הפרמטר השני של השאילתה מושמט מהבקשה, המשתנה urirequest.secondW ריק. אפשר להשתמש בהוספה לאינדקס בכל פעם שיש בבקשה מספר פריטים עם אותו שם.

שימוש בתווים מיוחדים בתבנית

כשמתאימים נתיבי URI, אפשר להשתמש בתווים הכלליים לחיפוש "*" ו-"**" בדפוס, כאשר:

• "*" תואם לכל קטע בנתיב
• "**" תואם למספר פלחים של הנתיב

לדוגמה, אתם מציינים דפוסים לרכיב <URIPath> כפי שמוצג כאן:

<URIPath>
  <Pattern ignoreCase="true">/a/*/{id}</Pattern>
  <Pattern ignoreCase="true">/a/**/{id}</Pattern>
</URIPath>

הדפוס הראשון תואם לבקשות עם נתיבים (החלק של נתיב ה-URI אחרי הנתיב הבסיסי), כמו "/a/b/c", "/a/foo/bar" וכו'. הדפוס השני תואם לכל מספר של קטעי נתיב אחרי " /a/", כמו " /a/foo/bar/baz/c", וגם " /a/b/cbar" ו-".a/foo/foo/bar/cbar".

כשמציינים תבניות לפרמטרים של שאילתות, לכותרות ולפרמטרים של טפסים, התו "*" מציין התאמה לכל מספר של תווים. לדוגמה, בהתאמת כותרת, עליכם לציין את הדפוס כך:

*;charset={encoding}

דפוס זה תואם לערכים "text/xml;charset=UTF-16" ו- "application/xml;charset=ASCII".

אם הערך שהועבר למדיניות extracts מכיל תו מיוחד, כגון '{', עליך להשתמש בתו '%' כדי לסמן אותו בתו בריחה (escape). בדוגמה הבאה המערכת תסמן בתו מילוט (escape) את התווים "{" ו-"}" בתבנית, מכיוון שהם משמשים כתווים מילוליים בערך הפרמטר של השאילתה:

<QueryParam>
  <Pattern ignoreCase="true">%{user%} {name}</Pattern>
</QueryParam>

בדוגמה הזו, הדפוס תואם לערך '{user} Steve' אבל לא את הערך 'user Steve'.

תואם JSON ו-XML

כשמחלצים נתונים מ-JSON ומ-XML, יש לציין תג <Variable> אחד או יותר במדיניות. התג <Variable> מציין את השם של משתנה היעד שבו מאוחסן המידע שחולץ, ואת ה-JsonPath (JSON) או XPath (XML) למידע שחולץ.

כל תגי <Variable> במדיניות נבדקים, כך שאפשר לאכלס מספר משתנים ממדיניות אחת. אם התג <Variable> לא מבצע הערכה לשדה חוקי ב-JSON או ב-XML, המערכת לא יוצרת את המשתנה המתאים.

בדוגמה הבאה מוצגת מדיניות extracts שמאכלסת שני משתנים מגוף ה-JSON של תגובה:

<ExtractVariables name="ExtractVariables-3">
   <Source>response</Source>
   <JSONPayload>
      <Variable name="latitude" type="float">
         <JSONPath>$.results[0].geometry.location.lat</JSONPath>
      </Variable>
      <Variable name="longitude" type="float">
         <JSONPath>$.results[0].geometry.location.lng</JSONPath>
      </Variable>
   </JSONPayload>
   <VariablePrefix>geocoderesponse</VariablePrefix>
</ExtractVariables>

כתיבה לאותו משתנה בכמה מקומות

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

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

<!-- If token only in query param, the query param determines the value. 
     If token is found in both the query param and header, header sets value. -->
<QueryParam name="token">
  <Pattern ignoreCase="true">{tokenValue}</Pattern>
</QueryParam>
 
<!-- Overwrite tokenValue even if it was found in query parameter. -->
<Header name="Token">
  <Pattern ignoreCase="true">{tokenValue}</Pattern>
</Header>

שליטה במה שקורה כשלא מתרחשת התאמה

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

אפשרות אחת היא להגדיר את <IgnoreUnresolvedVariables> כ-TRUE במדיניות שמפנה למשתנה כדי להגדיר את המדיניות כך שתתייחס לכל משתנה שלא ניתן לפתרון כמחרוזת ריקה (null):

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

הפניה לרכיב

בהפניה לרכיב מתוארים הרכיבים והמאפיינים של המדיניות בנושא extracts.

<ExtractVariables async="false" continueOnError="false" enabled="true" name="Extract-Variables-1">
   <DisplayName>Extract Variables 1</DisplayName>
   <Source clearPayload="true|false">request</Source>
   <VariablePrefix>myprefix</VariablePrefix>
   <IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
   <URIPath>
      <Pattern ignoreCase="false">/accounts/{id}</Pattern>
   </URIPath>
   <QueryParam name="code">
      <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
   </QueryParam>
   <Header name="Authorization">
      <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
   </Header>
   <FormParam name="greeting">
      <Pattern>hello {user}</Pattern>
   </FormParam>
   <Variable name="request.content">
       <Pattern>hello {user}</Pattern>
   </Variable>
   <JSONPayload>
      <Variable name="name">
         <JSONPath>{example}</JSONPath>
      </Variable>
   </JSONPayload>
   <XMLPayload stopPayloadProcessing="false">
      <Namespaces/>
      <Variable name="name" type="boolean">
         <XPath>/test/example</XPath>
      </Variable>
   </XMLPayload>
</ExtractVariables>

מאפייני <extractVariables>

<ExtractVariables async="false" continueOnError="false" enabled="true" name="Extract-Variables-1">

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

רכיב <DisplayName>

יש להשתמש במאפיין הזה בנוסף למאפיין name כדי להוסיף למדיניות בכלי לעריכת שרת ה-proxy לניהול ממשק משתמש עם שם אחר בשפה טבעית.

<DisplayName>Policy Display Name</DisplayName>

רכיב <Source>

(אופציונלי) כאן מציינים את המשתנה שרוצים לנתח. ברירת המחדל של הערך של <Source> היא message. הערך message הוא תלוי הקשר. בתהליך בקשה, message מפנה להודעת הבקשה. בתהליך התגובה, message מפנה להודעת התגובה.

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

אם לא ניתן לפענח את <Source>, או אם היא מובילה לסוג שאינו הודעה, המדיניות לא תגיב.

<Source clearPayload="true|false">request</Source>

מאפיינים

אלמנט <VariablePrefix>

(אופציונלי) כדי ליצור את השם המלא של המשתנה, צריך לצרף את <VariablePrefix>, נקודה לשם שהגדרת ב{סוגריים מסולסלים} ברכיב <Pattern> או ברכיב <Variable>. לדוגמה: myprefix.id, myprefix.dbncode או myprefix.oauthtoken.

<VariablePrefix>myprefix</VariablePrefix>

לדוגמה, נניח שהערך של השם הוא "user".

• אם לא מציינים את הערך <VariablePrefix>, הערכים שיחולצו מוקצים למשתנה בשם user.
• אם <VariablePrefix> מצוין בתור myprefix, הערכים שחולצו מוקצים למשתנה בשם myprefix.user.

הרכיב <ignoreUnresolvedVariables>>

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

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

אם הפניה מסוג XPath לא מפוענחת ב-<XMLPayload>, המדיניות מקפיצת את השגיאה הבאה:

{
   "fault":{
      "faultstring":"Unresolved xpath path in policy policy_name.",
      "detail":{
         "errorcode":"steps.extractvariables.InvalidXPath"
      }
   }
}

אלמנט <URIPath>

(אופציונלי, אבל אפשר למצוא מידע נוסף בשורה 'נוכחות' בטבלה שלמטה). משלים ערך מ-proxy.pathsuffix של הודעת מקור של בקשה. הנתיב שחל על התבנית הוא proxy.pathsuffix, שלא כולל את ה-Basepath של ה-API Proxy. אם הודעת המקור מובילה לסוג הודעה של תגובה, הרכיב הזה לא עושה כלום.

<URIPath>
   <Pattern ignoreCase="false">/accounts/{id}</Pattern>
</URIPath>

ניתן להשתמש במספר רכיבי <Pattern>:

<URIPath>
   <Pattern ignoreCase="false">/accounts/{id}</Pattern>
   <Pattern ignoreCase="false">/accounts/{id}/transactions/{index}</Pattern>
</URIPath>

מאפיינים

האלמנט <QueryParam>

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

<QueryParam name="code">
   <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
</QueryParam>

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

<QueryParam name="w.2">
   <Pattern ignoreCase="true">{secondW}</Pattern>
</QueryParam>

מאפיינים

האלמנט <Header>

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

<!-- The name is the actual header name. -->
<Header name="Authorization">
<!-- Provide a name for your new custom variable here. -->
   <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
</Header>

אם למספר כותרות יש שם זהה, השתמשו באינדקסים כדי להפנות לכותרות בודדות במערך:

<Header name="myHeader.2">
   <Pattern ignoreCase="true">{secondHeader}</Pattern>
</Header>

או את הערכים הבאים כדי להציג את כל הכותרות במערך:

<Header name="myHeader.values">
   <Pattern ignoreCase="true">{myHeaders}</Pattern>
</Header>

מאפיינים

אלמנט <FormParam>

(אופציונלי, אבל אפשר למצוא מידע נוסף בשורה 'נוכחות' בטבלה שלמטה). הפונקציה מוציאה ערך מפרמטר הטופס שצוין בהודעת request או response. ניתן לחלץ פרמטרים של טופס רק כאשר הכותרת Content-Type של ההודעה שצוינה היא application/x-www-form-urlencoded.

<FormParam name="greeting">
    <Pattern>hello {user}</Pattern>
</FormParam>

מאפיינים

רכיב <Variable>

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

<Variable name="myVar">
    <Pattern>hello {user}</Pattern>
</Variable>

כך מחלצים שני ערכים מהמשתנה:

<Variable name="myVar">
   <Pattern>hello {firstName} {lastName}</Pattern>
</Variable>

מאפיינים

רכיב <JSONPayload>

(אופציונלי, אבל אפשר למצוא מידע נוסף בשורה 'נוכחות' בטבלה שלמטה). מציינת את ההודעה בפורמט JSON שממנה יחלץ ערך המשתנה. חילוץ JSON מתבצע רק כשהכותרת Content-Type של ההודעה היא application/json.

<JSONPayload>
   <Variable name="name" type="string">
      <JSONPath>{example}</JSONPath>
   </Variable>
</JSONPayload>

רכיב <JSONPayload>/<Variable>

(חובה בתוך הרכיב JSONPayload). ההגדרה הזאת קובעת את המשתנה שאליו יוקצה הערך שחולץ. אפשר לכלול כמה תגי <Variable> ברכיב <JSONPayload> כדי לאכלס משתנים מרובים.

<Variable name="name" type="string">
   <JSONPath>{example}</JSONPath>
</Variable>

מאפיינים

רכיב <JSONPayload>/<Variable>/<JSONPath>

(חובה בתוך הרכיב JSONPayload:Variable). מציינת את נתיב ה-JSON שמשמש לחילוץ ערך מהודעה בפורמט JSON.

<Variable name="name">
   <JSONPath>$.rss.channel.title</JSONPath>
</Variable>

רכיב <XMLPayload>

(אופציונלי, אבל אפשר למצוא מידע נוסף בשורה 'נוכחות' בטבלה שלמטה). מציינת את ההודעה בפורמט XML שממנה יחולץ ערך המשתנה. מטענים ייעודיים (payloads) של XML נשלפים רק כשהכותרת Content-Type של ההודעה היא text/xml, application/xml או application/*+xml.

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
     <Namespace prefix="apigee">http://www.apigee.com</Namespace>
     <Namespace prefix="gmail">http://mail.google.com</Namespace>
  </Namespaces>
  <Variable name="name" type="boolean">
     <XPath>/apigee:test/apigee:example</XPath>
  </Variable>
</XMLPayload>

מאפיינים

רכיב <XMLPayload>/<Namespaces>

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

<XMLPayload stopPayloadProcessing="false">
  <Namespaces>
     <Namespace prefix="apigee">http://www.apigee.com</Namespace>
     <Namespace prefix="gmail">http://mail.google.com</Namespace>
  </Namespaces>
  <Variable name="legName" type="string">
    <XPath>/apigee:Directions/apigee:route/apigee:leg/apigee:name</XPath>
  </Variable>
</XMLPayload>

אם לא משתמשים במרחבי שמות בביטויי XPath, אפשר להשמיט את הרכיב <Namespaces> או להוסיף לו הערות, כפי שמתואר בדוגמה הבאה:

<XMLPayload stopPayloadProcessing="false">
  <!-- <Namespaces/> -->
  <Variable name="legName" type="string">
    <XPath>/Directions/route/leg/name</XPath>
  </Variable>
</XMLPayload>

מאפיינים

רכיב <XMLPayload>/<Variable>

(אופציונלי) מציין את המשתנה שאליו יוקצה הערך שחולץ.

<Variable name="name" type="boolean">
   <XPath>/test/example</XPath>
</Variable>

מאפיינים

רכיב <XMLPayload>/<Variable>/<XPath>

(חובה בתוך הרכיב XMLPayload:Variable). מציין את ה-XPath שהוגדר למשתנה. רק ביטויי XPath 1.0 נתמכים.

<Variable name="name" type="boolean">
   <XPath>/test/example</XPath>
</Variable>

דוגמה עם מרחב שמות. אם השתמשת במרחבי שמות בביטויי XPath, עליך להצהיר על מרחבי השמות בקטע <XMLPayload><Namespaces> במדיניות.

<Variable name="name" type="boolean">
   <XPath>/foo:test/foo:example</XPath>
</Variable>

הפניה לשגיאות

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

שגיאות בזמן ריצה

השגיאות האלה יכולות להתרחש כשהמדיניות מופעלת.

שגיאות בפריסה

השגיאות האלה יכולות להתרחש כשפורסים שרת proxy שכולל את המדיניות הזו.

משתני שבר

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

דוגמה לשגיאה

{
   "fault":{
      "detail":{
         "errorcode":"steps.extractvariables.SourceMessageNotAvailable"
      },
      "faultstring":"request message is not available for ExtractVariable: EV-ParseJsonResponse"
   }
}

דוגמה לכלל שגיאה

<FaultRule name="Extract Variable Faults">
    <Step>
        <Name>AM-CustomErrorMessage</Name>
        <Condition>(fault.name = "SourceMessageNotAvailable") </Condition>
    </Step>
    <Condition>(extractvariables.EM-ParseJsonResponse.failed = true) </Condition>
</FaultRule>

סכימות

נושאים קשורים

ניתוח תוכן של הודעות ב-API באמצעות ניתוח נתונים בהתאמה אישית

הפניות למשתנים