Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

‫ExtractVariables policy

מדיניות ניתנת להרחבה

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

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

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

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

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

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

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

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

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

דוגמאות

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

מזהי URI

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

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

השם של המשתנה שיוגדר נקבע לפי הערך שצוין ברכיב <VariablePrefix>, וגם לפי הערך שמוקף בסוגריים מסולסלים {} ברכיב <Pattern>. שני הערכים מחוברים באמצעות נקודה ביניהם, ולכן שם המשתנה יהיה urirequest.id, לדוגמה. אם אין רכיב <VariablePrefix>, שם המשתנה הוא רק הערך שמוקף בסוגריים מסולסלים.

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

GET http://example.com/svc1/accounts/12797282

נניח ש-basepath של ה-API Proxy הוא /svc1. כש-Apigee מחיל את קוד המדיניות ExtractVariables שלמעלה על הבקשה הנכנסת הזו, הוא מגדיר את המשתנה urirequest.id כ-12797282. אחרי ש-Apigee מריץ את המדיניות, מדיניות או קוד בהמשך תהליך העיבוד יכולים להתייחס למשתנה שנקרא urirequest.id כדי לקבל את ערך המחרוזת 12797282.

לדוגמה, מדיניות AssignMessage הבאה מטמיעה את הערך של המשתנה הזה במטען הייעודי (payload) של הודעת בקשה חדשה:

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

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

GET http://example.com/accounts/12797282?code=DBN88271

כש-Apigee מחיל את קוד המדיניות ExtractVariables שלמעלה על הבקשה הנכנסת הזו, הוא מגדיר את המשתנה queryinfo.dbncode ל-88271. אחרי ש-Apigee מבצע את המדיניות, מדיניות או קוד בהמשך תהליך העיבוד יכולים להתייחס למשתנה בשם queryinfo.dbncode כדי לקבל את ערך המחרוזת 88271.

עכשיו אפשר לגשת למשתנה queryinfo.dbncode בפרוקסי. לדוגמה, מדיניות AssignMessage הבאה מעתיקה את המשתנה למטען הייעודי (payload) של הבקשה:

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

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

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

GET http://example.com/weather?w=Boston&w=Chicago

כש-Apigee מחיל את קוד המדיניות ExtractVariables שלמעלה על הבקשה הנכנסת הזו, הוא מגדיר את המשתנה queryinfo.firstWeather לערך Boston ואת המשתנה queryInfo.secondWeather לערך Chicago.

עכשיו יש לך גישה למשתנה queryinfo.firstWeather ולמשתנה queryinfo.secondWeather בפרוקסי. לדוגמה, מדיניות AssignMessage הבאה מעתיקה את המטען הייעודי (payload) של הבקשה:

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

נניח שממשק ה-API שלכם משתמש באסימוני Bearer של OAuth v2.0. נניח שיש לנו בקשה עם טוקן OAuth v2.0 שכוללת כותרת כזו: Authorization: Bearer TU08xptfFfeM7aS0xHqlxTgEAdAM.

נניח שאתם מעצבים API ורוצים להשתמש בערך הטוקן (אבל לא בכותרת כולה) כמפתח בחיפוש במטמון. אתם יכולים להשתמש בקוד המדיניות ExtractVariables שלמעלה כדי לחלץ את הטוקן.

כש-Apigee מחיל את קוד המדיניות ExtractVariables שלמעלה על הכותרת הזו, הוא מגדיר את המשתנה clientrequest.oauthtoken לערך TU08xptfFfeM7aS0xHqlxTgEAdAM.

עכשיו אפשר לגשת למשתנה clientrequest.oauthtoken בשרת ה-proxy. לדוגמה, מדיניות AssignMessage הבאה מעתיקה אותו למטען הייעודי (payload) של הבקשה:

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

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>

כדאי לעיין במטען הייעודי (payload) של תגובת ה-JSON הבאה:

{
  "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
        }
      }
    }
  }]
}

כש-Apigee מחיל את קוד המדיניות ExtractVariables שלמעלה על הודעת ה-JSON הזו, הוא מגדיר שני משתנים: geocoderesponse.latitude ו-geocoderesponse.longitude. בשני המשתנים האלה נעשה שימוש באותה תחילית של משתנה, שהיא geocoderesponse. הסיומת של המשתנים האלה מצוינת במפורש במאפיין name של רכיב <Variable>.

