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

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

בנושא הזה נסביר איך ליצור שילוב (mashup) באמצעות הרכב מדיניות. הרכב המדיניות הוא תבנית של שרת proxy ב-Apigee שמאפשרת לשלב תוצאות ממספר יעדים בקצה העורפי בתגובה אחת באמצעות מדיניות.

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

מורידים את הקוד לדוגמה ומנסים אותו

מידע על הדוגמה הזו של ספר המתכונים הזה

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

בדוגמה שתיארנו נעשה שימוש בהרכב המדיניות כדי לשלב נתונים משני ממשקי ה-API הציבוריים הנפרדים האלה:

  • Google Geocoding API: ה-API הזה ממיר כתובות (כמו ' 1600 Amphitheatre Parkway, Mountain View, CA') לקואורדינטות גיאוגרפיות (כמו קו רוחב 37.423021 וקו אורך -122.083739).
  • Google Elevation API הזה הוא ממשק API פשוט שמאפשר להריץ שאילתות על מיקומים בכדור הארץ כדי לקבל נתוני גובה. בדוגמה הזו, הקואורדינטות שהוחזרו מה-Geocoding API ישמשו כקלט ל-API הזה.

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

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

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

{  
   "ElevationResponse":{  
      "status":"OK",
      "result":{  
         "location":{  
            "lat":"39.7500713",
            "lng":"-74.1357407"
         },
         "elevation":"0.5045232",
         "resolution":"76.3516159"
      }
   }
}

לפני שמתחילים

אפשר לקרוא סקירה קצרה של דפוס היצירה במדיניות בקטע 'דפוס היצירה של המדיניות' במאמר תבניות לעבודה עם ממשקי API בשרת Proxy.

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

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

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

ללכת בקצב

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

בהורדה לדוגמה אפשר למצוא את קובץ ה-XML הזה בקובץ doc-samples/policy-mashup-cookbook/apiproxy/proxies/default.xml.

<ProxyEndpoint name="default">
  <Flows>
    <Flow name="default">
      <Request>
            <!-- Generate request message for the Google Geocoding API -->
            <Step><Name>GenerateGeocodingRequest</Name></Step>
            <!-- Call the Google Geocoding API -->
            <Step><Name>ExecuteGeocodingRequest</Name></Step>
            <!-- Parse the response and set variables -->
            <Step><Name>ParseGeocodingResponse</Name></Step>
            <!-- Generate request message for the Google Elevation API -->
            <Step><Name>AssignElevationParameters</Name></Step>
      </Request>
      <Response>
            <!-- Parse the response message from the Elevation API -->
            <Step><Name>ParseElevationResponse</Name></Step>
            <!-- Generate the final JSON-formatted response with JavaScript -->
            <Step><Name>GenerateResponse</Name></Step>
      </Response>
    </Flow>
  </Flows>

  <HTTPProxyConnection>
    <!-- Add a base path to the ProxyEndpoint for URI pattern matching-->
    <BasePath>/policy-mashup-cookbook</BasePath>
    <!-- Listen on both HTTP and HTTPS endpoints -->
    <VirtualHost>default</VirtualHost>
    <VirtualHost>secure</VirtualHost>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <!-- Connect ProxyEndpoint to named TargetEndpoint under /targets -->
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

הנה סיכום של מרכיבי התהליך.

  • <Request> – הרכיב <Request> מורכב מכמה רכיבי <Step>. כל שלב נחשב לאחד מכללי המדיניות שניצור בהמשך הנושא הזה. כללי המדיניות האלה נועדו ליצור הודעת בקשה, לשלוח אותה ולנתח את התשובה. בסוף הנושא הזה תבינו מה התפקיד של כל אחד מכללי המדיניות האלה.
  • <Response> – הרכיב <Response> כולל גם <Steps>. השלבים האלה כוללים גם מדיניות קריאה, שאחראית לעיבוד התשובה הסופית מנקודת הקצה של היעד (Google Elevation API).
  • <HttpProxyConnection> – הרכיב הזה מציין פרטים על האופן שבו אפליקציות יתחברו לשרת ה-API הזה, כולל ה-<BasePath>, שמציין איך ייקרא ה-API הזה.
  • <RouteRule> - רכיב זה מציין מה יקרה מיד לאחר העיבוד של הודעות הבקשה הנכנסות. במקרה הזה, מתבצעת קריאה ל-TargetEndpoint. נדון בשלב חשוב זה בהרחבה בהמשך נושא זה.

