पॉलिसी कंपोज़िशन का इस्तेमाल करना

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

यहां इस नीति में शामिल एलिमेंट की खास जानकारी दी गई है. Assign Message नीति में, इस नीति के बारे में ज़्यादा जानकारी दी गई है.

• <AssignMessage name> - इस नीति को एक नाम देता है. जब किसी फ़्लो में नीति का रेफ़रंस दिया जाता है, तब इस नाम का इस्तेमाल किया जाता है.
• <AssignTo> - GeocodingRequest नाम का एक वैरिएबल बनाता है. इस वैरिएबल में, अनुरोध ऑब्जेक्ट शामिल होता है. इसे ServiceCallout नीति की मदद से, बैकएंड को भेजा जाएगा.
• <QueryParams> - क्वेरी पैरामीटर सेट करता है. इनकी ज़रूरत, बैकएंड एपीआई कॉल के लिए होती है. इस मामले में, Geocoding API को जगह की जानकारी चाहिए. इसे डाक कोड और देश के आईडी से दिखाया जाता है. ऐप्लिकेशन का उपयोगकर्ता यह जानकारी देता है. हम यहां सिर्फ़ इसे एक्सट्रैक्ट करते हैं. एपीआई के लिए, sensor पैरामीटर ज़रूरी है. इसकी वैल्यू सही या गलत हो सकती है. हम यहां इसे सिर्फ़ गलत पर हार्डकोड करते हैं.
• <Verb> - इस मामले में, हम एपीआई को एक सामान्य GET अनुरोध भेज रहे हैं.
• <AssignVariable> - इन वैरिएबल में, वे वैल्यू सेव होती हैं जिन्हें हम एपीआई को पास कर रहे हैं. इस उदाहरण में, वैरिएबल को बाद में, क्लाइंट को भेजे गए रिस्पॉन्स में ऐक्सेस किया जाएगा.

ServiceCallout की मदद से अनुरोध भेजना

नीति कंपोज़िशन के क्रम में अगला चरण, ServiceCallout नीति बनाना है. नीचे दी गई ServiceCallout नीति, अनुरोध ऑब्जेक्ट को Google Geocoding सेवा को भेजती है. यह ऑब्जेक्ट, हमने पिछली AssignMessage नीति में बनाया था. साथ ही, नतीजे को GeocodingResponse नाम के वैरिएबल में सेव करती है.

<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 नीति में बनाया गया था. इसमें, बैकएंड एपीआई को भेजा जाने वाला अनुरोध शामिल होता है.
• <Response> - इस एलिमेंट में, उस वैरिएबल का नाम दिया जाता है जिसमें रिस्पॉन्स सेव होता है. जैसा कि आपको दिखेगा, इस वैरिएबल को बाद में, ExtractVariables नीति से ऐक्सेस किया जाएगा.
• <HTTPTargetConnection> - बैकएंड एपीआई का टारगेट यूआरएल तय करता है. इस मामले में, हम यह तय करते हैं कि एपीआई, JSON रिस्पॉन्स दिखाए.

