नेविगेशन कनेक्ट वेब सेवाओं का इस्तेमाल करने के सबसे सही तरीके

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

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

वेब सेवा क्या होती है?

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

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

यहां दिए गए उदाहरण में, REST GET अनुरोध का यूआरएल दिखाया गया है:

#!/bin/bash

gcloud auth application-default login
access_token="$(gcloud auth application-default print-access-token)"

# Call the GetTrip API
curl -X GET "https://navigationconnect.googleapis.com/v1/projects/PROJECT_ID/trips/TRIP_ID" \
-H "Authorization: Bearer ${access_token}" \

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

एसएसएल/टीएलएस ऐक्सेस

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

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

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

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

विशेष वर्ण

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

सेट करें	वर्ण	यूआरएल का इस्तेमाल
अक्षर और अंक दोनों शामिल हो सकते हैं	a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9	टेक्स्ट स्ट्रिंग, स्कीम का इस्तेमाल (http), पोर्ट (8080) वगैरह.
गैर-आरक्षित	- _ . ~	टेक्स्ट स्ट्रिंग
बुकिंग की गई	! * ' ( ) ; : @ & = + $ , / ? % # [ ]	कंट्रोल वर्ण और/या टेक्स्ट स्ट्रिंग

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

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

यूआरएल में कोड में बदले जाने वाले सभी वर्णों को '%' वर्ण और उनके 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 की सभी वेब सेवाओं और स्टैटिक वेब एपीआई के लिए, यूआरएल में ज़्यादा से ज़्यादा 16,384 वर्ण इस्तेमाल किए जा सकते हैं. ज़्यादातर सेवाओं के लिए, वर्णों की इस सीमा तक पहुंचने की ज़रूरत नहीं पड़ेगी. हालांकि, ध्यान दें कि कुछ सेवाओं में कई पैरामीटर होते हैं. इस वजह से, यूआरएल लंबे हो सकते हैं.

Google API का सही तरीके से इस्तेमाल करना

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

एक्स्पोनेंशियल बैकऑफ़

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

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

उदाहरण के लिए, मान लें कि कोई ऐप्लिकेशन Time Zone API से यह अनुरोध करना चाहता है:

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

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

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

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

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

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

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

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

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

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