Places API वेब सेवाओं का इस्तेमाल करने के सबसे सही तरीके

Google Maps Platform वेब सेवाएं, Google की सेवाओं के लिए एचटीटीपी इंटरफ़ेस का संग्रह है. ये सेवाएं आपके मैप ऐप्लिकेशन का भौगोलिक डेटा उपलब्ध कराती हैं.

इस गाइड में कुछ ऐसे सामान्य तरीकों के बारे में बताया गया है जो वेब सेवा के अनुरोधों को सेट अप करने और सेवा से मिले जवाबों को प्रोसेस करने में मदद करते हैं. Places API के पूरे दस्तावेज़ के लिए डेवलपर की गाइड देखें.

वेब सेवा क्या है?

Google Maps Platform की वेब सेवाएं एक इंटरफ़ेस है. इसकी मदद से बाहरी सेवाओं से Maps API का डेटा मांगा जा सकता है. साथ ही, इस इंटरफ़ेस के डेटा को Maps ऐप्लिकेशन में इस्तेमाल किया जा सकता है. इन सेवाओं को मैप के साथ इस्तेमाल करने के लिए डिज़ाइन किया गया है. ऐसा Google Maps Platform की सेवा की शर्तों में दिए गए लाइसेंस से जुड़ी पाबंदियों के मुताबिक किया गया है.

Maps API की वेब सेवाएं, खास यूआरएल के लिए एचटीटीपी या एचटीटीपीएस अनुरोधों का इस्तेमाल करती हैं. ये सेवाएं, यूआरएल पैरामीटर और/या JSON फ़ॉर्मैट वाले POST डेटा को सेवाओं के लिए तर्क के तौर पर पास करती हैं. आम तौर पर, ये सेवाएं आपके ऐप्लिकेशन के हिसाब से पार्स और/या प्रोसेस करने के लिए, रिस्पॉन्स के मुख्य हिस्से में JSON या एक्सएमएल के तौर पर डेटा दिखाती हैं.

सामान्य Places API अनुरोध आम तौर पर इस तरह का होता है:

https://places.googleapis.com/v1/places/PLACE_ID?parameters

ध्यान दें: सभी Places API ऐप्लिकेशन के लिए पुष्टि करना ज़रूरी है. पुष्टि करने के क्रेडेंशियल के बारे में ज़्यादा जानकारी पाएं.

एसएसएल/TLS ऐक्सेस

Google Maps Platform के उन सभी अनुरोधों के लिए एचटीटीपीएस ज़रूरी है जो एपीआई कुंजियों का इस्तेमाल करते हैं या जिनमें उपयोगकर्ता डेटा शामिल होता है. संवेदनशील जानकारी वाले एचटीटीपी पर किए गए अनुरोध अस्वीकार किए जा सकते हैं.

मान्य यूआरएल बनाना

आपको लग सकता है कि "मान्य" यूआरएल अपने-आप दिख रहा है, लेकिन ऐसा नहीं है. उदाहरण के लिए, किसी ब्राउज़र के पता बार में डाले गए यूआरएल में खास वर्ण हो सकते हैं (जैसे कि "上海+中國"); ब्राउज़र को ट्रांसमिशन से पहले, उन वर्णों को किसी दूसरी एन्कोडिंग में अनुवाद करने की ज़रूरत होती है. इसी टोकन से, UTF-8 इनपुट जनरेट करने वाला या स्वीकार करने वाला कोई भी कोड, UTF-8 वर्णों वाले यूआरएल को "मान्य" मान सकता है, लेकिन आपको वेब सर्वर पर भेजने से पहले उन वर्णों का अनुवाद भी करना होगा. इस प्रोसेस को यूआरएल-एन्कोडिंग या प्रतिशत-एन्कोडिंग कहा जाता है.

खास वर्ण

