शुरू करना

इस दस्तावेज़ में Google Books API का इस्तेमाल करने के लिए, बैकग्राउंड में काम करने की जानकारी होती है.

सुविधा के बारे में जानकारी

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

शुरू करने से पहले

Google खाता बनाएं

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

किताबों के बारे में जानें

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

अनुरोधों को अनुमति देने और अपने ऐप्लिकेशन की पहचान करने के बारे में जानें

जब आपका ऐप्लिकेशन निजी डेटा को ऐक्सेस करने का अनुरोध करता है, तब इस अनुरोध की अनुमति किसी ऐसे उपयोगकर्ता को देनी चाहिए जिसके पास डेटा का ऐक्सेस हो.

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

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

अनुरोधों को अनुमति देने और एपीआई कुंजियों का इस्तेमाल करने के तरीके के बारे में जानकारी के लिए, एपीआई दस्तावेज़ का इस्तेमाल करना में अनुरोधों को अनुमति देना और अपने ऐप्लिकेशन की पहचान करना देखें.

Books API बैकग्राउंड

किताब से जुड़े सिद्धांत

Google Books को चार बुनियादी कॉन्सेप्ट पर बनाया गया है:

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

    ध्यान दें: फ़िलहाल, बुकशेल्फ़ बनाने और मिटाने के साथ-साथ किताबों की शेल्फ़ पर निजता सेटिंग में बदलाव करने का काम, सिर्फ़ Google Books की साइट पर किया जा सकता है.

  • समीक्षा: वॉल्यूम की समीक्षा, स्टार रेटिंग और/या टेक्स्ट का कॉम्बिनेशन होती है. उपयोगकर्ता हर वॉल्यूम के लिए एक समीक्षा सबमिट कर सकता है. समीक्षाएं दूसरे प्लैटफ़ॉर्म से भी ली जाती हैं.
  • पढ़ने का क्रम: उपयोगकर्ता के लिए, पढ़ने की पोज़िशन से पता चलता है कि वह किताब कहां पढ़ रही है. एक उपयोगकर्ता के लिए, हर वॉल्यूम में सिर्फ़ एक पढ़ने की जगह हो सकती है. अगर उपयोगकर्ता ने पहले वॉल्यूम को नहीं खोला है, तो पढ़ने की स्थिति मौजूद नहीं है. किताब पढ़ने की स्थिति में, जगह के बारे में ज़्यादा जानकारी सेव की जा सकती है. इस जानकारी का इस्तेमाल, किसी शब्द के रिज़ॉल्यूशन के हिसाब से किया जाता है. यह जानकारी उपयोगकर्ता के लिए हमेशा निजी रहती है.

Books API डेटा मॉडल

रिसॉर्स, एक यूनीक आइडेंटिफ़ायर के साथ निजी डेटा इकाई होती है. Books API, ऊपर बताए गए कॉन्सेप्ट के आधार पर दो तरह के संसाधनों पर काम करता है:

  • आवाज़ रिसॉर्स: वॉल्यूम दिखाता है.
  • किताबों का संसाधन: किसी खास उपयोगकर्ता के लिए एक किताबों की अलमारी के बारे में बताता है.

Books API का डेटा मॉडल, संसाधनों के ग्रुप के आधार पर बनाया जाता है जिन्हें कलेक्शन कहा जाता है:

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

Google हर उपयोगकर्ता के लिए पहले से तय की गई किताबों की एक शेल्फ़ उपलब्ध कराता है:

  • पसंदीदा: बदले जा सकने वाले किताबों की अलमारी.
  • खरीदा गया: उपयोगकर्ता के खरीदे गए वॉल्यूम से भरा गया. उपयोगकर्ता मैन्युअल तरीके से वॉल्यूम को जोड़ या हटा नहीं सकता.
  • पढ़ने के लिए: बदले जा सकने वाले किताबों की अलमारी.
  • अभी पढ़ा जा रहा है: बदले जा सकने वाले किताबों की अलमारी.
  • पढ़ें: बदले जा सकने वाले किताबों की अलमारी.
  • समीक्षा की गई: उपयोगकर्ता के ज़रिए समीक्षा किए गए वॉल्यूम से भरा गया. उपयोगकर्ता मैन्युअल तरीके से वॉल्यूम को जोड़ या हटा नहीं सकता.
  • हाल ही में देखे गए: उपयोगकर्ता के वेब ब्राउज़र में हाल ही में खोले गए वॉल्यूम की जानकारी. उपयोगकर्ता मैन्युअल रूप से वॉल्यूम नहीं जोड़ सकता है.
  • मेरी ई-बुक: बदले जा सकने वाले किताबों की अलमारी. खरीदी गई किताबें अपने-आप जुड़ जाती हैं, लेकिन उन्हें मैन्युअल तरीके से हटाया जा सकता है.
  • आपके लिए किताबें: आपके हिसाब से वॉल्यूम के सुझाव पाने की सुविधा. अगर हमारे पास उपयोगकर्ता के लिए कोई सुझाव नहीं है, तो यह किताबों की अलमारी मौजूद नहीं है.