המשתנה geocoderesponse.latitude מקבל את הערך 37.42291810. המשתנה geocoderesponse.longitude מקבל את הערך -122.08542120.

עכשיו אפשר לגשת למשתנה geocoderesponse.latitude בפרוקסי. לדוגמה, מדיניות AssignMessage הבאה מעתיקה את הכותרת לכותרת בשם latitude בתגובה:

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

XML

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

כדאי לעיין במטען הייעודי (payload) של תגובת ה-XML הבאה:

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

כש-Apigee מחיל את קוד המדיניות ExtractVariables שלמעלה על הודעת ה-XML הזו, הוא מגדיר שלושה משתנים:

‫directionsresponse.travelmode: קבלת הערך DRIVING
‫directionsresponse.duration: קבלת הערך 19
‫directionsresponse.timeunit: קבלת הערך minutes

כל המשתנים משתמשים באותו קידומת משתנה directionsresponse. הסיומת של המשתנים האלה מצוינת באופן מפורש על ידי מאפיין name של רכיב <Variable>.

עכשיו יש לך גישה למשתנה directionresponse.travelmode בשרת ה-proxy. לדוגמה, מדיניות AssignMessage הבאה מעתיקה את הערך לכותרת בשם tmode בתגובה:

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

הערה: הגדרת Content-Type: כשמחפשים משתנים בהודעות XML (כולל SOAP), החיפוש עובד רק אם Content-Type מוגדר בכותרת ההודעה (או בכותרת SOAP). לדוגמה, application/xml.

היקף המשתנה

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

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

טיפ: אם המשתנה החדש שחולץ לא מופיע בכלי לניפוי באגים, נסו להסיר את הרכיב <VariablePrefix> אם הוספתם אותו. מידע נוסף זמין במאמר ExtractVariables לא מוצג ב-trace.

התאמה ויצירת משתנים

המדיניות 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 Proxy הוא /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

‫…then the third pattern matches and the urirequest.pathSeg variable is set to 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> 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">

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

מאפיין	תיאור	ברירת מחדל	נוכחות
`name`	השם הפנימי של המדיניות. הערך של מאפיין `name` יכול להכיל אותיות, מספרים, רווחים, מקפים, קווים תחתונים ונקודות. הערך הזה לא יכול לחרוג מ-255 תווים. אפשר להשתמש ברכיב `<DisplayName>` כדי לתת למדיניות תווית בשם אחר בשפה טבעית בכלי לעריכת פרוקסי בממשק הניהול.	לא רלוונטי	חובה
`continueOnError`	מגדירים את הערך `false` כדי להחזיר שגיאה אם המדיניות נכשלת. זו התנהגות צפויה ברוב המדיניות. הגדרה ל-`true` מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת. מידע נוסף: הפעלת כללי תקלות מתבצעת רק במצב שגיאה (מידע על continueOnError) טיפול בתקלות בתהליך הנוכחי	FALSE	אופציונלי
`enabled`	מגדירים את המדיניות למצב `true` כדי לאכוף אותה. מגדירים את הערך `false` כדי להשבית את המדיניות. המדיניות לא תיאכף גם אם היא תישאר מצורפת לזרימה.	TRUE	אופציונלי
`async`	המאפיין הזה הוצא משימוש.	FALSE	הוצא משימוש

אלמנט <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

ברירת מחדל

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

לא רלוונטי

אם לא מציינים את הרכיב הזה, המערכת משתמשת בערך של המאפיין name של המדיניות.

נוכחות אופציונלי

סוג String

רכיב <Source>

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

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

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

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

ברירת מחדל:	הודעה
נוכחות:	אופציונלי
סוג:	String

מאפיינים

מאפיין תיאור ברירת מחדל נוכחות סוג

מאפיין	תיאור	ברירת מחדל	נוכחות	סוג
`clearPayload`	אם רוצים לנקות את המטען הייעודי שצוין ב-`<Source>` אחרי חילוץ הנתונים ממנו, צריך להגדיר את האפשרות כ-true. משתמשים באפשרות `<clearPayload>` רק אם הודעת המקור לא נדרשת אחרי ההפעלה של ExtractVariables. אם המדיניות מוגדרת כ-true, מתפנה הזיכרון שבו נעשה שימוש בהודעה.	FALSE	אופציונלי	בוליאני