हमें खास वर्णों का अनुवाद करना होगा, क्योंकि सभी यूआरएल यूनिफ़ॉर्म रिसॉर्स आइडेंटिफ़ायर (यूआरआई) स्पेसिफ़िकेशन में बताए गए सिंटैक्स के मुताबिक होने चाहिए. इसका मतलब है कि यूआरएल में ASCII वर्णों का सिर्फ़ एक खास सबसेट शामिल होना चाहिए: यूआरएल में कंट्रोल वर्णों के तौर पर इस्तेमाल करने के लिए, जाने-पहचाने अक्षर और अंक, और कुछ रिज़र्व वर्ण. इस टेबल में इन वर्णों को शामिल किया गया है:

यूआरएल के मान्य वर्णों की खास जानकारी
सेट करेंवर्णयूआरएल का इस्तेमाल
अक्षर और अंक दोनों शामिल हो सकते हैं ए b c d x x x CANNOT TRANSLATE टेक्स्ट स्ट्रिंग, स्कीम का इस्तेमाल (http), पोर्ट (8080) वगैरह.
गैर-आरक्षित - _ . ~ टेक्स्ट स्ट्रिंग
बुकिंग की गई ! * ' ( ) ; : @ & = + $ , / ? % # [ ] कंट्रोल वर्ण और/या टेक्स्ट स्ट्रिंग

मान्य यूआरएल बनाते समय, आपको यह पक्का करना होगा कि इसमें सिर्फ़ वही वर्ण शामिल हों जो मान्य यूआरएल वर्णों की खास जानकारी वाली टेबल में दिए गए हैं. वर्णों के इस सेट का इस्तेमाल करने के लिए यूआरएल तैयार करने से, आम तौर पर दो समस्याएं होती हैं. पहला: आइटम को हटा दें और दूसरा विकल्प:

  • आपको जिन वर्णों को मैनेज करना है वे ऊपर दिए गए सेट से बाहर के होते हैं. उदाहरण के लिए, 上海+中國 जैसी विदेशी भाषा के वर्णों को ऊपर दिए गए वर्णों का इस्तेमाल करके कोड में बदलना होगा. लोकप्रिय तौर-तरीकों के मुताबिक, स्पेस को अक्सर प्लस '+' वर्ण का इस्तेमाल करके दिखाया जाता है. यूआरएल में इनकी अनुमति नहीं है.
  • ऊपर दिए गए सेट में वर्ण, रिज़र्व किए गए वर्णों के तौर पर मौजूद होते हैं, लेकिन लिटरल तौर पर इस्तेमाल किए जाने चाहिए. उदाहरण के लिए, क्वेरी स्ट्रिंग की शुरुआत के लिए यूआरएल में ? का इस्तेमाल किया जाता है. अगर आपको स्ट्रिंग "? और मिस्टीरियन" इस्तेमाल करनी है, तो आपको '?' वर्ण को कोड में बदलना होगा.

यूआरएल के लिए कोड में बदलने के लिए सभी वर्णों को UTF-8 वर्ण से मेल खाने वाले '%' वर्ण और दो वर्ण वाले हेक्स मान का इस्तेमाल करके एन्कोड किया जाता है. उदाहरण के लिए, UTF-8 में 上海+中國 को %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B के तौर पर यूआरएल कोड में बदला जाएगा. स्ट्रिंग ? and the Mysterians को यूआरएल के तौर पर %3F+and+the+Mysterians या %3F%20and%20the%20Mysterians के तौर पर एन्कोड किया जाएगा.

ऐसे सामान्य वर्ण जिन्हें कोड में बदलने की ज़रूरत होती है

कोड में बदले जाने वाले कुछ सामान्य वर्ण यहां दिए गए हैं:

असुरक्षित वर्ण कोड में बदला गया मान
स्पेस %20
" %22
< %3C
> %3E
# %23
% %25
| %7C

उपयोगकर्ता के इनपुट से मिलने वाले यूआरएल को बदलना, कभी-कभी मुश्किल होता है. उदाहरण के लिए, कोई उपयोगकर्ता किसी पते को "5th&Main St" के रूप में डाल सकता है. आम तौर पर, आपको अपने यूआरएल को उसके हिस्सों से बनाना चाहिए. ऐसा करते हुए किसी भी उपयोगकर्ता के इनपुट को लिटरल वर्ण माना जाना चाहिए.

