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

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

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

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

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

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

currentConditions एंडपॉइंट का इस्तेमाल करके, हर घंटे की एयर क्वालिटी का अनुरोध करें. इसके लिए, एचटीटीपी पोस्ट अनुरोध इस पते पर भेजें:

https://airquality.googleapis.com/v1/currentConditions:lookup?key=API_KEY

JSON का मुख्य हिस्सा पास करें जगह तय करने के अनुरोध पर जाएँ.

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

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

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

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

आपको लग सकता है कि "मान्य" यूआरएल अपने-आप साबित हो जाता है, लेकिन ऐसा नहीं है. पता बार में डाला गया कोई यूआरएल ब्राउज़र में खास वर्ण (जैसे, "上海+中國"); ब्राउज़र को आंतरिक रूप से अनुवाद करने की ज़रूरत है. ट्रांसमिशन से पहले उन वर्णों को कोड में बदलने के अलग-अलग तरीके का इस्तेमाल कर सकते हैं. 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) वगैरह.
गैर-आरक्षित	- _ . ~	टेक्स्ट स्ट्रिंग
बुकिंग की गई	! * ' ( ) ; : @ & = + $ , / ? % # [ ]	वर्ण और/या टेक्स्ट स्ट्रिंग को कंट्रोल करें

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

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

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

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

उदाहरण के लिए, वह ऐप्लिकेशन देखें जो 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 के इन्फ़्रास्ट्रक्चर पर हमला करता है और इसे अपने हिसाब से मैनेज किया जाना चाहिए. इससे बचने के लिए, आपको यह पक्का करना चाहिए कि एपीआई अनुरोध, क्लाइंट के बीच सिंक न हों.

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

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

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

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

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

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

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

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

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