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

<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 नाम का एक वैरिएबल बनाता है. यह वैरिएबल, अनुरोध वाले उस ऑब्जेक्ट को इकट्ठा करता है जिसे Service कॉलआउट नीति के तहत बैकएंड को भेजा जाएगा.
• <QueryParams> - यह बैकएंड एपीआई कॉल के लिए ज़रूरी क्वेरी पैरामीटर सेट करता है. इस मामले में, जियोकोडिंग एपीआई को जगह की जानकारी चाहिए, जिसे पिन कोड और देश आईडी से दिखाया जाता है. ऐप्लिकेशन का इस्तेमाल करने वाला व्यक्ति ही इस जानकारी को देता है और हमने इसे यहां से इकट्ठा किया है. एपीआई के लिए sensor पैरामीटर की ज़रूरत होती है और यह सही या गलत होता है. साथ ही, हमने यहां इसे 'गलत' पर हार्डकोड कर दिया है.
• <Verb> - इस मामले में, हम एपीआई को एक आसान जीईटी अनुरोध भेज रहे हैं.
• <AssignVariable> - ये वैरिएबल उन वैल्यू को स्टोर करते हैं जिन्हें हम एपीआई को पास करते हैं. इस उदाहरण में, क्लाइंट के रिस्पॉन्स के तौर पर वैरिएबल को बाद में ऐक्सेस किया जाएगा.

सेवा कॉलआउट की मदद से अनुरोध भेजें

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

अब हमारे पास दो नीतियां हैं, एक जो बैकएंड एपीआई (Google का जियोकोडिंग एपीआई) को इस्तेमाल करने के लिए ज़रूरी अनुरोध की जानकारी तय करती है और दूसरी, जो असल में बैकएंड एपीआई को अनुरोध भेजती है. इसके बाद, हम दिए गए जवाब को हैंडल करेंगे.

<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> - जब किसी फ़्लो में नीति का इस्तेमाल किया जाता है, तब नीति के नाम को उसका रेफ़रंस देने के लिए इस्तेमाल किया जाता है.
• <सोर्स> - इसकी मदद से, उस रिस्पॉन्स वैरिएबल की जानकारी मिलती है जिसे सर्विस कॉलआउट नीति में बनाया गया है. यह वह वैरिएबल है जिससे यह नीति डेटा इकट्ठा करती है.
• <VariablePrefix> - वैरिएबल प्रीफ़िक्स इस नीति में बनाए गए दूसरे वैरिएबल के लिए एक नेमस्पेस तय करता है. Edge के पहले से तय वैरिएबल से तय किए गए रिज़र्व नामों को छोड़कर, प्रीफ़िक्स कोई भी नाम हो सकता है.
• <JSONPayload> - यह एलिमेंट, हमारी पसंद के रिस्पॉन्स डेटा को शामिल करता है और इसे नाम वाले वैरिएबल में शामिल करता है. असल में, जियोकोडिंग एपीआई, अक्षांश और देशांतर की तुलना में ज़्यादा जानकारी देता है. हालांकि, इस सैंपल के लिए हमें सिर्फ़ इन वैल्यू की ज़रूरत है. एपीआई के दस्तावेज़ में, जियोकोडिंग एपीआई से मिले JSON की पूरी रेंडरिंग देखी जा सकती है. JSON ऑब्जेक्ट के दिए गए कई फ़ील्ड में से geo.location.lat और geo.location.lng की वैल्यू, सिर्फ़ दो हैं.

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

• geocoderesponse.latitude
• geocoderesponse.longitude

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

कुछ समय के लिए ठहराव: फ़्लो पर वापस जाएं

इस समय, आपको शायद यह पता चल सकता है कि हम एक और सेवा कॉलआउट नीति क्यों नहीं बना रहे हैं. इन सबके बाद, हमने एक और मैसेज तैयार किया है. यह मैसेज टारगेट, Google एलिवेशन एपीआई पर कैसे भेजा जाता है? फ़्लो के <Route बटन> एलिमेंट में इसका जवाब दिया गया है. <RouteTerms> में तय किया गया है कि फ़्लो के <Request> हिस्से के लागू होने के बाद, बचे हुए अनुरोध मैसेज का क्या करना है. इस <RouteTerms> में तय किया गया TargetEndpoint, एपीआई प्रॉक्सी को http://maps.googleapis.com/maps/api/elevation/xml को मैसेज डिलीवर करने के लिए कहता है.

अगर आपने सैंपल एपीआई प्रॉक्सी को डाउनलोड किया है, तो आपको फ़ाइल doc-samples/policy-mashup-cookbook/apiproxy/targets/default.xml में Targetप्रॉक्सी एक्सएमएल मिल सकता है.

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

खास जानकारी

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