इसके अलावा, Google Maps Platform की सभी वेब सेवाओं और स्टैटिक वेब एपीआई के लिए, यूआरएल में 16384 से ज़्यादा वर्ण नहीं हो सकते. ज़्यादातर सेवाओं के लिए, इस वर्ण सीमा पर शायद ही कभी संपर्क किया जाए. हालांकि, ध्यान रखें कि कुछ सेवाओं में कई पैरामीटर होते हैं, जिनकी वजह से यूआरएल लंबे हो सकते हैं.

Google API का विनम्र उपयोग

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

घातांकीय बैकऑफ़

बहुत कम मामलों में ऐसा हो सकता है कि आपके अनुरोध को पूरा करने में कोई गड़बड़ी हो. आपको 4XX या 5XX का एचटीटीपी रिस्पॉन्स कोड मिल सकता है. इसके अलावा, यह भी हो सकता है कि आपके क्लाइंट और Google सर्वर के बीच टीसीपी कनेक्शन काम न करे. आम तौर पर, फिर से अनुरोध करना सही होता है, क्योंकि फ़ॉलोअप अनुरोध पूरा हो सकता है. ऐसा तब होता है, जब ओरिजनल अनुरोध पूरा न हो. हालांकि, यह ज़रूरी है कि Google के सर्वर से बार-बार लूप अनुरोध न किया जाए. लूप का यह व्यवहार, आपके क्लाइंट और Google के बीच के नेटवर्क को ओवरलोड कर सकता है. इससे कई पक्षों को समस्याएं हो सकती हैं.

एक बेहतर तरीका यह है कि कोशिश करने के बीच के समय में ज़्यादा से ज़्यादा देरी करें. आम तौर पर, हर बार कोशिश करने पर यह देरी बढ़ जाती है. इसे एक्सपोनेंशियल बैकऑफ़ कहा जाता है.

उदाहरण के लिए, एक ऐसा ऐप्लिकेशन चुनें जो टाइम ज़ोन एपीआई से यह अनुरोध करना चाहता है:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

Python के इस उदाहरण में, एक्स्पोनेंशियल बैकऑफ़ के साथ अनुरोध करने का तरीका बताया गया है:

import json
import time
import urllib.error
import urllib.parse
import urllib.request

# The maps_key defined below isn't a valid Google Maps API key.
# You need to get your own API key.
# See https://developers.google.com/maps/documentation/timezone/get-api-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"


def timezone(lat, lng, timestamp):

    # Join the parts of the URL together into one string.
    params = urllib.parse.urlencode(
        {"location": f"{lat},{lng}", "timestamp": timestamp, "key": API_KEY,}
    )
    url = f"{TIMEZONE_BASE_URL}?{params}"

    current_delay = 0.1  # Set the initial retry delay to 100ms.
    max_delay = 5  # Set the maximum retry delay to 5 seconds.

    while True:
        try:
            # Get the API response.
            response = urllib.request.urlopen(url)
        except urllib.error.URLError:
            pass  # Fall through to the retry loop.
        else:
            # If we didn't get an IOError then parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors cannot be fixed by a retry, e.g. INVALID_REQUEST or
                # ZERO_RESULTS. There is no point retrying these requests.
                raise Exception(result["error_message"])

        if current_delay > max_delay:
            raise Exception("Too many retry attempts.")

        print("Waiting", current_delay, "seconds before retrying.")

        time.sleep(current_delay)
        current_delay *= 2  # Increase the delay each time we retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

आपको इस बात का भी ध्यान रखना चाहिए कि ऐप्लिकेशन कॉल चेन में कोई ऐसा कोड नहीं है जो बाद में हो, जिससे एक के बाद एक बार-बार अनुरोध किए जाते हैं.

सिंक किए गए अनुरोध

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

