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

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

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

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

הורדה של קוד לדוגמה והתנסות בו

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

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

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

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

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

$ 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 Cookbook.

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

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

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

זורמים עם המצב

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

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

השלב הבא ברצף של יצירת המדיניות הוא יצירת מדיניות ServiceCallout. מדיניות ServiceCallout, שמפורטת בהמשך, שולחת את אובייקט הבקשה שיצרנו במדיניות 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> – האלמנט הזה מציין שם של משתנה שבו התגובה מאוחסנת. כפי שתראו, המשתנה הזה יקבל גישה מאוחר יותר על ידי המדיניות ExtractVariables.
  • ‫<HTTPTargetConnection> – מציין את כתובת ה-URL של היעד של ה-API של ה-Backend. במקרה הזה, אנחנו מציינים שה-API יחזיר תגובה בפורמט JSON.

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

מנתחים את התשובה באמצעות ExtractVariables

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

כאן מופיעה רשימה של כללי המדיניות של ExtractVariables. מידע נוסף על המדיניות הזו זמין במאמר בנושא מדיניות Extract Variables. בקובץ ה-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 הם:

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

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

  • geocoderesponse.latitude
  • geocoderesponse.longitude

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

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

במדיניות AssignMessage הבאה נעשה שימוש במשתנים שהוחזרו מהקצה העורפי הראשון (Google Geocoding) שאחסנו, והם מוצבים בבקשה שמיועדת לממשק ה-API השני (Google Elevation). כמו שצוין קודם, המשתנים האלה הם geocoderesponse.latitude ו-geocoderesponse.longitude.

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

הפסקה קצרה: חזרה לתהליך

בשלב הזה, יכול להיות שתשאלו למה אנחנו לא יוצרים עוד מדיניות ServiceCallout. אחרי הכול, יצרנו הודעה נוספת. איך ההודעה הזו נשלחת ליעד, 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. כדי להוסיף עוד מדיניות ל-composite כדי להמיר את התגובה מ-XML ל-JSON, נשתמש ב-extra credit.

בדוגמה הזו נעשה שימוש במדיניות 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.