बुकशेल्फ़ का उदाहरण:

  • "पसंदीदा"
    • "हैरी पॉटर"
  • "मेरे ई-बुक"
    • "स्विच"
    • "ट्वाइलाइट"
    • "द गर्ल विथ द ड्रैगन टैटू"

Books API से जुड़ी कार्रवाइयां

नीचे दिए गए टेबल में बताया गया है कि Books API में, कलेक्शन और संसाधनों के लिए पांच अलग-अलग तरीकों का इस्तेमाल किया जा सकता है.

कार्रवाई जानकारी REST एचटीटीपी मैपिंग
list कलेक्शन में मौजूद संसाधनों के खास सबसेट की सूची बनाता है. कलेक्शन यूआरआई पर GET.
शामिल करें कलेक्शन में नया संसाधन शामिल करता है (नया संसाधन बनाना). कलेक्शन यूआरआई पर POST, जहां आप नए रिसॉर्स के लिए डेटा पास करते हैं.
get एक खास रिसॉर्स मिलता है. संसाधन यूआरआई पर GET.
अपडेट किसी खास संसाधन को अपडेट करता है. संसाधन यूआरआई पर PUT, जहां आप अपडेट किए गए संसाधन के लिए डेटा पास करते हैं.
मिटाएं किसी खास संसाधन को मिटाता है. संसाधन यूआरआई पर DELETE, जहां आप संसाधन मिटाने के लिए डेटा पास करते हैं.

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

संसाधन प्रकार
काम करने वाले ऑपरेशन
सूची शामिल करें पाएं अपडेट मिटाएं
आवाज़ हाँ* हाँ
बुकशेल्फ़ हाँ* हां, प्रमाणित हाँ* हां, प्रमाणित हां, प्रमाणित
पढ़ने की जगहें हां, प्रमाणित हां, प्रमाणित हां, प्रमाणित हां, प्रमाणित

*दोनों AUTHENTICATED और इन कार्रवाइयों के बिना पुष्टि किए गए वर्शन उपलब्ध हैं, जहां बिना पुष्टि वाले अनुरोध, उपयोगकर्ता के निजी "मेरी लाइब्रेरी" डेटा पर काम करते हैं और बिना पुष्टि वाले अनुरोध सिर्फ़ सार्वजनिक डेटा पर काम करते हैं.

कॉल करने के तरीके

एपीआई को शुरू करने के कई तरीके हैं:

  • REST का इस्तेमाल सीधे तौर पर करें
  • JavaScript के REST का इस्तेमाल करना (सर्वर-साइड कोड ज़रूरी नहीं है)

REST

REST सॉफ़्टवेयर आर्किटेक्चर की एक शैली है, जो डेटा का अनुरोध करने और उसमें बदलाव करने के लिए एक सुविधाजनक और एक जैसा तरीका देती है.

REST शब्द को "रिप्रज़ेंटेशनल स्टेट ट्रांसफ़र" कहते हैं. Google API के संदर्भ में, इसका मतलब है कि Google के पास सेव किए गए डेटा को फिर से पाने और उनमें बदलाव करने के लिए, एचटीटीपी कार्रवाइयों का इस्तेमाल करना.

RESTful सिस्टम में, रिसॉर्स को डेटा स्टोर में स्टोर किया जाता है; क्लाइंट अनुरोध भेजता है कि सर्वर कोई खास कार्रवाई करता है (जैसे कि संसाधन बनाना, वापस पाना, अपडेट करना या मिटाना), और सर्वर कार्रवाई करता है और अक्सर बताए गए रिसॉर्स के रूप में एक जवाब भेजता है.