clearPayload

אם רוצים לנקות את המטען הייעודי שצוין ב-<Source> אחרי חילוץ הנתונים ממנו, צריך להגדיר את האפשרות כ-true.

משתמשים באפשרות <clearPayload> רק אם הודעת המקור לא נדרשת אחרי ההפעלה של ExtractVariables. אם המדיניות מוגדרת כ-true, מתפנה הזיכרון שבו נעשה שימוש בהודעה.

FALSE

אופציונלי

בוליאני

אלמנט <VariablePrefix>

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

<VariablePrefix>myprefix</VariablePrefix>

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

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

ברירת מחדל:	לא רלוונטי
נוכחות:	אופציונלי
סוג:	String

אלמנט <IgnoreUnresolvedVariables>

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

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

ברירת מחדל:	לא נכון
נוכחות:	אופציונלי
סוג:	בוליאני

אלמנט <URIPath>

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

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

ברירת מחדל:	לא רלוונטי
נוכחות:	זה שינוי אופציונלי. עם זאת, אתם צריכים לכלול לפחות אחד מהמאפיינים הבאים: `<URIPath>`,‏ `<QueryParam>`,‏ `<Header>`, `<FormParam>`,‏ `<JSONPayload>` או `<XMLPayload>.`
סוג:	לא רלוונטי

מאפיינים

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

אלמנט <QueryParam>

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

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

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

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

ברירת מחדל:	לא רלוונטי
נוכחות:	זה שינוי אופציונלי. עם זאת, אתם צריכים לכלול לפחות אחד מהמאפיינים הבאים: `<URIPath>`,‏ `<QueryParam>`,‏ `<Header>`, `<FormParam>`,‏ `<JSONPayload>` או `<XMLPayload>.`
סוג:	לא רלוונטי

מאפיינים

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

אלמנט <Header>

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

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

ברירת מחדל:	לא רלוונטי
נוכחות:	זה שינוי אופציונלי. עם זאת, אתם צריכים לכלול לפחות אחד מהמאפיינים הבאים: `<URIPath>`,‏ `<QueryParam>`,‏ `<Header>`, `<FormParam>`,‏ `<JSONPayload>` או `<XMLPayload>.`
סוג:	לא רלוונטי

מאפיינים

מאפיין	תיאור	ברירת מחדל	נוכחות	סוג
name	מציינים את שם הכותרת שממנה רוצים לחלץ את הערך. אם לכמה כותרות יש את אותו שם, צריך להשתמש בהפניה עם אינדקס. המופע הראשון של הכותרת לא מקבל אינדקס, המופע השני מקבל אינדקס 2, המופע השלישי מקבל אינדקס 3 וכן הלאה. אפשר להשתמש ב-`.values` כדי לקבל את כל הכותרות במערך.	לא רלוונטי	חובה	String

רכיב <FormParam>

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

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

ברירת מחדל:	לא רלוונטי
נוכחות:	זה שינוי אופציונלי. עם זאת, אתם צריכים לכלול לפחות אחד מהמאפיינים הבאים: `<URIPath>`,‏ `<QueryParam>`,‏ `<Header>`, `<FormParam>`,‏ `<JSONPayload>` או `<XMLPayload>.`
סוג:	לא רלוונטי

מאפיינים

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

אלמנט <Variable>

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

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

כדי לחלץ שני ערכים מהמשתנה:

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

ברירת מחדל:	לא רלוונטי
נוכחות:	זה שינוי אופציונלי. עם זאת, אתם צריכים לכלול לפחות אחד מהמאפיינים הבאים: `<URIPath>`,‏ `<QueryParam>`,‏ `<Header>`, `<FormParam>`,‏ `<JSONPayload>` או `<XMLPayload>.`
סוג:	לא רלוונטי

מאפיינים

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

אלמנט <JSONPayload>

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

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

ברירת מחדל:	לא רלוונטי
נוכחות:	זה שינוי אופציונלי. עם זאת, אתם צריכים לכלול לפחות אחד מהמאפיינים הבאים: `<URIPath>`,‏ `<QueryParam>`,‏ `<Header>`, `<FormParam>`,‏ `<JSONPayload>` או `<XMLPayload>.`
סוג:	לא רלוונטי