उदाहरण के लिए, किसी ऐसे ऐप्लिकेशन पर ध्यान दें जो मौजूदा टाइम ज़ोन में समय दिखाता हो. यह ऐप्लिकेशन शायद क्लाइंट ऑपरेटिंग सिस्टम में, ऐप्लिकेशन को मिनट की शुरुआत में चालू करके एक अलार्म सेट कर देगा, ताकि दिखाए गए समय को अपडेट किया जा सके. ऐप्लिकेशन को उस अलार्म से जुड़ी प्रोसेसिंग के तहत, कोई भी एपीआई कॉल नहीं करना चाहिए.

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

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

मिनट की शुरुआत के अलावा, सिंक करने के दूसरे सामान्य समय पर आपको ध्यान देना नहीं चाहिए कि टारगेट एक घंटे की शुरुआत से किया जाए और हर दिन की आधी रात को.

जवाब प्रोसेस किए जा रहे हैं

इस सेक्शन में बताया गया है कि वेब सर्विस रिस्पॉन्स से डाइनैमिक तौर पर इन वैल्यू को कैसे एक्सट्रैक्ट किया जा सकता है.

Google Maps की वेब सेवाएं ऐसे जवाब देती हैं जो समझने में आसान होते हैं, लेकिन उपयोगकर्ता के लिए आसान नहीं होते. डेटा का सेट दिखाने के बजाय क्वेरी करते समय, हो सकता है कि आप कुछ खास वैल्यू निकालना चाहें. आम तौर पर, आपको वेब सेवा से मिलने वाले जवाबों को पार्स करना होगा और सिर्फ़ अपनी पसंद की वैल्यू को एक्सट्रैक्ट करना होगा.

इस्तेमाल की जाने वाली पार्स करने की स्कीम, इस बात पर निर्भर करती है कि एक्सएमएल में आउटपुट दिखाया जा रहा है या JSON में. JSON जवाब, जो पहले से ही JavaScript ऑब्जेक्ट के रूप में होते हैं, उन्हें क्लाइंट में ही JavaScript में प्रोसेस किया जा सकता है. एक्सएमएल के जवाबों को एक्सएमएल प्रोसेसर और एक्सएमएल क्वेरी लैंग्वेज का इस्तेमाल करके प्रोसेस किया जाना चाहिए, ताकि एक्सएमएल फ़ॉर्मैट में एलिमेंट को ठीक किया जा सके. हम नीचे दिए गए उदाहरणों में XPath का इस्तेमाल करते हैं, क्योंकि यह आम तौर पर एक्सएमएल प्रोसेसिंग लाइब्रेरी में काम करता है.

एक्सएमएल के साथ एक्सएमएल को प्रोसेस किया जा रहा है

एक्सएमएल, डेटा इंटरचेंज के लिए इस्तेमाल किया जाने वाला जानकारी का एक वयस्कों के लिए बना फ़ॉर्मैट है. हालांकि, यह JSON जितना हल्का नहीं है, लेकिन एक्सएमएल फ़ाइल को ज़्यादा भाषा में इस्तेमाल किया जा सकता है और इसके टूल भी बेहतर हैं. उदाहरण के लिए, Java में एक्सएमएल प्रोसेस करने के लिए कोड, javax.xml पैकेज में मौजूद होता है.

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

एक्सएमएल एक्सप्रेशन

XPath के बारे में कुछ जानकारी होने से, एक मज़बूत पार्सिंग स्कीम बनाने में काफ़ी मदद मिलती है. यह सेक्शन इस बारे में फ़ोकस करेगा कि एक्सएमएल दस्तावेज़ में मौजूद एलिमेंट को XPath के साथ कैसे ठीक किया जाता है. इससे आपको कई एलिमेंट को ठीक करने और मुश्किल क्वेरी बनाने में मदद मिलेगी.

