שימוש ביצירה של מדיניות

<AssignMessage name="GenerateGeocodingRequest">
  <AssignTo createNew="true" type="request">GeocodingRequest</AssignTo>
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.queryparam.postalcode}</QueryParam>
      <QueryParam name="region">{request.queryparam.country}</QueryParam>
      <QueryParam name="sensor">false</QueryParam>
    </QueryParams>
    <Verb>GET</Verb>
  </Set>
  <!-- Set variables for use in the final response -->
  <AssignVariable>
    <Name>PostalCode</Name>
    <Ref>request.queryparam.postalcode</Ref>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
  </AssignVariable>
</AssignMessage>

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

• <AssignMessage name> – מעניק שם למדיניות זו. השם הוא משמש כאשר יש הפניה למדיניות בתהליך.
• &lt;AssignTo&gt; – יצירת משתנה בעל שם בשם GeocodingRequest. המשתנה הזה כולל את אובייקט הבקשה שיישלח לקצה העורפי על ידי המדיניות בנושא ServiceCallout
• &lt;QueryParams&gt; - מגדיר את הפרמטרים של השאילתה שדרושים קריאה ל-API בקצה העורפי. במקרה הזה, Geocoding API צריך לדעת את המיקום, מבוטאת מיקוד ומזהה מדינה. משתמש האפליקציה מספק את המידע הזה, אנחנו פשוט מחלצים אותו כאן. הפרמטר sensor נדרש על ידי ה-API, והוא או true או false, וכאן פשוט מקלידים את המחרוזת false.
• &lt;Verb&gt; - במקרה הזה, אנחנו שולחים בקשת GET פשוטה API.
• &lt;AssignVariable&gt; – משתנים אלו מאחסנים את הערכים מועברים ל-API. בדוגמה הזו, תתבצע גישה למשתנים בהמשך התשובה שהוחזרו ללקוח.

שליחת הבקשה עם ServiceCallout

השלב הבא ברצף של כתיבת המדיניות הוא יצירת מדיניות ServiceCallout. המדיניות ServiceCallout, שמפורטת בהמשך, שולחת את אובייקט הבקשה שיצרנו במדיניות הקודמת של AssignMessage לשירות Google Geocoding, ושומר את התוצאה שנקרא GeocodingResponse.

<ServiceCallout name="ExecuteGeocodingRequest">
  <Request variable="GeocodingRequest"/>
  <Response>GeocodingResponse</Response>
  <HTTPTargetConnection>
    <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
  </HTTPTargetConnection>
</ServiceCallout>

הנה תיאור קצר של רכיבי המדיניות הזו.

• &lt;ServiceCallout&gt; - כמו במדיניות הקודמת, במדיניות הזו יש שם.
• <Request variable> - זהו המשתנה שנוצר ב- מדיניות AssignMessage. הוא כולל את שליחת הבקשה ל-API של הקצה העורפי.
• &lt;Response&gt; - רכיב זה שם משתנה שבו התגובה נשמר. כמו שאפשר לראות, המשתנה הזה ייגש בשלב מאוחר יותר באמצעות משתנה החילוץ המדיניות בנושא
• &lt;HTTPTargetConnection&gt; - מציין את כתובת אתר היעד של הקצה העורפי API. במקרה הזה, אנחנו מציינים שה-API מחזיר תגובת JSON.

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

<ExtractVariables name="ParseGeocodingResponse">
  <Source>GeocodingResponse</Source>
  <VariablePrefix>geocoderesponse</VariablePrefix>
  <JSONPayload>
    <Variable name="latitude">
       <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude">
       <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

הרכיבים העיקריים במדיניות CSVVariable הם:

• <חילוץVariables name> - שוב, שם המדיניות משמש כדי להתייחס למדיניות כאשר משתמשים בה בתהליך.
• &lt;Source&gt; - מציין את משתנה התגובה שיצרנו בו מדיניות ServiceCallout. זהו המשתנה שממנו המדיניות הזו שולפת נתונים.
• &lt;VariablePrefix&gt; - קידומת המשתנה מציינת מרחב שמות עבור משתנים אחרים שנוצרו במדיניות הזו. הקידומת יכולה להיות כל שם, חוץ מהטקסט השמור שמות שמוגדרים על ידי Edge משתנים מוגדרים מראש.
• &lt;JSONPayload&gt; - רכיב זה מאחזר את נתוני התגובה שמעניין אותנו ושמה אותו במשתנים בעלי שם. למעשה, Geocoding API מחזיר יותר מאשר קו רוחב וקו אורך. עם זאת, אלה הערכים היחידים שאנחנו צריכים בדוגמה הזו. אפשר לראות רינדור מלא של ה-JSON שמוחזר על ידי Geocoding API בממשקי API תיעוד. הערכים של geometry.location.lat ו-geometry.location.lng הם פשוט שניים מתוך השדות הרבים באובייקט JSON המוחזר.