אלמנט <JSONPayload>/<Variable>

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

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

ברירת מחדל:	לא רלוונטי
נוכחות:	חובה להשתמש בו ברכיב JSONPayload.
סוג:	לא רלוונטי

מאפיינים

מאפיין	תיאור	ברירת מחדל	נוכחות	סוג
name	מציינת את שם המשתנה שאליו יוקצה הערך שחולץ.	name	חובה	String
סוג	מציין את סוג הנתונים של ערך המשתנה.	לא רלוונטי	אופציונלי	מחרוזת. אפשר לבחור מבין האפשרויות הבאות: מחרוזת בוליאני מספר שלם ארוך מספר ממשי (float) double nodeset (מחזיר קטע JSON)

מאפיין

תיאור

ברירת מחדל

נוכחות

סוג

name

מציינת את שם המשתנה שאליו יוקצה הערך שחולץ.

name

חובה

String

סוג

מציין את סוג הנתונים של ערך המשתנה.

לא רלוונטי

אופציונלי

מחרוזת. אפשר לבחור מבין האפשרויות הבאות:

מחרוזת
בוליאני
מספר שלם
ארוך
מספר ממשי (float)
double
nodeset (מחזיר קטע JSON)

אלמנט <JSONPayload>/<Variable>/<JSONPath>

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

הערה: ה<JSONPath> רכיב תומך בתכונת החלפת המחרוזות הדינמית שנקראת תבנוּת הודעות.

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

ברירת מחדל:	לא רלוונטי
נוכחות:	חובה
סוג:	String

אלמנט <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>

ברירת מחדל:	לא רלוונטי
נוכחות:	זה שינוי אופציונלי. עם זאת, אתם צריכים לכלול לפחות אחד מהמאפיינים הבאים: `<URIPath>`,‏ `<QueryParam>`,‏ `<Header>`, `<FormParam>`,‏ `<JSONPayload>` או `<XMLPayload>.`
סוג:	לא רלוונטי

מאפיינים

מאפיין	תיאור	ברירת מחדל	נוכחות	סוג
`stopPayloadProcessing`	הערך `true` יגרום להפסקת ההערכה של XPath אחרי שאוכלס משתנה אחד. כלומר, רק משתנה אחד יאוכלס על ידי המדיניות.	FALSE	אופציונלי	בוליאני

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

ברירת מחדל:	לא רלוונטי
נוכחות:	אופציונלי
סוג:	String

מאפיינים

מאפיין	תיאור	ברירת מחדל	נוכחות	סוג
`prefix`	קידומת מרחב השמות.	לא רלוונטי	חובה	String

אלמנט <XMLPayload>/<Variable>

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

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

ברירת מחדל:	לא רלוונטי
נוכחות:	אופציונלי
סוג:	לא רלוונטי

מאפיינים

מאפיין	תיאור	ברירת מחדל	נוכחות	סוג
name	מציינת את שם המשתנה שאליו יוקצה הערך שחולץ.	name	חובה	String
סוג	מציין את סוג הנתונים של ערך המשתנה.	בוליאני	אופציונלי	מחרוזת. אפשר לבחור מבין האפשרויות הבאות: מחרוזת בוליאני מספר שלם ארוך מספר ממשי (float) double nodeset (מחזירה קטע XML)

מאפיין

תיאור

ברירת מחדל

נוכחות

סוג

name

מציינת את שם המשתנה שאליו יוקצה הערך שחולץ.

name

חובה

String

סוג

מציין את סוג הנתונים של ערך המשתנה.

בוליאני

אופציונלי

מחרוזת. אפשר לבחור מבין האפשרויות הבאות:

מחרוזת
בוליאני
מספר שלם
ארוך
מספר ממשי (float)
double
nodeset (מחזירה קטע XML)

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

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

האלמנט <XPath> לא תומך בתבניות הודעות.

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

ברירת מחדל:	לא רלוונטי
נוכחות:	חובה
סוג:	String

הערה: השימוש ב-parent, ancestor,‏ following ו-preceding בביטויי XPath לא נתמך ב-Apigee. כדי לקבל את אותן תוצאות התאמה, אפשר לנסות התאמה או יצירת אינדקס של שמות צמתים מפורשים. לדוגמה:

‫<XPath>/Attributes/Attribute[@Name=’foo_attribute']/Value</XPath>
מקבל את הערך foo_attribute.
<XPath>/Attributes/Attribute[4]/Value</XPath>
מקבל את הערך של המאפיין הרביעי.

הפניה לשגיאה

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

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

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

קוד תקלה	סטטוס HTTP	מטרה	תיקון
`steps.extractvariables.ExecutionFailed`	`500`	השגיאה הזו מתרחשת במקרים הבאים: המטען הייעודי (payload) של הקלט (JSON, ‏ XML) ריק. הקלט (JSON,‏ XML וכו') שהועבר למדיניות לא תקין או שהפורמט שלו שגוי.
`steps.extractvariables.ImmutableVariable`	`500`	משתנה שמשמש במדיניות הוא קבוע. המדיניות לא הצליחה להגדיר את המשתנה הזה.	לא רלוונטי
`steps.extractvariables.InvalidJSONPath`	`500`	השגיאה הזו מתרחשת אם נעשה שימוש בנתיב JSON לא תקין ברכיב `JSONPath` של המדיניות. לדוגמה, אם מטען ייעודי (payload) של JSON לא מכיל את האובייקט `Name`, אבל מציינים את `Name` כנתיב במדיניות, השגיאה הזו תופיע.
`steps.extractvariables.JsonPathParsingFailure`	`500`	השגיאה הזו מתרחשת כשהמדיניות לא מצליחה לנתח נתיב JSON ולחלץ נתונים ממשתנה הזרימה שצוין ברכיב `Source`. בדרך כלל זה קורה אם משתנה הזרימה שצוין ברכיב `Source` לא קיים בזרימה הנוכחית.
`steps.extractvariables.SetVariableFailed`	`500`	השגיאה הזו מתרחשת אם המדיניות לא הצליחה להגדיר את הערך למשתנה. השגיאה מתרחשת בדרך כלל אם מנסים להקצות ערכים לכמה משתנים שהשמות שלהם מתחילים באותן מילים בפורמט מקונן עם נקודות.
`steps.extractvariables.SourceMessageNotAvailable`	`500`	השגיאה הזו מתרחשת אם המשתנה message שצוין ברכיב `Source` של המדיניות הוא אחד מהבאים: לא נכלל בהיקף (לא זמין בתהליך הספציפי שבו המדיניות מופעלת) או אי אפשר לפתור (לא מוגדר)
`steps.extractvariables.UnableToCast`	`500`	השגיאה הזו מתרחשת אם המדיניות לא הצליחה להמיר את הערך שחולץ למשתנה. בדרך כלל זה קורה כשמנסים להגדיר את הערך של סוג נתונים אחד למשתנה של סוג נתונים אחר.

שגיאות בהטמעה

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

שם השגיאה	מטרה	תיקון
`NothingToExtract`	אם המדיניות לא כוללת את הרכיבים `URIPath`,‏ `QueryParam`,‏ `Header`,‏ `FormParam`,‏ `XMLPayload` או `JSONPayload`, הפריסה של ה-API Proxy תיכשל כי אין מה לחלץ.
`NONEmptyPrefixMappedToEmptyURI`	השגיאה הזו מתרחשת אם למדיניות יש קידומת שמוגדרת ברכיב `Namespace` מתחת לרכיב `XMLPayload`, אבל לא מוגדר URI.
`DuplicatePrefix`	השגיאה הזו מתרחשת אם לאותו כלל מדיניות מוגדר אותו קידומת יותר מפעם אחת ברכיב `Namespace` שמתחת לרכיב `XMLPayload`.
`NoXPathsToEvaluate`	אם למדיניות אין את הרכיב `XPath` בתוך הרכיב `XMLPayload`, ה-Deployment (פריסה) של ה-proxy ל-API נכשל עם השגיאה הזו. אם רוצים לחלץ משתנים מ-XML Payload, צריך לציין רכיב צאצא מסוג `XPath`.
`EmptyXPathExpression`	אם במדיניות יש ביטוי `XPath` ריק בתוך הרכיב `XMLPayload`, פריסת ה-proxy ל-API תיכשל.
`NoJSONPathsToEvaluate`	אם למדיניות אין את הרכיב `JSONPath` בתוך הרכיב `JSONPayload`, ה-Deployment (פריסה) של ה-proxy ל-API נכשל עם השגיאה הזו.
`EmptyJSONPathExpression`	אם במדיניות יש ביטוי `XPath` ריק בתוך הרכיב `XMLPayload`, פריסת ה-proxy ל-API תיכשל.
`MissingName`	אם למדיניות אין את המאפיין `name` באף אחד מרכיבי המדיניות כמו `QueryParam`, `Header`, `FormParam` או `Variable`, במקום שבו הוא נדרש, הפריסה של ה-proxy ל-API נכשלת.
`PatternWithoutVariable`	אם במדיניות לא מצוין משתנה ברכיב `Pattern`, פריסת proxy ל-API תיכשל. רכיב `Pattern` דורש את שם המשתנה שבו יאוחסנו הנתונים שחולצו.
`CannotBeConvertedToNodeset`	אם במדיניות יש ביטוי `XPath` שבו הסוג `Variable` מוגדר כ-nodeset, אבל אי אפשר להמיר את הביטוי ל-nodeset, פריסת ה-proxy ל-API תיכשל.
`JSONPathCompilationFailed`	המדיניות לא הצליחה לקמפל נתיב JSON שצוין.	לא רלוונטי
`InstantiationFailed`	לא ניתן ליצור מופע של המדיניות.	לא רלוונטי
`XPathCompilationFailed`	אם הקידומת או הערך שמשמשים ברכיב `XPath` לא שייכים לאף אחד ממרחבי השמות שהוגדרו במדיניות, הפריסה של שרת ה-API הפרוקסי תיכשל.
`InvalidPattern`	אם ההגדרה של הרכיב `Pattern` לא תקינה באף אחד מהרכיבים כמו `URIPath`, `QueryParam`, `Header`, `FormParam`, `XMLPayload` או `JSONPayload` במדיניות, פריסת ה-proxy ל-API תיכשל. האלמנט `Pattern` נחשב לא תקין אם הוא לא כולל משתנה. מידע נוסף על התאמת תבניות זמין במאמר מידע על התאמה ויצירת משתנים.

משתני תקלות

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

משתנים	כאשר:	דוגמה
`fault.name="fault_name"`	‫`fault_name` הוא שם התקלה, כפי שמופיע בטבלה Runtime errors שלמעלה. שם התקלה הוא החלק האחרון של קוד התקלה.	`fault.name = "SourceMessageNotAvailable"`
`extractvariables.policy_name.failed`	‫`policy_name` הוא השם שהמשתמש הגדיר למדיניות שגרמה לשגיאה.	`extractvariables.EV-ParseJsonResponse.failed = true`

דוגמה לתגובת שגיאה

הערה: כדי לטפל בשגיאות, מומלץ ללכוד את החלק errorcode של תגובת השגיאה. אל תסתמכו על הטקסט ב-faultstring, כי הוא עשוי להשתנות.

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

סכימות

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

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

‫ExtractVariables policy קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

דוגמאות

מזהי URI

פרמטרים של שאילתה

פרמטרים מרובים

כותרות

JSON

XML

היקף המשתנה

התאמה ויצירת משתנים

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

ציון של כמה דפוסים

ציון תבניות עם כמה משתנים

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

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

התאמה בין JSON ל-XML

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

שליטה בפעולות שמתבצעות כשאין התאמה

הפניה לרכיב

מאפיינים של <ExtractVariables>

אלמנט <DisplayName>

רכיב <Source>

מאפיינים

אלמנט <VariablePrefix>

אלמנט <IgnoreUnresolvedVariables>

אלמנט <URIPath>

מאפיינים

אלמנט <QueryParam>

מאפיינים

אלמנט <Header>

מאפיינים

רכיב <FormParam>

מאפיינים

אלמנט <Variable>

מאפיינים

אלמנט <JSONPayload>

אלמנט <JSONPayload>/<Variable>

מאפיינים

אלמנט <JSONPayload>/<Variable>/<JSONPath>

אלמנט <XMLPayload>

מאפיינים

‫<XMLPayload>/<Namespaces> element

מאפיינים

אלמנט <XMLPayload>/<Variable>

מאפיינים

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

הפניה לשגיאה

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

שגיאות בהטמעה

משתני תקלות

דוגמה לתגובת שגיאה

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

סכימות

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

‫ExtractVariables policy