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

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

מה

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

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

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

סרטונים

כדאי לצפות בסרטונים הבאים כדי לקבל מידע נוסף על מדיניות ExtractVariables.

דוגמאות

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

<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>

מידע על מדיניות ExtractVariables

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

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

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

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

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

היקף

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

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

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

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

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

התאמה של נתיבי 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 הפרוקסי הוא /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>

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

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>

שוב , נניח שיש API Proxy עם נתיב בסיס של /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

כדי להפנות לפרמטרים האלה של השאילתה במדיניות ExtractVariables, משתמשים באינדקסים. המופע הראשון של פרמטר השאילתה לא מקבל אינדקס, המופע השני מקבל אינדקס 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/c ול-‎/a/foo/bar.

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

*;charset={encoding}

התבנית הזו תואמת לערכים text/xml;charset=UTF-16 ו-application/xml;charset=ASCII.

אם הערך שמועבר למדיניות ExtractVariables מכיל תו מיוחד, כמו {‎, צריך להשתמש בתו %‎ כדי לסמן אותו בתו בריחה (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, המשתנה המתאים לא נוצר.

בדוגמה הבאה מוצגת מדיניות ExtractVariables שמאכלסת שתי משתנים מגוף ה-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>

הפניה לרכיב

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

<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">

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

&lt;DisplayName&gt; רכיב

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

<DisplayName>Policy Display Name</DisplayName>

אלמנט <Source>

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

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

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

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

מאפיינים

אלמנט <VariablePrefix>

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

<VariablePrefix>myprefix</VariablePrefix>

לדוגמה, נניח שהערך של name הוא 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>

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

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

הסבר על המשתנים