זה אולי לא ברור מאליו, אבל חשוב לראות ש-CSV Variables מייצר משתנים שהשמות שלהם מכילים את תחילית המשתנה (georesponse) ואת שמות המשתנים שמצוינים במדיניות. המשתנים האלה מאוחסנים שרת ה-proxy ל-API, יהיה זמין לכללי מדיניות אחרים במסגרת תהליך ה-proxy, לראות. המשתנים הם:

• geocoderesponse.latitude
• geocoderesponse.longitude

רוב העבודה כבר הושלמה. יצרנו שילוב של שלושה כללי מדיניות שיוצרים מבקשים, מפעילים API לקצה עורפי ומנתחים את נתוני ה-JSON שהוחזרו. בשלבים האחרונים, נתונים מהחלק הזה של התהליך למדיניות AssignMessage אחרת, מפעילים את הקצה העורפי API (Google level API), ומחזירים את הנתונים המעובדים שלנו למפתח האפליקציה.

<AssignMessage name="AssignElevationParameters">
<Remove>
    <QueryParams>
      <QueryParam name="country"/>
      <QueryParam name="postalcode"/>
    </QueryParams>
  </Remove>
  <Set>
    <QueryParams>
      <QueryParam name="locations">{geocoderesponse.latitude},{geocoderesponse.longitude}</QueryParam>
      <QueryParam name="sensor">false</QueryParam>
    </QueryParams>
  </Set>
</AssignMessage>

אם תבדקו את Google Heightion API, תראו שהוא מקבל שני פרמטרים של שאילתה. הראשון נקרא locations והערך שלו הוא קו הרוחב וקו האורך (ערכים המופרדים בפסיקים). הפרמטר השני הוא sensor, והוא חובה יהיה נכון או לא נכון. הדבר שהכי חשוב לציין בשלב הזה הוא שהבקשה שאנחנו יוצרים כאן לא מחייבת ServiceCallout. אנחנו לא צריכים לקרוא לשנייה ל-API מ-ServiceCallout עליו בשלב הזה כי אנחנו יכולים לקרוא לממשק ה-API של הקצה העורפי נקודת קצה ביעד. אם חושבים על זה, יש לנו את כל הנתונים שדרושים לנו כדי לקרוא ל-Google Heights API להודעת הבקשה שנוצרה בשלב הזה לא נדרשת ServiceCallout, שנוצרה עבור צינור עיבוד הבקשות הראשי, ולכן פשוט תועבר על ידי ProxyEndpoint ל-TargetEndpoint, לאחר ה-RouteRule שהוגדר עבור שרת ה-proxy ל-API הזה. נקודת הקצה (TargetEndpoint) מנהלת את החיבור עם ה-API המרוחק. (חשוב לזכור שכתובת ה-URL של גובה ה-API מוגדר ב-HTTPConnection של TargetEndpoint. ממשק API של גובה אם תרצו לקבל מידע נוסף. ה-QueryParams שאחסנו קודם, אין יותר צורך ב-country וב-postalcode ולכן אנחנו מסירים אותם כאן.

השהיה קצרה: חזרה לזרימה

בשלב הזה, יכול להיות שתהיתם למה אנחנו לא יוצרים מדיניות נוספת של ServiceCallout. אחרי יצרנו הודעה נוספת. איך ההודעה נשלחת ליעד, liftion API? התשובה נמצאת ב-<RouteRule> של הזרימה. &lt;RouteRule&gt; מציין מה לעשות עם הודעות הבקשה שנותרו לאחר <Request> חלק מ- שהזרימה בוצעה. נקודת הקצה (TargetEndpoint) שצוינה על ידי <RouteRule> אומרת ל שרת proxy ל-API להעברת ההודעה אל http://maps.googleapis.com/maps/api/elevation/xml.

אם הורדתם את ה-Proxy ל-API לדוגמה, תוכלו למצוא בקובץ את ה-XML של TargetProxy doc-samples/policy-mashup-cookbook/apiproxy/targets/default.xml

<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <!-- This is where we define the target. For this sample we just use a simple URL. -->
    <URL>http://maps.googleapis.com/maps/api/elevation/xml</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

עכשיו צריך רק לעבד את התגובה מ-Google Elevation API בוצע.

$ curl "http://{myorg}-test.apigee.net/policy-mashup-cookbook?country=us&postalcode=08008"

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

{  
   "country":"us",
   "postalcode":"08008",
   "elevation":{  
      "meters":0.5045232,
      "feet":1.6552599030345978
   },
   "location":{  
      "latitude":39.75007129999999,
      "longitude":-74.1357407
   }
}

סיכום

נושא זה בספר המתכונים הזה מסביר כיצד להשתמש בתבנית הרכבה של המדיניות כדי ליצור mashup של נתונים מכמה מקורות קצה עורפי. הרכב המדיניות הוא דפוס נפוץ המשמש ב-API פיתוח proxy להוספת פונקציונליות של קריאייטיב ל-API.