एक्सएमएल दस्तावेज़ में एलिमेंट चुनने के लिए, एक्सप्रेशन का इस्तेमाल करता है. इसके लिए, वह डायरेक्ट्री पाथ में इस्तेमाल होने वाले सिंटैक्स का इस्तेमाल करता है. ये एक्सप्रेशन, एक्सएमएल डॉक्यूमेंट ट्री में एलिमेंट की पहचान करते हैं. यह डीओएम की तरह ही हैरारकी ट्री है. आम तौर पर, XPath एक्सप्रेशन में रुचि होती है. इससे पता चलता है कि वे दिए गए मानदंड से मेल खाने वाले सभी नोड से मेल खाएंगे.

हम अपने उदाहरण दिखाने के लिए नीचे दिए गए एब्सट्रैक्ट एक्सएमएल का इस्तेमाल करेंगे:

<WebServiceResponse>
 <status>OK</status>
 <result>
  <type>sample</type>
  <name>Sample XML</name>
  <location>
   <lat>37.4217550</lat>
   <lng>-122.0846330</lng>
  </location>
 </result>
 <result>
  <message>The secret message</message>
 </result>
</WebServiceResponse>

एक्सप्रेशन में नोड चुनना

एक्सएमएल के विकल्प के तौर पर नोड चुने जाते हैं. रूट नोड में पूरा दस्तावेज़ होता है. आपने खास एक्सप्रेशन "/" का इस्तेमाल करके यह नोड चुना है. ध्यान दें कि रूट नोड आपके एक्सएमएल दस्तावेज़ का टॉप-लेवल नोड नहीं है; असल में, यह इस टॉप-लेवल एलिमेंट से एक लेवल ऊपर रहता है और इसे शामिल करता है.

एलिमेंट नोड, एक्सएमएल दस्तावेज़ ट्री में कई एलिमेंट दिखाते हैं. उदाहरण के लिए, <WebServiceResponse> एलिमेंट, हमारी ऊपर दी गई सैंपल सेवा में दिखाए गए टॉप-लेवल एलिमेंट को दिखाता है. अलग-अलग नोड को या तो पूरे या मिलते-जुलते पाथ के ज़रिए चुना जाता है. इन्हें मुख्य "/" वर्ण की मौजूदगी या मौजूद न होने से दिखाया जाता है.

  • ऐब्सलूट पाथ: "/WebServiceResponse/result" एक्सप्रेशन उन सभी <result> नोड को चुनता है जो <WebServiceResponse> नोड से जुड़े हैं. (ध्यान दें कि ये दोनों एलिमेंट, रूट नोड "/" से आते हैं.)
  • मौजूदा कॉन्टेक्स्ट से मिलता-जुलता पाथ: "result" एक्सप्रेशन, मौजूदा कॉन्टेक्स्ट में मौजूद किसी भी <result> एलिमेंट से मेल खाएगा. आम तौर पर, आपको कॉन्टेक्स्ट की चिंता नहीं करनी चाहिए. आम तौर पर, वेब सेवाओं के नतीजों को एक एक्सप्रेशन से प्रोसेस किया जाता है.

इनमें से किसी भी एक्सप्रेशन को, डबल-स्लैश ("//") से दिखाए गए वाइल्डकार्ड पाथ की मदद से ऑगमेंटेड किया जा सकता है. यह वाइल्डकार्ड बताता है कि इंटरवेंशन पाथ में शून्य या उससे ज़्यादा एलिमेंट मैच हो सकते हैं. उदाहरण के लिए, XPath एक्सप्रेशन "//formatted_address", मौजूदा दस्तावेज़ में उस नाम के सभी नोड से मेल खाएगा. एक्सप्रेशन //viewport//lat, उन सभी <lat> एलिमेंट से मैच करेगा जो <viewport> को पैरंट के तौर पर ट्रेस कर सकते हैं.

डिफ़ॉल्ट रूप से, XPath एक्सप्रेशन सभी एलिमेंट से मेल खाते हैं. आपके पास एक्सप्रेशन को किसी खास एलिमेंट से मैच करने के लिए सीमित करने का विकल्प होता है. predicate, यह स्क्वेयर ब्रैकेट में होता है ([]). उदाहरण के लिए, XPath एक्सप्रेशन "/GeocodeResponse/result[2] हमेशा दूसरा नतीजा दिखाता है.

