Blogger API: शुरू करना

इस दस्तावेज़ में Blogger API का इस्तेमाल शुरू करने का तरीका बताया गया है.

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

कोई Google खाता प्राप्त करें

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

Blogger के बारे में जानें

अगर आपको Blogger के सिद्धांतों के बारे में नहीं पता है, तो इस दस्तावेज़ को पढ़ें और कोड बनाना शुरू करने से पहले यूज़र इंटरफ़ेस के ज़रिए प्रयोग करें. यह दस्तावेज़ मान लेता है कि आपको Blogger के साथ-साथ वेब प्रोग्रामिंग के सिद्धांतों और वेब डेटा फ़ॉर्मैट के बारे में जानकारी है.

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

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

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

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

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

Blogger के सिद्धांत

Blogger को पांच बुनियादी सिद्धांतों के आधार पर बनाया गया है:

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

Blogger एपीआई डेटा मॉडल

संसाधन, एक यूनीक आइडेंटिफ़ायर वाली व्यक्तिगत डेटा इकाई होता है. Blogger JSON API पांच तरह के संसाधनों पर काम करता है:

• ब्लॉग का संसाधन: किसी ब्लॉग के बारे में बताता है.
• पोस्ट संसाधन: यह किसी पोस्ट को दिखाता है. पोस्ट का हर संसाधन, ब्लॉग संसाधन का चाइल्ड संसाधन होता है.
• टिप्पणियों का संसाधन: यह किसी खास पोस्ट पर की गई टिप्पणी को दिखाता है. हर टिप्पणी का संसाधन, पोस्ट के संसाधन का ही हिस्सा होता है.
• पेज का संसाधन: यह पेज के स्टैटिक पेज को दिखाता है. हर पेज का रिसॉर्स, ब्लॉग रिसॉर्स का ही हिस्सा होता है.
• उपयोगकर्ताओं का संसाधन: यह ऐसे उपयोगकर्ता के बारे में बताता है जिसकी पहचान छिपाई गई हो. इसका इस्तेमाल किसी पेज, पोस्ट या टिप्पणी के लेखक की पहचान करने के लिए किया जाता है.

संसाधनों के बीच के संबंधों की खास जानकारी

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

ब्लॉग कलेक्शन

<span="apicollection">ब्लॉग कलेक्शन में वे सभी ब्लॉग होते हैं जिनके ऐक्सेस के अधिकार उपयोगकर्ता के पास होते हैं. आपके पास उपयोगकर्ता के हिसाब से ब्लॉग की सूची बनाने या आईडी के हिसाब से किसी ब्लॉग को वापस पाने का विकल्प होता है.</span="apicollection">

पोस्ट का कलेक्शन

पोस्ट के कलेक्शन में किसी खास ब्लॉग संसाधन के सभी पोस्ट रिसॉर्स शामिल होते हैं.

टिप्पणियों का कलेक्शन

टिप्पणियों के कलेक्शन में किसी खास पोस्ट के संसाधन से जुड़े सभी टिप्पणियों के संसाधन शामिल होते हैं.

पेजों का कलेक्शन

पेजों के कलेक्शन में किसी खास ब्लॉग संसाधन के सभी पेज रिसॉर्स शामिल होते हैं.

उपयोगकर्ताओं का कलेक्शन

उपयोगकर्ताओं के कलेक्शन में Blogger पर मौजूद सभी उपयोगकर्ताओं के संसाधन शामिल होते हैं. इसलिए, इसे सूची में नहीं डाला जा सकता. उपयोगकर्ता, आईडी के ज़रिए या आइडेंटिफ़ायर self का इस्तेमाल करके, अपने उपयोगकर्ता संसाधन को हासिल कर सकता है, लेकिन किसी और का नहीं.

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

आपके पास Blogger API में, कलेक्शन और रिसॉर्स के लिए, कई तरीकों को अपनाने का विकल्प होता है. इन तरीकों के बारे में इस टेबल में बताया गया है.

