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

परिचय

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

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

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

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

पहला चरण: डिस्कवरी दस्तावेज़ पाना

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

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

दूसरा कदम: अनुरोध करना

अनुरोधों को दो अलग-अलग चरणों में पूरा किया जाता है:

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. डिस्कवरी दस्तावेज़ के सबसे ऊपरी लेवल से rootUrl प्रॉपर्टी को कैप्चर करें.
   उदाहरण के लिए, Google Cloud सेवा प्रबंधन एपीआई के डिस्कवरी दस्तावेज़ में rootUrl प्रॉपर्टी:

   https://servicemanagement.googleapis.com/

2. डिस्कवरी दस्तावेज़ के सबसे ऊपर के लेवल पर servicePath का इस्तेमाल करें.
   उदाहरण के लिए, Google Cloud सेवा प्रबंधन एपीआई के डिस्कवरी दस्तावेज़ में servicePath प्रॉपर्टी खाली होती है.

3. पाने के लिए उन्हें एक साथ जोड़ें:

   https://servicemanagement.googleapis.com/

4. path प्रॉपर्टी को पाएं, उसे यूआरआई टेंप्लेट के तौर पर बड़ा करें, और पिछले चरण से मिले यूआरआई के नतीजों को यूआरआई से जोड़ें.
   उदाहरण के लिए, Google Cloud सेवा मैनेजमेंट एपीआई और #get सेवा के तरीके में, path प्रॉपर्टी की वैल्यू v1/services/{serviceName} है. इसलिए, मैथड का पूरा यूआरआई:

   https://servicemanagement.googleapis.com/v1/services/{serviceName}

Google Cloud सेवा प्रबंधन एपीआई को कॉल करने के लिए एपीआई कुंजी ज़रूरी है. इसलिए, एपीआई कुंजी लागू करने के बाद, एपीआई डिस्कवरी सेवा की सेवा की परिभाषा देखने के लिए पूरा यूआरआई यह होता है:

https://servicemanagement.googleapis.com/v1/services/discovery.googleapis.com?key=API_KEY

तीसरा चरण: कॉल करें और जवाब मैनेज करें

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

उदाहरण

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

सामान्य एपीआई क्लाइंट

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

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

import httplib2
import json
import uritemplate
import urllib

# Step 1: Fetch Discovery document
DISCOVERY_URI = "https://servicemanagement.googleapis.com/$discovery/rest?version=v1"
h = httplib2.Http()
resp, content = h.request(DISCOVERY_URI)
discovery = json.loads(content)

# Step 2.a: Construct base URI
BASE_URL = discovery['rootUrl'] + 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 (service.services.get(serviceName='discovery.googleapis.com', key='API_KEY'))

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

• पहला चरण: डिस्कवरी दस्तावेज़ फ़ेच करें.
  Google Cloud सेवा प्रबंधन एपीआई के डिस्कवरी दस्तावेज़ को वापस लाया गया है और उसे डेटा स्ट्रक्चर में पार्स किया गया है. Python डाइनैमिक तरीके से टाइप की जाने वाली भाषा है, इसलिए डिस्कवरी दस्तावेज़ को रनटाइम के दौरान फ़ेच किया जा सकता है.
• कदम 2.a: मूल यूआरआई बनाना.
  बेस यूआरआई का हिसाब लगाया जाता है.
• कदम 2.b: अनुरोध लिखें.
  जब किसी कलेक्शन पर तरीका कॉल किया जाता है, तो यूआरआई टेंप्लेट को मेथड में पास किए गए पैरामीटर के साथ बड़ा कर दिया जाता है. साथ ही, query की जगह वाले पैरामीटर को यूआरएल के क्वेरी पैरामीटर में डाला जाता है. आखिर में, खोज के दस्तावेज़ में बताए गए एचटीटीपी तरीके का इस्तेमाल करके, कंपोज़िशन वाले यूआरएल को अनुरोध भेजा जाता है.
• कदम 3.a: क्लाइंट प्लैटफ़ॉर्म बनाएं.
  क्लाइंट सरफ़ेस को पार्स किए गए डिस्कवरी दस्तावेज़ पर बार-बार घटते हुए बनाया गया है. methods सेक्शन में मौजूद हर तरीके के लिए, एक नया तरीका Collection ऑब्जेक्ट से जोड़ा जाता है. कलेक्शन को नेस्ट किया जा सकता है. इसलिए, resources मिलने पर, हम सभी सदस्यों के लिए बार-बार Collection ऑब्जेक्ट बना सकते हैं. नेस्ट किया गया हर कलेक्शन, Collection ऑब्जेक्ट के साथ एट्रिब्यूट के तौर पर भी अटैच होता है.
• कदम 3.b: क्लाइंट का इस्तेमाल करें.
  इससे यह पता चलता है कि एपीआई का बिल्ट-इन प्लैटफ़ॉर्म कैसे इस्तेमाल किया जाता है. सबसे पहले, सर्विस ऑब्जेक्ट को डिस्कवरी दस्तावेज़ से बनाया जाता है. इसके बाद, 'Google क्लाउड सेवा प्रबंधन एपीआई' से एपीआई डिस्कवरी सेवा की सेवा की परिभाषा हासिल की जाती है.