क्लाइंट लाइब्रेरी बनाना

Google APIs के साथ इस्तेमाल करने के लिए, अलग-अलग तरह के टूल बनाने के लिए, Google APIs Discovery Service का इस्तेमाल किया जा सकता है. हालांकि, Discovery document का मुख्य मकसद, Google को अलग-अलग प्रोग्रामिंग भाषाओं में क्लाइंट लाइब्रेरी बनाने की अनुमति देना है. इस दस्तावेज़ में, Google API के लिए कस्टम क्लाइंट लाइब्रेरी बनाने का तरीका बताया गया है.

स्थिर और पूरी सुविधाओं वाली क्लाइंट लाइब्रेरी एक जटिल टूल है. इसे बनाने में महीनों लग सकते हैं. हालांकि, Google API के लिए एक सामान्य क्लाइंट लाइब्रेरी बनाने के निर्देशों को तीन आसान चरणों में बांटा जा सकता है:

1. खोज से जुड़ा दस्तावेज़ फ़ेच करना और एपीआई सरफेस बनाना
2. अनुरोध लिखना
3. कॉल करना और जवाब पाना

इन चरणों के बारे में ज़्यादा जानकारी, यहां दी गई है. इन निर्देशों को कोड में कैसे मैप किया जाता है, यह देखने के लिए उदाहरण सेक्शन में Simple APIs client का सैंपल भी देखा जा सकता है.

खोज से जुड़ा दस्तावेज़ फ़ेच करना

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

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

अनुरोध लिखें

अनुरोध बनाने के लिए, इन दो चरणों को पूरा करना होता है:

1. अनुरोध का मुख्य हिस्सा लिखना.
2. अनुरोध यूआरएल बनाया जा रहा है.

अगर अनुरोध के मुख्य हिस्से में कोई जानकारी दी गई है, तो आपको उसे भाषा के हिसाब से सही तरीके से दिखाने वाले फ़ॉर्मैट से वायर फ़ॉर्मैट में बदलना होगा. उदाहरण के लिए, Java क्लाइंट लाइब्रेरी में, हर अनुरोध टाइप के लिए एक क्लास हो सकती है. इससे अनुरोध के डेटा को टाइप-सेफ़ तरीके से बदला जा सकता है. साथ ही, इसे JSON में क्रम से लगाया जा सकता है.

अनुरोध यूआरएल बनाने की प्रोसेस थोड़ी ज़्यादा पेचीदा होती है.

एपीआई में मौजूद हर तरीके की path प्रॉपर्टी, यूआरआई टेंप्लेट v04 सिंटैक्स का इस्तेमाल करती है. इस प्रॉपर्टी में ऐसे वैरिएबल हो सकते हैं जिन्हें घुमावदार ब्रैकेट में रखा जाता है. यहां वैरिएबल के साथ path प्रॉपर्टी का एक उदाहरण दिया गया है:

/example/path/var

ऊपर दिए गए पाथ में, var एक वैरिएबल है. इस वैरिएबल की वैल्यू, उस तरीके के लिए डिस्कवरी दस्तावेज़ के parameters सेक्शन से मिलती है. हर वैरिएबल के नाम की वैल्यू, parameters ऑब्जेक्ट में मौजूद होती है. ऊपर दिए गए उदाहरण में, parameters सेक्शन में var नाम का एक पैरामीटर है. इसकी location प्रॉपर्टी path है, ताकि यह पता चल सके कि यह पाथ वैरिएबल है.

अनुरोध करते समय, आपको यूआरएल में var की वैल्यू बदलनी होगी. उदाहरण के लिए, अगर लाइब्रेरी का इस्तेमाल करने वाला व्यक्ति ऐसा विकल्प चुनता है जिससे var की वैल्यू foo पर सेट हो जाती है, तो नया यूआरएल /example/path/foo होगा.

यह भी ध्यान दें कि path प्रॉपर्टी, रिलेटिव यूआरआई है. ऐब्सलूट यूआरआई का हिसाब लगाने के लिए, यह तरीका अपनाएं:

1. अगर आपको अपनी जगह (क्षेत्र) के बारे में पता है और डिस्कवरी दस्तावेज़ में endpoints प्रॉपर्टी है, तो देखें कि आपकी जगह endpoints सूची में मौजूद है या नहीं. अगर ऐसा है, तो endpoints सूची में से वह endpointUrl चुनें जिसका location आपके location से मेल खाता हो.

2. अगर डिस्कवरी दस्तावेज़ में endpoints प्रॉपर्टी मौजूद नहीं है या आपकी जगह की जानकारी endpoints सूची में मौजूद नहीं है या आपको ग्लोबल एंडपॉइंट को टारगेट करना है, तो डिस्कवरी दस्तावेज़ के टॉप लेवल से rootUrl प्रॉपर्टी पाएं.

   उदाहरण के लिए, Service Usage API के लिए खोज से जुड़े दस्तावेज़ में rootUrl प्रॉपर्टी यह है:

   https://serviceusage.googleapis.com/

3. डिस्कवरी दस्तावेज़ के सबसे ऊपर के लेवल से servicePath को पाएं. उदाहरण के लिए, Service Usage API के लिए Discovery document में servicePath प्रॉपर्टी खाली है.

4. इन दोनों को एक साथ जोड़ने पर, यह मिलेगा:

   https://serviceusage.googleapis.com/

5. path प्रॉपर्टी को चुनें. इसे यूआरआई टेंप्लेट के तौर पर बड़ा करें. इसके बाद, इस बड़े किए गए टेंप्लेट के नतीजों को पिछले चरण के यूआरआई के साथ जोड़ें. उदाहरण के लिए, v1 Service Usage API के serviceusage.services.enable तरीके में, path प्रॉपर्टी की वैल्यू v1/{+name}:enable है. इसलिए, इस तरीके का पूरा यूआरआई यह है:

   https://serviceusage.googleapis.com/v1/{+name}:enable

Service Usage API को कॉल करने के लिए, आपको एपीआई पासकोड की ज़रूरत नहीं होती. हालांकि, अगर जिस एपीआई को कॉल किया जा रहा है उसके लिए एपीआई कुंजी की ज़रूरत है, तो यूआरआई की क्वेरी स्ट्रिंग में एपीआई कुंजी जोड़ी जा सकती है:

REQUEST_URI?key=API_KEY

कॉल करना और जवाब मैनेज करना

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

उदाहरण

यहां एपीआई क्लाइंट लाइब्रेरी का एक आसान उदाहरण दिया गया है.

Simple APIs क्लाइंट

यहां Python3 में लिखी गई एक सामान्य क्लाइंट लाइब्रेरी का उदाहरण दिया गया है. क्लाइंट, Service Usage API के साथ इंटरैक्ट करने के लिए एक इंटरफ़ेस बनाता है. इसके बाद, उस इंटरफ़ेस का इस्तेमाल करके प्रोजेक्ट my-project में Compute Engine API (compute.googleapis.com) चालू करता है.

चेतावनी: यहां दिया गया कोड, क्लाइंट लाइब्रेरी का बहुत ही आसान वर्शन है. यह एक अधूरा कोड है. इसे क्लाइंट लाइब्रेरी बनाने के कुछ पहलुओं को दिखाने के लिए उपलब्ध कराया गया है. यह प्रोडक्शन के लिए तैयार कोड नहीं है.

import httplib2
import json
import uritemplate
import urllib

# Step 1: Fetch Discovery document
DISCOVERY_URI = "https://serviceusage.googleapis.com/$discovery/rest?version=v1"
h = httplib2.Http()
resp, content = h.request(DISCOVERY_URI)
discovery = json.loads(content)
location = None # Set this to your location if appropriate
use_global_endpoint = True # Set this to False if you want to target the endpoint for your location