कार्रवाई	कंपनी का ब्यौरा	REST एचटीटीपी मैपिंग
list	किसी कलेक्शन में मौजूद सभी संसाधनों की सूची बनाता है.	संग्रह यूआरआई पर GET.
पाएं	कोई खास संसाधन मिलता है.	संसाधन यूआरआई पर GET.
getByUrl	इससे संसाधनों को यूआरएल की मदद से ढूंढने पर मदद मिलती है.	GET, जिसका यूआरएल पैरामीटर के तौर पर पास किया गया हो.
getByPath	किसी संसाधन को उसके पाथ से खोजकर हासिल करता है.	पैरामीटर के रूप में पाथ वाला GET.
listByUser	यह उपयोगकर्ता के मालिकाना हक वाले संसाधनों की सूची बनाता है.	उपयोगकर्ता के मालिकाना हक वाले संग्रह पर GET.
search	क्वेरी पैरामीटर के आधार पर संसाधनों को खोजें.	Search Network में दिखने वाले यूआरएल पर GET, जिसमें क्वेरी को पैरामीटर के तौर पर पास किया गया है.
डालें	किसी कलेक्शन में कोई संसाधन बनाना.	संग्रह यूआरआई पर POST.
मिटाएं	संसाधन को मिटाता है.	संसाधन यूआरआई पर DELETE.
पैच	पैच सिमेंटिक्स का इस्तेमाल करके, किसी संसाधन को अपडेट करना.	संसाधन यूआरआई पर PATCH.
अपडेट करें	संसाधन अपडेट करें.	संसाधन यूआरआई पर PUT.

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

संसाधन किस तरह का है	इस्तेमाल किए जा सकने वाले तरीके
	सूची	पाएं	getByUrl	getByPath	listByUser	खोजें	डालें	मिटाएं	पैच	अपडेट
ब्लॉग	no	हां	हां	no	हां	no	नहीं	नहीं	नहीं	no
पोस्ट	हां	हां	no	हां	no	हां	हाँ	हाँ	हाँ	हां
टिप्पणियां	हां	हां	no	नहीं	नहीं	नहीं	नहीं	नहीं	नहीं	no
पेज	हां	हां	no	नहीं	नहीं	नहीं	नहीं	नहीं	नहीं	no
उपयोगकर्ता	no	हां	no	नहीं	नहीं	नहीं	नहीं	नहीं	नहीं	no

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

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

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

आराम

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 के लिए खास जानकारी शामिल होती है.

Blogger एपीआई में REST

काम करने वाली Blogger कार्रवाइयां सीधे REST HTTP कार्रवाइयों से मैप करती हैं, जैसा कि Blogger API से जुड़ी कार्रवाइयों में बताया गया है.

Blogger API यूआरआई का खास फ़ॉर्मैट इस तरह से बनाया जाता है:

https://www.googleapis.com/blogger/v3/users/userId
https://www.googleapis.com/blogger/v3/users/self
https://www.googleapis.com/blogger/v3/users/userId/blogs
https://www.googleapis.com/blogger/v3/users/self/blogs
https://www.googleapis.com/blogger/v3/blogs/blogId
https://www.googleapis.com/blogger/v3/blogs/byurl
https://www.googleapis.com/blogger/v3/blogs/blogId/posts
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/bypath
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/search
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments/commentId
https://www.googleapis.com/blogger/v3/blogs/blogId/pages
https://www.googleapis.com/blogger/v3/blogs/blogId/pages/pageId

इस्तेमाल किए गए यूआरआई और एपीआई में काम करने वाले हर ऑपरेशन के नतीजों की पूरी जानकारी Blogger API रेफ़रंस दस्तावेज़ में दी गई है.

उदाहरण

उन ब्लॉग की सूची बनाएं जिनके ऐक्सेस के अधिकार पुष्टि किए गए उपयोगकर्ता के पास हैं:

GET https://www.googleapis.com/blogger/v3/users/self/blogs?key=YOUR-API-KEY

code.blogger.com ब्लॉग पर पोस्ट पाएं, जिसका ब्लॉग आईडी 3213900 है:

GET https://www.googleapis.com/blogger/v3/blogs/3213900?key=YOUR-API-KEY

JavaScript से REST

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

नीचे दिए गए उदाहरण में, YOUR-API-KEY को अपनी एपीआई कुंजी से बदलने के बाद, code.blogger.com ब्लॉग से एक पोस्ट फिर से ली गई है.

<html>
  <head>
    <title>Blogger API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function handleResponse(response) {
        document.getElementById("content").innerHTML += "<h1>" + response.title + "</h1>" + response.content;
      }
    </script>
    <script
    src="https://www.googleapis.com/blogger/v3/blogs/3213900/posts/8398240586497962757?callback=handleResponse&key=YOUR-API-KEY"></script>
  </body>
</html>

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

JSON

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