יצירת המדיניות

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

יצירת המדיניות הראשונה ל-assignMessage

במדיניות הראשונה של AssignMessage שמופיעה למטה, נוצרת הודעת בקשה שתישלח לשירות הקידוד הגיאוגרפי של Google.

נתחיל עם קוד המדיניות, ולאחר מכן נסביר את הרכיבים שלו בפירוט רב יותר. בהורדה לדוגמה אפשר למצוא את קובץ ה-XML הזה בקובץ doc-samples/policy-mashup-cookbook/apiproxy/policies/GenerateGeocodingRequest.xml.

<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> - נותן שם למדיניות הזו. השם משמש כשיש הפניה למדיניות בתהליך.
  • <AssignTo> – יוצר משתנה בעל שם שנקרא GeocodingRequest. המשתנה הזה כולל את אובייקט הבקשה שיישלח לקצה העורפי על ידי המדיניות 'יתרונות יתרונות מרכזיים'.
  • <QueryParams> – הגדרת הפרמטרים של השאילתה הדרושים לקריאה ל-API בקצה העורפי. במקרה כזה, ה-Geocoding API צריך לדעת את המיקום, שמצוין באמצעות מיקוד ומזהה מדינה. המשתמש באפליקציה מספק את המידע הזה, ואנחנו פשוט מחלצים אותו כאן. הפרמטר sensor נדרש על ידי ה-API, והפרמטר יכול להיות True או False, וכאן תזינו אותו בתוך הקוד כ-FALSE.
  • <Verb> - במקרה זה, אנחנו שולחים בקשת GET פשוטה ל-API.
  • <AssignVariable> – המשתנים האלה מאחסנים את הערכים שאנחנו מעבירים ל-API. בדוגמה הזו, אפשר לגשת למשתנים מאוחר יותר בתגובה שתוחזר ללקוח.

שליחת הבקשה באמצעות ServiceCallout

השלב הבא ברצף של יצירת המדיניות הוא יצירת מדיניות מסוג ServiceCallout. המדיניות בנושא Serviceיתרונות המרכזיים, שמפורטת בהמשך, שולחת את אובייקט הבקשה שיצרנו במדיניות assignMessage הקודמת אל שירות הקידוד הגיאוגרפי של Google, ושומרת את התוצאה במשתנה שנקרא GeocodingResponse.

כמו קודם, בואו נסתכל קודם על הקוד. לפניכם הסבר מפורט. אפשר לקרוא מידע נוסף על המדיניות הזו במדיניות בנושא יתרונות מרכזיים של שירות. בהורדה לדוגמה אפשר למצוא את קובץ ה-XML הזה בקובץ doc-samples/policy-mashup-cookbook/apiproxy/policies/ExecuteGeocodingRequest.xml.

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

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

  • <ServiceCallout> – כמו במדיניות הקודמת, גם למדיניות הזו יש שם.
  • <Request variable> - זהו המשתנה שנוצר במדיניות assignMessage. היא כוללת את הבקשה שעוברת לממשק ה-API לקצה העורפי.
  • <Response> – הרכיב הזה מציין משתנה שבו מאוחסנת התגובה. כמו שרואים, אפשר יהיה לגשת למשתנה הזה מאוחר יותר דרך המדיניות tractVariables.
  • <HTTPTargetConnection> - מציין את כתובת אתר היעד של ממשק ה-API לקצה העורפי. במקרה זה, נציין שה-API יחזיר תגובת JSON.

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

ניתוח התגובה באמצעות tractVariables

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

זוהי רשימה של המדיניות בנושא חילוץ משתנים. אפשר לקרוא מידע נוסף על המדיניות הזו במדיניות לחילוץ משתנים. בהורדה לדוגמה אפשר למצוא את קובץ ה-XML הזה בקובץ doc-samples/policy-mashup-cookbook/apiproxy/policies/ParseGeocodingResponse.xml.

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

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

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

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

  • geocoderesponse.latitude
  • geocoderesponse.longitude

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

יצירת הבקשה השנייה באמצעות assignMessage

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

בהורדה לדוגמה אפשר למצוא את קובץ ה-XML הזה בקובץ doc-samples/policy-mashup-cookbook/apiproxy/policies/AssignElevationParameters.xml.