एक्सप्रेशन का टाइप
रूट नोड
XPath एक्सप्रेशन:  "/"
चुना गया: 
    <WebServiceResponse>
     <status>OK</status>
     <result>
      <type>sample</type>
      <name>Sample XML</name>
      <location>
       <lat>37.4217550</lat>
       <lng>-122.0846330</lng>
      </location>
     </result>
     <result>
      <message>The secret message</message>
     </result>
    </WebServiceResponse>
ऐब्सलूट पाथ
XPath एक्सप्रेशन:  "/WebServiceResponse/result"
चुना गया: 
    <result>
     <type>sample</type>
     <name>Sample XML</name>
     <location>
      <lat>37.4217550</lat>
      <lng>-122.0846330</lng>
     </location>
    </result>
    <result>
     <message>The secret message</message>
    </result>
वाइल्डकार्ड वाला पाथ
XPath एक्सप्रेशन:  "/WebServiceResponse//location"
चुना गया: 
    <location>
     <lat>37.4217550</lat>
     <lng>-122.0846330</lng>
    </location>
विधेय वाला पाथ
XPath एक्सप्रेशन:  "/WebServiceResponse/result[2]/message"
चुना गया: 
    <message>The secret message</message>
पहले result के सभी डायरेक्ट चिल्ड्रन
XPath एक्सप्रेशन:  "/WebServiceResponse/result[1]/*"
चुना गया: 
     <type>sample</type>
     <name>Sample XML</name>
     <location>
      <lat>37.4217550</lat>
      <lng>-122.0846330</lng>
     </location>
result का name, जिसका type टेक्स्ट "सैंपल" है.
XPath एक्सप्रेशन:  "/WebServiceResponse/result[type/text()='sample']/name"
चुना गया: 
    Sample XML

इस बात का ध्यान रखना ज़रूरी है कि एलिमेंट चुनते समय नोड चुने जाते हैं, न कि सिर्फ़ उन ऑब्जेक्ट में मौजूद टेक्स्ट को. आम तौर पर, आपको मेल खाने वाले सभी नोड की फिर से जांच करके, टेक्स्ट को एक्सट्रैक्ट करना होता है. टेक्स्ट नोड को सीधे तौर पर भी मैच किया जा सकता है; नीचे टेक्स्ट नोड देखें.

ध्यान दें कि XPath एट्रिब्यूट नोड के साथ भी काम करता है; हालांकि, Google Maps की सभी वेब सेवाएं बिना एट्रिब्यूट के एलिमेंट उपलब्ध कराती हैं. इसलिए, एट्रिब्यूट का मिलान करना ज़रूरी नहीं है.

एक्सप्रेशन में टेक्स्ट चुनना

एक्सएमएल दस्तावेज़ में मौजूद टेक्स्ट को टेक्स्ट नोड ऑपरेटर की मदद से XPath एक्सप्रेशन में बताया जाता है. यह ऑपरेटर "text()", बताए गए नोड से टेक्स्ट निकालने का संकेत देता है. उदाहरण के लिए, XPath एक्सप्रेशन "//formatted_address/text()", <formatted_address> एलिमेंट में मौजूद पूरा टेक्स्ट दिखाएगा.

एक्सप्रेशन का टाइप
सभी टेक्स्ट नोड (खाली सफ़ेद जगह सहित)
XPath एक्सप्रेशन:  "//text()"
चुना गया: 
    sample
    Sample XML

    37.4217550
    -122.0846330
    The secret message
लेख चयन
XPath एक्सप्रेशन:  "/WebServiceRequest/result[2]/message/text()"
चुना गया: 
    The secret message
कॉन्टेक्स्ट सेंसिटिव चुनना
XPath एक्सप्रेशन:  "/WebServiceRequest/result[type/text() = 'sample']/name/text()"
चुना गया: 
    Sample XML