अब हमारे पास दो नीतियां हैं. पहली नीति में, बैकएंड एपीआई (Google का Geocoding 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>

ExtractVariable नीति के मुख्य एलिमेंट ये हैं:

• <ExtractVariables name> - नीति के नाम का इस्तेमाल, किसी फ़्लो में नीति का रेफ़रंस देने के लिए किया जाता है.
• <Source> - उस रिस्पॉन्स वैरिएबल को तय करता है जिसे हमने ServiceCallout नीति में बनाया था. यह वह वैरिएबल है जिससे यह नीति, डेटा एक्सट्रैक्ट करती है.
• <VariablePrefix> - वैरिएबल प्रीफ़िक्स, इस नीति में बनाए गए अन्य वैरिएबल के लिए नेमस्पेस तय करता है. प्रीफ़िक्स कोई भी नाम हो सकता है. हालांकि, Edge's पहले से तय वैरिएबल में तय किए गए रिज़र्व नाम नहीं होने चाहिए.
• <JSONPayload> - यह एलिमेंट, रिस्पॉन्स डेटा को वापस पाता है. यह डेटा हमारे लिए काम का है. साथ ही, इसे नाम वाले वैरिएबल में डालता है. दरअसल, Geocoding API, अक्षांश और देशांतर के अलावा भी कई तरह की जानकारी दिखाता है. हालांकि, इस सैंपल के लिए हमें सिर्फ़ इन वैल्यू की ज़रूरत है. Geocoding API से मिले JSON को पूरी तरह से रेंडर किया गया वर्शन, एपीआई के दस्तावेज़ में देखा जा सकता है. geometry.location.lat और geometry.location.lng की वैल्यू, मिले JSON ऑब्जेक्ट में मौजूद कई फ़ील्ड में से सिर्फ़ दो हैं.

यह साफ़ तौर पर नहीं दिख सकता, लेकिन यह देखना ज़रूरी है कि ExtractVariables, दो वैरिएबल बनाता है. इनके नाम में वैरिएबल प्रीफ़िक्स (geocoderesponse) और नीति में तय किए गए असली वैरिएबल के नाम शामिल होते हैं. ये वैरिएबल, एपीआई प्रॉक्सी में सेव होते हैं और प्रॉक्सी फ़्लो में मौजूद अन्य नीतियों के लिए उपलब्ध होंगे. जैसा कि आपको दिखेगा. ये वैरिएबल हैं:

• geocoderesponse.latitude
• geocoderesponse.longitude

अब ज़्यादातर काम हो चुका है. हमने तीन नीतियों का एक कंपोज़िट बनाया है. यह कंपोज़िट, अनुरोध बनाता है , बैकएंड एपीआई को कॉल करता है, और मिले JSON डेटा को पार्स करता है. आखिरी चरणों में, हम फ़्लो के इस हिस्से से डेटा को दूसरी AssignMessage नीति में डालेंगे. इसके बाद, दूसरे बैकएंड एपीआई (Google Elevation 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 Elevation API की जांच की जाए, तो आपको दिखेगा कि इसमें दो क्वेरी पैरामीटर इस्तेमाल किए जाते हैं. पहले पैरामीटर को locations कहा जाता है. इसकी वैल्यू, अक्षांश और देशांतर (कॉमा से अलग की गई वैल्यू) होती है. दूसरा पैरामीटर sensor है. यह ज़रूरी है और इसकी वैल्यू सही या गलत होनी चाहिए. इस समय ध्यान देने वाली सबसे अहम बात यह है कि यहां बनाए गए अनुरोध मैसेज के लिए, ServiceCallout की ज़रूरत नहीं होती. इस समय, हमें दूसरे एपीआई को ServiceCallout से कॉल करने की ज़रूरत नहीं है, क्योंकि हम प्रॉक्सी के TargetEndpoint से बैकएंड एपीआई को कॉल कर सकते हैं. अगर इस बारे में सोचा जाए, तो हमारे पास Google Elevations API को कॉल करने के लिए ज़रूरी सभी डेटा मौजूद है. इस चरण में जनरेट किए गए अनुरोध मैसेज के लिए, ServiceCallout की ज़रूरत नहीं होती. ऐसा इसलिए, क्योंकि मुख्य अनुरोध पाइपलाइन के लिए जनरेट किए गए अनुरोध को, इस एपीआई प्रॉक्सी के लिए कॉन्फ़िगर किए गए RouteRule के मुताबिक, ProxyEndpoint से TargetEndpoint को फ़ॉरवर्ड किया जाएगा. TargetEndpoint, रिमोट एपीआई के साथ कनेक्शन को मैनेज करता है. (याद रखें कि Elevation API का यूआरएल, TargetEndpoint के लिए HTTPConnection में तय किया गया है. ज़्यादा जानने के लिए, Elevation API का दस्तावेज़ देखें. हमने पहले जो QueryParams सेव किए थे, country और postalcode, उनकी अब ज़रूरत नहीं है. इसलिए, हम उन्हें यहां से हटा देते हैं हैं.

कुछ देर के लिए रुकें: फ़्लो पर वापस जाएं

इस समय, आपको लग सकता है कि हम दूसरी ServiceCallout नीति क्यों नहीं बना रहे हैं. आखिरकार, हमने एक और मैसेज बनाया है. वह मैसेज, टारगेट यानी Google Elevation API को कैसे भेजा जाता है? इसका जवाब, फ़्लो के <RouteRule> एलिमेंट में है. <RouteRule> में यह तय किया जाता है कि फ़्लो के <Request> हिस्से के लागू होने के बाद, बचे हुए अनुरोध मैसेज के साथ क्या करना है. इस <RouteRule> में तय किया गया TargetEndpoint, एपीआई प्रॉक्सी को मैसेज, http://maps.googleapis.com/maps/api/elevation/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"

रिस्पॉन्स में, ऐप्लिकेशन के असली उपयोगकर्ता की ओर से दिए गए पिन कोड वाले इलाके के बीचोंबीच की जियोकोड की गई जगह के साथ-साथ, उस जियोकोड की गई जगह की ऊंचाई की जानकारी शामिल होती है. यह डेटा, दो बैकएंड एपीआई से वापस पाया गया था. इसे एपीआई प्रॉक्सी से जुड़ी नीतियों की मदद से मैशअप किया गया था. साथ ही, क्लाइंट को एक ही रिस्पॉन्स में वापस भेजा गया था.

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

खास जानकारी

कुकबुक के इस विषय में, नीति कंपोज़िशन पैटर्न का इस्तेमाल करके, एक से ज़्यादा बैकएंड सोर्स से डेटा को मैशअप करने का तरीका बताया गया है. नीति कंपोज़िशन, एपीआई प्रॉक्सी डेवलपमेंट में इस्तेमाल किया जाने वाला एक सामान्य पैटर्न है. इसका इस्तेमाल, अपने एपीआई में क्रिएटिव फ़ंक्शनैलिटी जोड़ने के लिए किया जाता है.