<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 Elevation API, תראו שהוא משתמש בשני פרמטרים של שאילתות. הערך הראשון נקרא locations והערך שלו הוא קווי הרוחב והאורך (ערכים מופרדים בפסיקים). הפרמטר השני הוא sensor, זהו פרמטר נדרש וחייב להיות מוגדר כ-true או כ-false. הדבר החשוב ביותר שצריך לדעת בשלב הזה הוא שהודעת הבקשה שאנחנו יוצרים כאן לא מחייבת שימוש ב-Service יתרונות מרכזיים. בשלב הזה אנחנו לא צריכים לקרוא ל-API השני מ-ServiceCallout, כי אנחנו יכולים לקרוא ל-API של הקצה העורפי מ-TargetEndpoint של שרת ה-proxy. אם תחשבו על זה, יש לנו את כל הנתונים שדרושים לנו כדי לקרוא ל-Google Elevations API. הודעת הבקשה שנוצרת בשלב הזה לא דורשת 'יתרונות מרכזיים', כי הבקשה נוצרת לצינור עיבוד הנתונים הראשי, ולכן היא פשוט תועבר על ידי ProxyEndpoint אל TargetEndpoint בהתאם ל-RouteRule שהוגדר עבור שרת ה-proxy הזה של ה-API. TargetEndpoint מנהל את החיבור עם ה-API המרוחק. (חשוב לזכור שכתובת ה-URL של ממשק ה-API של הגובה מוגדרת ב-HTTPConnection עבור TargetEndpoint. למידע נוסף, אפשר לעיין במסמכי התיעוד בנושא Elevation API. אין יותר צורך בקובצי QueryParams שאחסנו בעבר, country ו-postalcode, ולכן אנחנו מסירים אותם כאן.

השהיה קצרה: חזרה לתהליך

בשלב זה, ייתכן שתהית למה אנו לא יוצרים מדיניות נוספת בנושא יתרונות מרכזיים של שירות. אחרי הכול, יצרנו הודעה נוספת. איך ההודעה הזו נשלחת אל היעד, Google Elevation API? התשובה נמצאת ברכיב <RouteRule> של הזרימה. החלק <RouteRule> מציין מה לעשות עם הודעות הבקשה שנותרו אחרי שהחלק <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, וזהו.

המרת התגובה מ-XML ל-JSON

בדוגמה הזו, התגובה מ-Google Elevation API מוחזרת בפורמט XML. כדי לקבל 'קרדיט נוסף', נוסיף עוד מדיניות לרכיב שלנו כדי לשנות את התשובה מ-XML ל-JSON.

בדוגמה הזו, כדי לבצע את ההמרה, נעשה שימוש במדיניות JavaScript בשם GenerateResponse, עם קובץ משאבים שמכיל את קוד ה-JavaScript. למטה מוצגת הגדרת המדיניות GenerateResponse:

<Javascript name="GenerateResponse" timeout="10000">
  <ResourceURL>jsc://GenerateResponse.js</ResourceURL>
</Javascript>

קובץ המשאבים GenerateResponse.js כולל את קוד ה-JavaScript המשמש לביצוע ההמרה. הקוד מופיע בקובץ doc-samples/policy-mashup-cookbook/apiproxy/resources/JSC/GenerateResponse.js.

Apigee מספקת גם מדיניות מוכנה מראש, XMLToJSON, כדי להמיר XML ל-JSON. אפשר לערוך את ProxyEndpoint לשימוש במדיניות xmltojson שמוצגת למטה במקום זאת. 

<XMLToJSON name="xmltojson">
  <Options>
  </Options>
  <OutputVariable>response</OutputVariable>
  <Source>response</Source>
</XMLToJSON>

בדיקת הדוגמה

אם עדיין לא עשית זאת, מומלץ להוריד, לפרוס ולהריץ את הדוגמה של policy-mashup-cookbook, שנמצאת בתיקייה doc-samples במאגר הדוגמאות של Apigee Edge ב-GitHub. פשוט צריך לפעול לפי ההוראות בקובץ ה-README שבתיקייה policy-mashup-cookbook. לחלופין, אפשר לפעול לפי ההוראות הקצרות שכאן: שימוש בשרתי ה-proxy לדוגמה של API.

לסיכום, ניתן לקרוא ל-API המורכב באופן הבא. מחליפים את {myorg} בשם הארגון:

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

סיכום

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