इसके अलावा, किसी एक्सप्रेशन का आकलन करके नोड के सेट का सेट निकाला जा सकता है. इसके बाद, हर नोड से टेक्स्ट निकालकर उस "नोड सेट" को दोहराया जा सकता है. हमने नीचे दिए गए उदाहरण में इस तरीके का इस्तेमाल किया है.

XPath के बारे में ज़्यादा जानकारी के लिए, XPath W3C की खास बातें देखें.

Java में XPath का आकलन किया जा रहा है

Java में, javax.xml.xpath.* पैकेज में एक्सएमएल पार्स करने और एक्सएमएल एक्सप्रेशन का इस्तेमाल करने के लिए, कई तरीकों से सुविधा उपलब्ध है. इसी वजह से, इस सेक्शन में दिया गया सैंपल कोड, Java का इस्तेमाल करके यह बताता है कि एक्सएमएल को कैसे हैंडल किया जाता है और एक्सएमएल सर्विस रिस्पॉन्स से डेटा को कैसे पार्स किया जाता है.

अपने Java कोड में XPath का इस्तेमाल करने के लिए, आपको सबसे पहले XPathFactory का इंस्टेंस इंस्टैंशिएट करना होगा. साथ ही, XPath ऑब्जेक्ट बनाने के लिए, उस फ़ैक्ट्री पर newXPath() को कॉल करना होगा. इसके बाद, यह ऑब्जेक्ट evaluate() तरीके का इस्तेमाल करके पास किए गए एक्सएमएल और XPath एक्सप्रेशन को प्रोसेस कर सकता है.

एक्सएमएल एक्सप्रेशन का आकलन करते समय, पक्का करें कि आप ऐसे किसी भी संभावित "नोड सेट" पर दोहराएं जो लौटा जा सकता है. ये नतीजे Java कोड में DOM नोड के तौर पर दिखाए जाते हैं. इसलिए, आपको NodeList ऑब्जेक्ट में कई वैल्यू को कैप्चर करना चाहिए. साथ ही, उन नोड से किसी भी टेक्स्ट या वैल्यू को निकालने के लिए, उस ऑब्जेक्ट पर फिर से लागू करना चाहिए.

इस कोड में बताया गया है कि XPath ऑब्जेक्ट कैसे बनाएं, उसे एक्सएमएल और XPath एक्सप्रेशन कैसे असाइन करें, और सही कॉन्टेंट प्रिंट करने के लिए एक्सप्रेशन का मूल्यांकन कैसे करें.

import org.xml.sax.InputSource;
import org.w3c.dom.*;
import javax.xml.xpath.*;
import java.io.*;

public class SimpleParser {

  public static void main(String[] args) throws IOException {

	XPathFactory factory = XPathFactory.newInstance();

    XPath xpath = factory.newXPath();

    try {
      System.out.print("Web Service Parser 1.0\n");

      // In practice, you'd retrieve your XML via an HTTP request.
      // Here we simply access an existing file.
      File xmlFile = new File("XML_FILE");

      // The xpath evaluator requires the XML be in the format of an InputSource
	  InputSource inputXml = new InputSource(new FileInputStream(xmlFile));

      // Because the evaluator may return multiple entries, we specify that the expression
      // return a NODESET and place the result in a NodeList.
      NodeList nodes = (NodeList) xpath.evaluate("XPATH_EXPRESSION", inputXml, XPathConstants.NODESET);

      // We can then iterate over the NodeList and extract the content via getTextContent().
      // NOTE: this will only return text for element nodes at the returned context.
      for (int i = 0, n = nodes.getLength(); i < n; i++) {
        String nodeString = nodes.item(i).getTextContent();
        System.out.print(nodeString);
        System.out.print("\n");
      }
    } catch (XPathExpressionException ex) {
	  System.out.print("XPath Error");
    } catch (FileNotFoundException ex) {
      System.out.print("File Error");
    }
  }
}