रूट ऑप्टिमाइज़ेशन एपीआई की वेब सेवाओं को इस्तेमाल करने के सबसे सही तरीके

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

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

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

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

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

यहां दिए गए उदाहरण में, optimizeTours वाले तरीके से REST POST अनुरोध का यूआरएल दिखाया गया है:

https://routeoptimization.googleapis.com/v1/projects/PROJECT_NUMBER:optimizeTours

जिस क्लाउड प्रोजेक्ट में रूट ऑप्टिमाइज़ेशन एपीआई चालू है, वहां PROJECT_NUMBER की जगह उस क्लाउड प्रोजेक्ट का नंबर या आईडी डालें.

अपने OptimizeToursRequest मैसेज को JSON अनुरोध के मुख्य हिस्से के तौर पर शामिल करें.

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

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

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

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

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

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

खास वर्ण

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

सेट करें	वर्ण	यूआरएल का इस्तेमाल
अक्षर और अंक दोनों शामिल हो सकते हैं	ए बी सी डी ई एफ़ ग एच आई जे के एल मी एन ओ पी क्यू र स टी यू वी वा x वाय z ए बी सी डी ई एफ़ जी एच आई जे के एल M N O P Q R S T U V X 8 9 6 0 1 2 3 4 5 6	टेक्स्ट स्ट्रिंग, स्कीम का इस्तेमाल (http), पोर्ट (8080) वगैरह.
गैर-आरक्षित	- _ . ~	टेक्स्ट स्ट्रिंग
बुकिंग की गई	! * ' ( ) ; : @ & = + $ , / ? % # [ ]	कंट्रोल कैरेक्टर और/या टेक्स्ट स्ट्रिंग

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

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