# Step 2.a: Construct base URI
BASE_URL = None
if not use_global_endpoint and location:
  if discovery['endpoints']:
    BASE_URL = next((item['endpointUrl'] for item in discovery['endpoints'] if item['location'] == location), None)
if not BASE_URL:
  BASE_URL = discovery['rootUrl']
BASE_URL += discovery['servicePath']

class Collection(object): pass

def createNewMethod(name, method):
  # Step 2.b Compose request
  def newMethod(**kwargs):
    body = kwargs.pop('body', None)
    url = urllib.parse.urljoin(BASE_URL, uritemplate.expand(method['path'], kwargs))
    for pname, pconfig in method.get('parameters', {}).items():
      if pconfig['location'] == 'path' and pname in kwargs:
        del kwargs[pname]
    if kwargs:
      url = url + '?' + urllib.parse.urlencode(kwargs)
    return h.request(url, method=method['httpMethod'], body=body,
                     headers={'content-type': 'application/json'})

  return newMethod

# Step 3.a: Build client surface
def build(discovery, collection):
  for name, resource in discovery.get('resources', {}).items():
    setattr(collection, name, build(resource, Collection()))
  for name, method in discovery.get('methods', {}).items():
    setattr(collection, name, createNewMethod(name, method))
  return collection

# Step 3.b: Use the client
service = build(discovery, Collection())
print (serviceusage.services.enable(name='projects/my-project/services/compute.googleapis.com'))

क्लाइंट के मुख्य कॉम्पोनेंट ये हैं:

• पहला चरण: डिस्कवरी दस्तावेज़ फ़ेच करें. Service Usage API के लिए डिस्कवरी दस्तावेज़ को वापस पाया जाता है और उसे डेटा स्ट्रक्चर में पार्स किया जाता है. Python एक डाइनैमिक टाइप वाली भाषा है. इसलिए, डिस्कवरी दस्तावेज़ को रनटाइम में फ़ेच किया जा सकता है.
• दूसरा चरण: बेस यूआरआई बनाना. बेस यूआरआई का हिसाब लगाया जाता है.
• दूसरा चरण: अनुरोध लिखना. जब किसी कलेक्शन पर कोई तरीका कॉल किया जाता है, तो यूआरआई टेंप्लेट को उस तरीके में पास किए गए पैरामीटर के साथ बड़ा किया जाता है. साथ ही, query लोकेशन वाले पैरामीटर को यूआरएल के क्वेरी पैरामीटर में रखा जाता है. आखिर में, डिस्कवरी दस्तावेज़ में बताई गई एचटीटीपी विधि का इस्तेमाल करके, कंपोज़ किए गए यूआरएल पर अनुरोध भेजा जाता है.
• तीसरा चरण: क्लाइंट सरफेस बनाना. क्लाइंट सरफेस को पार्स किए गए डिस्कवरी दस्तावेज़ पर बार-बार नीचे की ओर जाकर बनाया जाता है. methods सेक्शन में मौजूद हर तरीके के लिए, Collection ऑब्जेक्ट से एक नया तरीका अटैच किया जाता है. कलेक्शन को नेस्ट किया जा सकता है. इसलिए, हम resources की तलाश करते हैं. अगर कोई resources मिल जाता है, तो हम उसके सभी सदस्यों के लिए, बार-बार Collection ऑब्जेक्ट बनाते हैं. हर नेस्ट किए गए कलेक्शन को Collection ऑब्जेक्ट के एट्रिब्यूट के तौर पर भी अटैच किया जाता है.
• तीसरा चरण: क्लाइंट का इस्तेमाल करना. इससे पता चलता है कि एपीआई की बनाई गई सतह का इस्तेमाल कैसे किया जाता है. सबसे पहले, डिस्कवरी दस्तावेज़ से एक सेवा ऑब्जेक्ट बनाया जाता है. इसके बाद, Compute Engine API को प्रोजेक्ट my-project में चालू करने के लिए, Service Usage API का इस्तेमाल किया जाता है.