Google के RESTful एपीआई में, क्लाइंट POST, GET, PUT, या DELETE जैसी एचटीटीपी कार्रवाई का इस्तेमाल करके कार्रवाई तय करता है. यह संसाधन को नीचे दिए गए फ़ॉर्म के वैश्विक-यूनीक यूआरआई से तय करता है:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

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

आपको एचटीटीपी 1.1 स्टैंडर्ड के दस्तावेज़ में, मैथड डेफ़िनिशन की जानकारी मिल सकती है. इनमें GET, POST, PUT, और DELETE के लिए खास जानकारी शामिल है.

Books API में REST

Books API ऑपरेशन में बताए गए तरीके से, Books के साथ काम करने वाले काम, सीधे REST एचटीटीपी वाली कार्रवाइयों पर मैप किए जाते हैं.

Books API यूआरआई के खास फ़ॉर्मैट यहां दिए गए हैं:

https://www.googleapis.com/books/v1/{collectionName}/resourceID?parameters

जहां resourceID किसी वॉल्यूम या बुकशेल्फ़ संसाधन के लिए पहचानकर्ता होता है और parametersकोई भी कोई क्वेरी होता है जिसे क्वेरी पर लागू किया जा सकता है. ज़्यादा जानकारी के लिए, क्वेरी पैरामीटर की जानकारी देखें.

resourceID पाथ एक्सटेंशन के फ़ॉर्मैट की मदद से, उस संसाधन की पहचान की जा सकती है जिस पर अभी काम किया जा रहा है, उदाहरण के लिए:

https://www.googleapis.com/books/v1/volumes
https://www.googleapis.com/books/v1/volumes/volumeId
https://www.googleapis.com/books/v1/mylibrary/bookshelves
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes
...

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

Books API में इसके काम करने के तरीके से जुड़े कुछ उदाहरण यहां दिए गए हैं.

रजाई बनाने के लिए खोज करें:

GET https://www.googleapis.com/books/v1/volumes?q=quilting

वॉल्यूम s1gVAAAAYAAJ के बारे में जानकारी पाएं:

GET https://www.googleapis.com/books/v1/volumes/s1gVAAAAYAAJ

JavaScript से REST

callback क्वेरी पैरामीटर और कॉलबैक फ़ंक्शन का इस्तेमाल करके, JavaScript से REST के इस्तेमाल से Books API को शुरू किया जा सकता है. JSON-P भी कहा जाता है. यह आपको ऐसे रिच ऐप्लिकेशन लिखने देता है जो कोई सर्वर साइड कोड लिखे बिना ही Books का डेटा दिखाते हैं.

ध्यान दें: access_token पैरामीटर का इस्तेमाल करके, OAuth 2.0 टोकन पास करके, पुष्टि किए गए तरीकों को कॉल किया जा सकता है. JavaScript के साथ इस्तेमाल करने के लिए OAuth 2.0 टोकन पाने के लिए, क्लाइंट-साइड वेब ऐप्लिकेशन के लिए OAuth 2.0 में दिए गए निर्देशों का पालन करें. एपीआई कंसोल के "एपीआई ऐक्सेस" टैब में, वेब ऐप्लिकेशन के लिए क्लाइंट आईडी सेट अप करना न भूलें. साथ ही, अपना टोकन पाते समय उन OAuth 2.0 क्रेडेंशियल का इस्तेमाल करें.

नीचे दिए गए उदाहरण में, “हैरी पॉटर” के लिए खोज के नतीजे दिखाने का तरीका बताया गया है:

<html>
  <head>
    <title>Books API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function handleResponse(response) {
      for (var i = 0; i < response.items.length; i++) {
        var item = response.items[i];
        // in production code, item.text should have the HTML entities escaped.
        document.getElementById("content").innerHTML += "<br>" + item.volumeInfo.title;
      }
    }
    </script>
    <script src="https://www.googleapis.com/books/v1/volumes?q=harry+potter&callback=handleResponse"></script>
  </body>
</html>

डेटा फ़ॉर्मैट

JSON

JSON (JavaScript ऑब्जेक्ट नोटेशन) एक सामान्य, भाषा-स्वतंत्र डेटा फ़ॉर्मैट है. यह आर्बिट्ररी डेटा स्ट्रक्चर के बारे में आसान टेक्स्ट दिखाता है. ज़्यादा जानकारी के लिए, json.org देखें.