चेतावनी: यह पेज, Google के पुराने एपीआई यानी कि Google Data API के बारे में है. यह सिर्फ़ उन एपीआई के बारे में है जो Google Data API डायरेक्ट्री में मौजूद हैं. इनमें से कई एपीआई को नए एपीआई से बदला गया है. किसी नए एपीआई के बारे में जानकारी पाने के लिए, उस नए एपीआई के दस्तावेज़ देखें. नए एपीआई से अनुरोधों को अनुमति देने के बारे में जानकारी पाने के लिए, Google खाते की पुष्टि करना और अनुमति देना देखें.
इस दस्तावेज़ में, Google Data API क्वेरी भेजने और लौटाए गए जवाबों को समझने के लिए, JavaScript क्लाइंट लाइब्रेरी को इस्तेमाल करने का तरीका बताया गया है.
डेटा एपीआई की सुविधा देने वाली सेवाओं के साथ इंटरैक्ट करने के लिए, Google कई तरह की प्रोग्रामिंग भाषाओं में क्लाइंट लाइब्रेरी का सेट उपलब्ध कराता है. इन लाइब्रेरी का इस्तेमाल करके, आप एपीआई अनुरोध तैयार कर सकते हैं, उन्हें किसी सेवा को भेज सकते हैं, और जवाब पा सकते हैं.
इस दस्तावेज़ में JavaScript क्लाइंट लाइब्रेरी को इस्तेमाल करने के बारे में कुछ सामान्य जानकारी दी गई है. साथ ही, आम तौर पर इस्तेमाल होने वाले उदाहरणों के सेट भी दिए गए हैं.
दर्शक
यह दस्तावेज़ JavaScript प्रोग्रामर के लिए है जो ऐसे क्लाइंट ऐप्लिकेशन लिखना चाहते हैं जो Google डेटा सेवाओं से सहभागिता कर सकते हैं.
इस दस्तावेज़ में यह माना गया है कि आप Google डेटा एपीआई प्रोटोकॉल से जुड़े सामान्य आइडिया समझते हैं. इसमें यह भी माना जाता है कि आपको JavaScript की मदद से प्रोग्राम करने का तरीका पता है.
क्लास लाइब्रेरी और क्लाइंट लाइब्रेरी से दिए गए तरीकों के बारे में जानने के लिए, JavaScript क्लाइंट लाइब्रेरी का एपीआई रेफ़रंस (JSdoc फ़ॉर्मैट में) देखें.
इस दस्तावेज़ को पढ़ने के लिए डिज़ाइन किया गया है. इसके अलावा, हर उदाहरण पहले के उदाहरणों के आधार पर बनाया गया है.
उपयोग की शर्तें
JavaScript क्लाइंट लाइब्रेरी का इस्तेमाल करते समय, आप Google JavaScript क्लाइंट लाइब्रेरी की इस्तेमाल की शर्तों का पालन करने के लिए सहमत होते हैं.
डेटा मॉडल और कंट्रोल फ़्लो की खास जानकारी
JavaScript क्लाइंट लाइब्रेरी, Google Data API के इस्तेमाल किए गए एलिमेंट दिखाने के लिए क्लास के सेट का इस्तेमाल करता है.
ध्यान दें: डेटा का मूल वर्शन JSON है, लेकिन क्लाइंट लाइब्रेरी में ऐब्स्ट्रैक्शन लेयर होती है. इससे, आपको सीधे JSON डेटा के साथ काम करने की ज़रूरत नहीं होती. अगर आपको सीधे क्लाइंट लाइब्रेरी के बिना JSON के साथ काम करना है, तो Google डेटा एपीआई के साथ JSON का इस्तेमाल करना देखें.
लाइब्रेरी में कई तरीके इस्तेमाल किए जा सकते हैं. इनकी मदद से, एसिंक्रोनस तरीके से डेटा भेजा जा सकता है. साथ ही, उस सेवा से डेटा पाया जा सकता है जिसमें डेटा एपीआई है. उदाहरण के लिए, google.gdata.calendar.CalendarService.getEventsFeed() का तरीका इस्तेमाल करने पर, Google Calendar पर फ़ीड दिखाने का अनुरोध भेजा जाता है. जारी रखने वाले फ़ंक्शन में से एक, कंटिन्शन फ़ंक्शन है. इसे कॉलबैक भी कहा जाता है. सेवा, फ़ंक्शन के कॉल करके, JSON फ़ॉर्मैट में फ़ीड दिखाती है. इसके बाद, क्लाइंट JavaScript ऑब्जेक्ट के तौर पर डेटा का इस्तेमाल करने के लिए, get के अलग-अलग तरीकों पर कॉल कर सकता है.
नई एंट्री जोड़ने के लिए, क्लाइंट लाइब्रेरी की क्लास और तरीकों का इस्तेमाल करके एंट्री बनाएं. इसके बाद, सेवा में नई एंट्री भेजने के लिए, feed.insertEntry() तरीके को कॉल करें. फिर से आप जारी रखने वाला फ़ंक्शन दें, जिसे एंट्री के सफलतापूर्वक जोड़े जाने पर सेवा कॉल करती है.
अगर आप JavaScript पर नए हैं, तो नियंत्रण प्रवाह कुछ भ्रमित हो सकता है. ज़्यादातर मामलों में, जैसे कि getEventsFeed() या insertEntry() को कॉल करने पर, आपकी स्क्रिप्ट खत्म हो जाती है. सेवा देने वाले व्यक्ति से अनुरोध किया गया डेटा मिलने पर, कंटिन्यूएशन फ़ंक्शन में एक्ज़ीक्यूशन फिर से शुरू हो जाता है. इसलिए, लौटाए गए डेटा के लिए आपका क्लाइंट जो भी करता है उसे 'जारी रखने के फ़ंक्शन' में किया जाना चाहिए या उस फ़ंक्शन से कॉल किया जाना चाहिए. कई फ़ंक्शन में उनका इस्तेमाल करने के लिए, आपको कुछ वैरिएबल को ग्लोबल बनाने की ज़रूरत पड़ सकती है.
इस तरह की प्रोग्रामिंग के बारे में ज़्यादा जानकारी के लिए, विकिपीडिया में "जारी रखने की शैली पास करना" देखें.
काम करने वाले एनवायरमेंट के बारे में जानकारी
फ़िलहाल, हम सिर्फ़ ऐसे JavaScript क्लाइंट ऐप्लिकेशन की सुविधा देते हैं जो ब्राउज़र में वेब पेज पर चलते हैं. फ़िलहाल, ये ब्राउज़र काम करते हैं:
- Firefox 2.x और 3.x
- Internet Explorer 6, 7, और 8
- Safari 3.x और 4.x
- Google Chrome (सभी वर्शन)
JavaScript क्लाइंट लाइब्रेरी, सेवा के सर्वर से होने वाले सभी कम्यूनिकेशन को मैनेज करती है. अगर आप एक अनुभवी JS डेवलपर हैं, तो आप सोच रहे होंगे, "लेकिन वही ऑरिजिन नीति क्या होगी?" JavaScript क्लाइंट लाइब्रेरी, आपके क्लाइंट को ब्राउज़र के सुरक्षा मॉडल के साथ काम करते हुए, किसी भी डोमेन से Google डेटा के अनुरोध भेजने की सुविधा देती है.
Google Data API की मदद से पुष्टि करने के बारे में खास जानकारी पाने के लिए, Google Data API की पुष्टि करने की खास जानकारी देखें. इस दस्तावेज़ के बाकी हिस्से के लिए यह माना गया है कि आपको सिस्टम की बुनियादी बातों के बारे में पता है.
सैंपल क्लाइंट ऐप्लिकेशन
JavaScript क्लाइंट लाइब्रेरी को काम करते देखने के लिए, हमारे सैंपल पेज पर जाएं.
ट्यूटोरियल और उदाहरण
नीचे दिए गए उदाहरण, JavaScript क्लाइंट लाइब्रेरी का इस्तेमाल करके, अलग-अलग डेटा एपीआई अनुरोधों को भेजने का तरीका बताते हैं.
उन्हें और मज़बूत बनाने के लिए, ये उदाहरण किसी खास सेवा से इंटरैक्ट करने का तरीका बताते हैं: Google कैलेंडर. हम उन जगहों की जानकारी देंगे जहां Calendar, Google की दूसरी सेवाओं से अलग है. इससे, आपको इन उदाहरणों को दूसरी सेवाओं के साथ इस्तेमाल करने में मदद मिलेगी. कैलेंडर के बारे में ज़्यादा जानकारी के लिए, Google Calendar Data API दस्तावेज़ देखें.
लाइब्रेरी लोड हो रही है
क्लाइंट लाइब्रेरी का इस्तेमाल करने से पहले, क्लाइंट को सर्वर से क्लाइंट लाइब्रेरी कोड का अनुरोध करना होगा.
Google AJAX एपीआई लोडर को फ़ेच करने के लिए, अपने एचटीएमएल दस्तावेज़ के <head> सेक्शन में <script> टैग का इस्तेमाल करके शुरुआत करें:
<script type="text/javascript" src="https://www.google.com/jsapi"></script>
लाइब्रेरी को पहले से लोड करके, Google के सर्वर पर आने-जाने की यात्राएं कम की जा सकती हैं. इससे, इंतज़ार का समय कम हो जाता है. कुछ पैकेज को सीधे Google AJAX API लोडर से
पहले से लोड करने के लिए, (नीचे देखें google.load() का इस्तेमाल किए बिना), यह तरीका अपनाएं:
<script type="text/javascript"
src="https://www.google.com/jsapi?autoload=%7Bmodules%3A%5B%7Bname%3Agdata%2Cversion%3A2.x%2Cpackages%3A%5Bblogger%2Ccontacts%5D%7D%5D%7D"></script>
ध्यान दें: स्क्रिप्ट के src यूआरएल को पूरी तरह से यूआरएल कोड में बदला जाना चाहिए. उदाहरण के लिए, पिछला उदाहरण
<script type="text/javascript" src="https://www.google.com/jsapi?autoload={modules:[{name:gdata,version:2.x,packages:[blogger,contacts]}]}"></script> है.
अगर आप मॉड्यूल लोड नहीं कर रहे हैं, तो आप आम लोडर फ़ेच करने के बाद, अपने JavaScript सेटअप कोड में अगले उदाहरण
का इस्तेमाल करके, Google डेटा क्लाइंट लाइब्रेरी लोड कर सकते हैं. यह कॉल आपके एचटीएमएल दस्तावेज़ के <head> सेक्शन से (या किसी JavaScript फ़ाइल से किया जाना चाहिए, जिसमें आपके एचटीएमएल दस्तावेज़ के <head> टैग में <script> टैग इस्तेमाल किया गया हो):
google.load("gdata", "2");
इसके अलावा, पूरी लाइब्रेरी के बजाय किसी खास सेवा का अनुरोध किया जा सकता है. यह उदाहरण सिर्फ़ उन पैकेज को डाउनलोड करता है जो Blogger और संपर्कों के लिए हैं:
google.load("gdata", "2.x", {packages: ["blogger", "contacts"]});
google.load() पैरामीटर का दूसरा पैरामीटर, JavaScript क्लाइंट लाइब्रेरी का वर्शन नंबर है.हमारी वर्शन नंबरिंग स्कीम, Google Maps API में इस्तेमाल की गई स्कीम के आधार पर बनाई गई है. यहां वर्शन के संभावित नंबर और उनके मतलब के बारे में बताया गया है:
"1"- मेजर वर्शन 1 का दूसरा वर्शन.
"1.x"- मेजर वर्शन 1 का नया वर्शन.
"1.s"- मेजर वर्शन 1 का नया और ठीक वर्शन. डेवलपर से मिलने वाले फ़ीडबैक के आधार पर, हम कभी-कभी क्लाइंट लाइब्रेरी के किसी खास वर्शन को "स्टेबल"" बना देंगे. हालांकि, उस वर्शन में नई सुविधाएं नहीं हो सकती हैं.
"1.0","1.1" वगैरह- लाइब्रेरी का कोई वर्शन, जिसमें खास मेजर और माइनर रिविज़न नंबर मौजूद हो.
google.load() को कॉल करने के बाद, आपको पेज के लोड होने तक इंतज़ार करना होगा. इसके बाद, कोड लोड करना होगा:
google.setOnLoadCallback(getMyFeed);
जहां getMyFeed() इस दस्तावेज़ के अगले सेक्शन में बताया गया एक फ़ंक्शन है. <body> एलिमेंट से onload हैंडलर अटैच करने के बजाय, इस तरीके का इस्तेमाल करें.
एक ऐसे फ़ीड का अनुरोध करना जिसकी पुष्टि नहीं की गई है
बिना पुष्टि वाले फ़ीड का अनुरोध करने के लिए, अपनी JavaScript फ़ाइल में या अपनी एचटीएमएल फ़ाइल के <script> टैग में यह कोड जोड़ें.
नीचे दिए गए कोड में, पहले getMyFeed() को कॉल किया जाता है (AJAX एपीआई लोडर से), जैसा कि पिछले सेक्शन में बताया गया है.
यह Google Calendar से कनेक्शन बनाने के लिए, setupMyService() को कॉल करता है. इसे CalendarService ऑब्जेक्ट दिखाता है. हमने सेवा बनाने के कोड को मॉड्यूलरिटी के लिए एक अलग फ़ंक्शन में ले जाया है; बाद में, हम आपकी पुष्टि करने के विकल्पों के आधार पर, setupMyService() फ़ंक्शन में बदलाव करेंगे.
सेवा सेट अप होने के बाद, getMyFeed() क्लाइंट लाइब्रेरी के getEventsFeed() तरीके को फ़ीड का अनुरोध करने के लिए कॉल करता है.
हम फ़ीड के यूआरएल को ग्लोबल वैरिएबल में दिखा रहे हैं, ताकि इसका इस्तेमाल बाद के फ़ंक्शन में किया जा सके. इस उदाहरण में, हम liz@gmail.com नाम के उपयोगकर्ता के (बिना पुष्टि वाले) फ़ीड यूआरएल का इस्तेमाल कर रहे हैं. प्रमाणित उपयोगकर्ता को दिखाने के लिए, आप उपयोगकर्ता के ईमेल पते की जगह default का भी इस्तेमाल कर सकते हैं.
var feedUrl = "http://www.google.com/calendar/feeds/liz@gmail.com/public/full";
function setupMyService() {
var myService = new google.gdata.calendar.CalendarService('exampleCo-exampleApp-1');
return myService;
}
function getMyFeed() {
myService = setupMyService();
myService.getEventsFeed(feedUrl, handleMyFeed, handleError);
}
ध्यान रखें कि myService को ग्लोबल वैरिएबल बनाया जा रहा है, ताकि बाद के फ़ंक्शन में इसका इस्तेमाल आसानी से किया जा सके.
ऊपर दिए गए कोड को अपने क्लाइंट में काम करने के लिए, आपको सार्वजनिक रूप से शेयर किए गए कैलेंडर वाले कैलेंडर खाते के लिए असली उपयोगकर्ता के ईमेल पते का इस्तेमाल करना होगा.
ध्यान दें: नया CalendarService ऑब्जेक्ट बनाने पर, क्लाइंट लाइब्रेरी google.gdata.client.init() नाम के तरीके का इस्तेमाल करती है. इससे यह पता चलता है कि क्लाइंट जिस ब्राउज़र में काम कर रहा है वह काम करता है या नहीं. अगर कोई गड़बड़ी होती है, तो क्लाइंट लाइब्रेरी उपयोगकर्ता को गड़बड़ी का मैसेज दिखाती है. अगर आप इस प्रकार की गड़बड़ी को स्वयं प्रबंधित करना चाहते हैं, तो फिर आप सेवा बनाने से पहले स्पष्ट रूप से google.gdata.client.init(handleInitError) को कॉल कर सकते हैं, जहां handleInitError() आपका फ़ंक्शन है. अगर कोई init गड़बड़ी होती है, तो आपके फ़ंक्शन को एक स्टैंडर्ड गड़बड़ी ऑब्जेक्ट मिलता है. आप उस ऑब्जेक्ट के साथ जो चाहें, कर सकते हैं.
getEventsFeed() को किए जाने वाले कॉल में, दूसरा आर्ग्युमेंट handleMyFeed होता है, जो एक कॉलबैक फ़ंक्शन होता है; नीचे देखें. Google Calendar, अनुरोध को प्रोसेस करता है. इसके बाद, अनुरोध पूरा होने पर, कॉलबैक को वह "फ़ीड रूट" ऑब्जेक्ट पास करता है जिसमें अनुरोध किया गया फ़ीड मौजूद है. फ़ीड रूट, एक कंटेनर ऑब्जेक्ट है जिसमें फ़ीड होता है.
getEventsFeed() में तीसरा तर्क, एक वैकल्पिक गड़बड़ी को संभालने वाला फ़ंक्शन है; अगर क्लाइंट लाइब्रेरी को कोई गड़बड़ी मिलती है, तो वह सक्सेस कॉलबैक फ़ंक्शन के बजाय बताए गए गड़बड़ी हैंडलर को कॉल करती है. जिस ऑब्जेक्ट को क्लाइंट लाइब्रेरी, गड़बड़ी हैंडलर में आर्ग्युमेंट के तौर पर भेजती है वह JavaScript Error ऑब्जेक्ट का एक उदाहरण है, जिसमें cause की अन्य प्रॉपर्टी होती है.
यहां कॉलबैक फ़ंक्शन और गड़बड़ी हैंडलर के आसान वर्शन दिए गए हैं:
function handleMyFeed(myResultsFeedRoot) {
alert("This feed's title is: " + myResultsFeedRoot.feed.getTitle().getText());
}
function handleError(e) {
alert("There was an error!");
alert(e.cause ? e.cause.statusText : e.message);
}
हम बस गड़बड़ियों को उपयोगकर्ता को दिखाकर गड़बड़ियों को ठीक कर रहे हैं. इसलिए, आपके क्लाइंट का गड़बड़ी हैंडलर उसे ज़्यादा बेहतर बना सकता है. हो सकता है कि कुछ मामलों में कोई वजह न बताई गई हो. इसलिए, ऐसे मामलों में हमारा गड़बड़ी हैंडलर, वापस स्टैंडर्ड message प्रॉपर्टी दिखाता है.
ध्यान दें कि इस कोड से पुष्टि नहीं होती, इसलिए इसका इस्तेमाल सिर्फ़ सार्वजनिक फ़ीड पाने के लिए किया जा सकता है.
प्रमाणीकरण कर रहा है
JavaScript क्लाइंट लाइब्रेरी का इस्तेमाल दो मोड में किया जा सकता है. अगर आप कोई गैजेट लिख रहे हैं, तो यह पुष्टि करने के लिए OAuth प्रॉक्सी नाम की सुविधा का इस्तेमाल करता है. अगर इसे स्टैंडअलोन JavaScript ऐप्लिकेशन से ऐक्सेस किया जा रहा है, तो यह AuthSub पुष्टि सिस्टम का इस्तेमाल करता है. पुष्टि करने के बारे में जानकारी पाने के लिए, Google Data API से पुष्टि करने की खास जानकारी वाला दस्तावेज़ देखें. इस सेक्शन के बाकी हिस्सों को यह माना जाता है कि आप इस सिस्टम के काम करने के तरीके की बुनियादी बातें जानते हैं.
इस दस्तावेज़ में दिए गए सैंपल कोड से पुष्टि करने का तरीका इस्तेमाल करने से पहले, फ़ीड के यूआरएल को सार्वजनिक से निजी में बदलें:
var feedUrl = "http://www.google.com/calendar/feeds/liz@gmail.com/private/full";
AuthSub के साथ वेब क्लाइंट में पुष्टि करना
Google का "JavaScript के लिए SubSub" का ऑथराइज़ेशन सिस्टम अब उपलब्ध नहीं है.
इसके बजाय, हम क्लाइंट-साइड ऐप्लिकेशन के लिए OAuth 2.0 का इस्तेमाल करने का सुझाव देते हैं.
OAuth प्रॉक्सी के साथ गैजेट में प्रमाणीकरण
यहां बताया गया है कि किसी गैजेट की प्रमाणीकरण प्रक्रिया के दौरान क्या होता है:
- आपका गैजेट पहली बार लोड होता है और किसी एक Google डेटा API का उपयोग करके उपयोगकर्ता का डेटा ऐक्सेस करने की कोशिश करता है.
- उपयोगकर्ता ने अभी तक अपने डेटा का ऐक्सेस नहीं दिया है, इसलिए अनुरोध पूरा नहीं हुआ.
रिस्पॉन्स ऑब्जेक्ट में OAuth अनुमति पेज के लिए एक यूआरएल (
response.oauthApprovalUrlमें) शामिल है. आपके गैजेट को उस URL के साथ एक नई विंडो को लॉन्च करने की प्रक्रिया प्रदान करनी चाहिए. - अनुमति पेज पर, उपयोगकर्ता आपके गैजेट को ऐक्सेस देना या अस्वीकार करना चुनता है. अगर यह सफल होता है, तो उपयोगकर्ता को
आपके बताए गए
oauth_callbackपेज पर ले जाया जाता है. बेहतर उपयोगकर्ता अनुभव पाने के लिए,http://oauth.gmodules.com/gadgets/oauthcallbackका इस्तेमाल करें. - इसके बाद, उपयोगकर्ता पॉप-अप विंडो को बंद कर देता है. उपयोगकर्ता को अनुमति मिलने के बाद, गैजेट को इसकी सूचना देने के लिए, हमने पॉप-अप हैंडलर बनाया है. इसका इस्तेमाल करके, मंज़ूरी विंडो को बंद किया जा सकता है. इसके अलावा, विंडो बंद होने के बाद, आपका गैजेट भी लिंक को दिखा सकता है. उदाहरण के लिए, "मैंने ऐक्सेस करने की अनुमति दी है").
- आपका गैजेट, उपयोगकर्ता के डेटा का दोबारा अनुरोध करके, दूसरी बार Google Data API को ऐक्सेस करने की कोशिश करता है. यह कोशिश पूरी हो गई है.
- आपका गैजेट प्रमाणित है और सामान्य रूप से काम करना शुरू कर सकता है.
अपने गैजेट में, <ModulePrefs> सेक्शन में <OAuth> एलिमेंट जोड़ें:
<ModulePrefs>
...
<OAuth>
<Service name="google">
<Access url="https://www.google.com/accounts/OAuthGetAccessToken" method="GET" />
<Request url="https://www.google.com/accounts/OAuthGetRequestToken?
scope=http://www.blogger.com/feeds/%20http://www.google.com/calendar/feeds/" method="GET" />
<Authorization url="https://www.google.com/accounts/OAuthAuthorizeToken?
oauth_callback=http://oauth.gmodules.com/gadgets/oauthcallback" />
</Service>
</OAuth>
...
</ModulePrefs>
इस सेक्शन में, नीचे दिए गए क्वेरी पैरामीटर को बदलें:
scopeअनुरोध के यूआरएल में ज़रूरी पैरामीटर है. आपका गैजेट केवल इस पैरामीटर में उपयोग किए गए
scope(s) से डेटा ऐक्सेस कर सकेगा. इस उदाहरण में, गैजेट आपके ब्लॉगर और कैलेंडर डेटा को ऐक्सेस करेगा. गैजेट किसी एक दायरे या एक से ज़्यादा दायरों के लिए डेटा का अनुरोध कर सकता है (जैसा कि इस उदाहरण में बताया गया है).oauth_callbackअनुमति देने वाले यूआरएल में एक वैकल्पिक पैरामीटर. उपयोगकर्ता के अपने डेटा को ऐक्सेस करने की अनुमति देने के बाद, OAuth मंज़ूरी पेज इस यूआरएल पर रीडायरेक्ट करेगा. आपके पास इस पैरामीटर को छोड़ने का विकल्प है. इसे अपने "स्वीकार किए गए पेज" पर सेट करें. इसके अलावा,
http://oauth.gmodules.com/gadgets/oauthcallbackका इस्तेमाल भी किया जा सकता है. बाद में, उपयोगकर्ताओं को आपका गैजेट इंस्टॉल करने पर सबसे अच्छा अनुभव मिलता है. वह पेज JavaScript का स्निपेट देता है जो पॉप-अप विंडो को अपने-आप बंद कर देता है.
इसके बाद, अपने गैजेट के <Content> अनुभाग में JavaScript क्लाइंट लाइब्रेरी लोड करें. सेवा के ऑब्जेक्ट के useOAuth() तरीके को कॉल करने के लिए, पिछले उदाहरणों में से setupMyService() फ़ंक्शन में बदलाव करें. यह गैजेट को OAuth Proxy का इस्तेमाल करके, AuthSub के बजाय उसे प्रमाणित करने के लिए कहता है. नीचे दिए गए टेंप्लेट से, आपको
शुरू करने में मदद मिलेगी:
<Content type="html">
<![CDATA[
...
<script src="https://www.google.com/jsapi"></script>
<script type="text/javascript">
var myService = null;
function setupMyService() {
myService = new google.gdata.calendar.CalendarService('exampleCo-exampleApp-1');
myService.useOAuth('google');
fetchData();
}
function initGadget() {
google.load('gdata', '2.x');
google.setOnLoadCallback(setupMyService);
}
function fetchData() {
var callback = function(response) {
if (response.oauthApprovalUrl) {
// TODO: Display "Sign in" link (response.oauthApprovalUrl contains the URL)
} else if (response.feed) {
// TODO: show results
} else {
// TODO: handle the error
}
};
myService.getEventsFeed('http://www.google.com/calendar/feeds/default/public/full', callback, callback);
}
gadgets.util.registerOnLoadHandler(initGadget);
</script>
...
]]>
</Content>
ध्यान दें कि google.accounts.user.login(scope) को किया गया कॉल हटा दिया गया है. प्रॉक्सी सर्वर आपके लिए पुष्टि करने की प्रक्रिया को हैंडल करता है.
fetchData() में क्या शामिल होना चाहिए, इस जानकारी के साथ ही Google डेटा एपीआई गैजेट लिखने के बारे में ज़्यादा जानकारी के लिए, Google डेटा गैजेट बनाना से जुड़ा हमारा लेख देखें या
पूरी जानकारी के साथ OAuth गैजेट दस्तावेज़ देखें.
नया आइटम शामिल किया जा रहा है
नया कैलेंडर इवेंट बनाने के लिए, पिछले फ़ंक्शन से एक्ज़ीक्यूशन जारी रखने के लिए, handleMyFeed() फ़ंक्शन के आखिर में बदलाव करें:
function handleMyFeed(myResultsFeedRoot) {
alert("This feed's title is: " + myResultsFeedRoot.feed.getTitle().getText());
insertIntoMyFeed(myResultsFeedRoot);
}
नए फ़ंक्शन में, नई एंट्री बनाने के लिए, पहले CalendarEventEntry कंस्ट्रक्टर का इस्तेमाल करें. इसके बाद, एंट्री डालें, ताकि कॉल खत्म होने पर, सेवा को कॉल करने के लिए कॉलबैक दिया जा सके.
function insertIntoMyFeed(feedRoot) {
var newEntry = new google.gdata.calendar.CalendarEventEntry({
authors: [{
name: "Elizabeth Bennet",
email: "liz@gmail.com"
}],
title: {
type: 'text',
text: 'Tennis with Darcy'
},
content: {
type: 'text',
text: 'Meet for a quick lesson'
},
locations: [{
rel: "g.event",
label: "Event location",
valueString: "Netherfield Park tennis court"
}],
times: [{
startTime: google.gdata.DateTime.fromIso8601("2007-09-23T18:00:00.000Z"),
endTime: google.gdata.DateTime.fromIso8601("2007-09-23T19:00:00.000Z")
}]
});
feedRoot.feed.insertEntry(newEntry, handleMyInsertedEntry, handleError);
}
ध्यान दें कि कंस्ट्रक्टर में इस्तेमाल की गई हर ऑब्जेक्ट प्रॉपर्टी का नाम, उस प्रॉपर्टी के लिए इस्तेमाल किए गए सेटर तरीके के नाम से मेल खाता है. (उदाहरण के लिए, इससे मिलते-जुलते JSON फ़ील्ड नाम के बजाय).
यह भी ध्यान रखें कि आप सिर्फ़ startTime और endTime के लिए, ISO 8601 तारीख और समय की स्ट्रिंग नहीं दे सकते. आपको पहले, fromIso8601() वाले तरीके से ऐसी स्ट्रिंग का इस्तेमाल करना होगा.
यह सेवा, शामिल की गई एंट्री की कॉपी को entryRoot ऑब्जेक्ट के तौर पर दिखाती है और उस ऑब्जेक्ट को कॉलबैक पर भेजती है:
function handleMyInsertedEntry(insertedEntryRoot) {
alert("Entry inserted. The title is: " + insertedEntryRoot.entry.getTitle().getText());
alert("The timestamp is: " + insertedEntryRoot.entry.getTimes()[0].startTime);
}
किसी खास एंट्री का अनुरोध करना
किसी खास एंट्री का अनुरोध करने के लिए, पहले नए फ़ंक्शन को कॉल करने के लिए, handleMyInsertedEntry() फ़ंक्शन में बदलाव करें:
function handleMyInsertedEntry(insertedEntryRoot) {
alert("Entry inserted. The title is: " + insertedEntryRoot.entry.getTitle().getText());
alert("The timestamp is: " + insertedEntryRoot.entry.getTimes()[0].startTime);
requestMySpecificEntry(insertedEntryRoot.entry.getSelfLink().getHref());
}
नीचे दिए गए कोड से, पिछले उदाहरण में डाली गई खास एंट्री का अनुरोध किया जा सकता है.
उदाहरणों की इस शृंखला के संदर्भ में, उस एंट्री को वापस लाना ज़रूरी नहीं है, क्योंकि Calendar में पहले से ही डाली गई एंट्री वापस आ गई है; लेकिन जब भी आपको किसी एंट्री का यूआरआई पता होता है, तब वही तकनीक लागू की जा सकती है.
function requestMySpecificEntry(entryURI) {
myService.getEventsEntry(entryURI, handleMySpecificEntry, handleError);
}
function handleMySpecificEntry(retrievedEntryRoot) {
myEntryRoot = retrievedEntryRoot; // Global variable for later use
alert("This entry's title is: " + retrievedEntryRoot.entry.getTitle().getText());
}
यह उदाहरण, getEventsFeed() के उदाहरण की तरह ही होता है. हालांकि, हम किसी खास एंट्री के लिए, सेवा के getEventEntry() तरीके को कॉल कर रहे हैं और यूआरआई थोड़ा अलग है. पुष्टि किए गए उपयोगकर्ता के मुख्य कैलेंडर के बारे में बताने के लिए, यह "डिफ़ॉल्ट" विकल्प का इस्तेमाल करता है और इसके आखिर में एंट्री आईडी होता है.
साथ ही, हमें बाद में वापस लाई गई एंट्री का इस्तेमाल करना होगा, ताकि हम उसे एक ग्लोबल वैरिएबल में कॉपी कर सकें.
एंट्री खोजी जा रही हैं
पूरे टेक्स्ट की खोज करने के लिए, पहले नए फ़ंक्शन को कॉल करने के लिए, handleMySpecificEntry() फ़ंक्शन में बदलाव करें:
function handleMySpecificEntry(retrievedEntryRoot) {
myEntryRoot = retrievedEntryRoot; // Global variable for later use
alert("This entry's title is: " + retrievedEntryRoot.entry.getTitle().getText());
searchMyFeed();
}
इसके बाद, खोज से पहला मिलान पाने के लिए, इस कोड का इस्तेमाल करें:
function searchMyFeed() {
var myQuery = new google.gdata.calendar.CalendarEventQuery(feedUrl);
myQuery.setFullTextQuery("Tennis");
myQuery.setMaxResults(10);
myService.getEventsFeed(myQuery, handleMyQueryResults, handleError);
}
function handleMyQueryResults(myResultsFeedRoot) {
if (myResultsFeedRoot.feed.getEntries()[0]) {
alert("The first search-match entry's title is: " + myResultsFeedRoot.feed.getEntries()[0].getTitle().getText());
}
else {
alert("There are no entries that match the search query.");
}
}
किसी आइटम को अपडेट करना
किसी मौजूदा आइटम को अपडेट करने के लिए, नए अपडेट फ़ंक्शन को कॉल करने के लिए पहले handleMyQueryResults() के आखिर में एक लाइन जोड़ें:
updateMyEntry();
इसके बाद, इस कोड का इस्तेमाल करें. इस उदाहरण में, हम पहले निकाली गई एंट्री का शीर्षक बदल रहे हैं (जो कि पिछले उदाहरण में ग्लोबल ऑब्जेक्ट myEntryRoot में मौजूद थी) को उसके पुराने टेक्स्ट ("डेंसी के साथ टेनिस") से "ज़रूरी मीटिंग" में बदला जा रहा है.
function updateMyEntry() {
myEntryRoot.entry.getTitle().setText("Important meeting");
myEntryRoot.entry.updateEntry(handleMyUpdatedEntry, handleError);
}
function handleMyUpdatedEntry(updatedEntryRoot) {
alert("Entry updated. The new title is: " + updatedEntryRoot.entry.getTitle().getText());
}
जैसा कि सभी कैलेंडर तरीकों के साथ होता है, updateEntry() तरीके से एंट्री को अपडेट करने में इस्तेमाल होने वाला सही बदलाव यूआरआई अपने आप तय होता है, ताकि आपको उस यूआरआई को साफ़ तौर पर पेश न करना पड़े.
कोई आइटम मिटाना
अपडेट की गई एंट्री मिटाने के लिए, पहले handleMyUpdatedEntry() में एक लाइन जोड़ें:
deleteMyEntry(updatedEntryRoot);
इसके बाद, इस कोड का इस्तेमाल करें:
function deleteMyEntry(updatedEntryRoot) {
updatedEntryRoot.entry.deleteEntry(handleMyDeletedEntry, handleError);
}
function handleMyDeletedEntry() {
alert("Entry deleted");
}
ध्यान दें, deleteEntry() तरीके से यह तय होता है कि एंट्री मिटाने के लिए, सही यूआरआई का इस्तेमाल कैसे किया जाएगा.
ध्यान दें कि कोई एंट्री नहीं दिखाई जाती है. अगर कॉलबैक को कॉल किया जाता है, तो हम जानते हैं कि मिटाया जाना सफल रहा; अगर मिटाया नहीं जाता है, तो handleMyDeletedEntry() को कॉल करने के बजाय deleteEntry(), handleError() को कॉल करता है.
ई-टैग का इस्तेमाल करना
ध्यान दें: ई-टैग का इस्तेमाल सिर्फ़ 'Google डेटा प्रोटोकॉल' के 2.0 वर्शन को चलाने वाली सेवाओं के साथ किया जा सकता है.
सुविधा के बारे में जानकारी
Google डेटा JavaScript क्लाइंट के वर्शन 2 में ETag की सुविधा दी गई है. ईटैग, किसी खास एंट्री का खास वर्शन बताने वाले आइडेंटिफ़ायर होते हैं; दो मामलों में यह अहम है:
- "शर्त के मुताबिक डेटा वापस पाना" करना, जिसमें क्लाइंट एंट्री का अनुरोध करता है और सर्वर एंट्री को सिर्फ़ तब भेजता है, जब क्लाइंट ने पिछली बार अनुरोध किया हो कि यह बदलाव हो चुका हो.
- यह पक्का करना कि कई क्लाइंट अनजाने में एक-दूसरे के बदलावों को ओवरराइट न कर दें. डेटा क्लाइंट ऐसा अपडेट और मिटाने की प्रक्रिया के ज़रिए करता है. ऐसा तब होता है, जब क्लाइंट एंट्री के लिए कोई पुराना ETag तय करता है.
ईटैग दो तरह के होते हैं: कमज़ोर और मज़बूत. कमज़ोर ETag हमेशा W/ से शुरू होता है, जैसे कि: W/"D08FQn8-eil7ImA9WxZbFEw". इस बात की कोई गारंटी नहीं है कि एंट्री में बदलाव होने पर, कमज़ोर ई-टैग बदल जाएंगे. इसलिए, एचटीटीपी का इस्तेमाल सिर्फ़ शर्तों के साथ वापस पाने के लिए किया जा सकता है. स्ट्रॉन्ग ई-टैग किसी खास एंट्री के खास वर्शन की पहचान करते हैं. इनका इस्तेमाल शर्तों को फिर से हासिल करने और अपडेट के दौरान या मिटाने के लिए किया जा सकता है, ताकि अन्य क्लाइंट के बदलावों को ओवरराइट किया जा सके. इस फ़र्क़ की वजह से, क्लाइंट लाइब्रेरी आपको अपडेट करने या मिटाने के लिए कमज़ोर ई-टैग भेजने की अनुमति नहीं देगी.
ई-टैग, सर्वर के रिस्पॉन्स में दो जगहों पर मिल सकते हैं:
ETagएचटीटीपी हेडर में.- फ़ीड/एंट्री में,
gd:etagएट्रिब्यूट के तौर पर.
अगर कोई सेवा वर्शन 2 पर काम करती है, तो हर फ़ीड और एंट्री ऑब्जेक्ट में ETag का मान फिर से पाने के लिए getEtag() तरीका होगा.
JavaScript क्लाइंट को, अनुरोध करने के साथ ई-टैग शामिल करने के दो तरीके काम करते हैं. पहला नया ऑब्जेक्ट opt_params है. क्लाइंट लाइब्रेरी के वर्शन 2 के सभी get/update/insert फ़ंक्शन में एक नया opt_params पैरामीटर मौजूद है. इस ऑब्जेक्ट का इस्तेमाल, अनुरोध करते समय वैकल्पिक पैरामीटर के बारे में बताने के लिए किया जाता है. फ़िलहाल, 'etag' ही इकलौता वैकल्पिक पैरामीटर है. हालांकि, आने वाले समय में दूसरे पैरामीटर भी लॉन्च किए जा सकते हैं. उदाहरण के लिए, आप किसी GET अनुरोध में एक ETag इस तरह जोड़ सकते हैं:
var opt_params = {};
opt_params['etag'] = 'ETAG GOES HERE';
service.getFeed(uri, successHandler, errorHandler, opt_params);
आप फ़ीड/एंट्री पर setEtag() तरीके को कॉल करके, सीधे फ़ीड या एंट्री ऑब्जेक्ट में भी ईटैग जोड़ सकते हैं.
GData प्रोटोकॉल रेफ़रंस की मदद से, ई-टैग के बारे में ज़्यादा जानें.
डेटा पाने के लिए ई-टैग का इस्तेमाल करना
ईटैग, डेटा वापस लाते समय बैंडविड्थ और एक्ज़ीक्यूशन के समय को कम करने में मदद कर सकता है. If-None-Match header: के साथ जीईटी अनुरोध में ETag शामिल किया जा सकता है
If-None-Match: ETAG GOES HERE
अगर ETag, फ़ीड या मौजूदा एंट्री के मौजूदा वर्शन से मेल खाता है, तो सर्वर 304 NOT MODIFIED रिस्पॉन्स और खाली बॉडी के साथ रिस्पॉन्स देता है. ऐसा न होने पर, सर्वर 200 OK रिस्पॉन्स और फ़ीड या एंट्री डेटा के साथ जवाब देता है.
अनुरोध करते समय, 'etag' पैरामीटर को शामिल करके, JavaScript क्लाइंट में ई-टैग का इस्तेमाल किया जा सकता है:
var etag = feed.getEtag(); // Feed loaded from a previous request
var opt_params = {};
opt_params['etag'] = etag;
service.getFeed(feedUrl, successHandler, errorHandler, opt_params);
शर्तों के साथ वापस पाने के लिए, मज़बूत और कमज़ोर, दोनों ई-टैग इस्तेमाल किए जाते हैं. अगर ई-टैग मेल खाता है, तो गड़बड़ी हैंडलर को 304 रिस्पॉन्स के साथ कॉल किया जाएगा:
function successHandler(feedRoot) {
// 200 response
// Update UI to display updates
}
function errorHandler(errorObj) {
if (errorObj.cause.getStatus() == 304) {
// 304 response, do nothing
}
// otherwise the response is some other error
}
JavaScript क्लाइंट में, ई-टैग इस्तेमाल करने का ज़्यादा उदाहरण देखने के लिए, Blogger का इस्तेमाल करके शर्तों के मुताबिक डेटा वापस पाने के नमूने पर नज़र डालें. यह नमूना Blogger पर पांच सेकंड के अंतराल पर, आपके ब्लॉग के अपडेट ढूंढने के लिए पोस्ट करता है. बदलाव होने पर, नमूना पोस्ट की एक सूची अपडेट करता है.
डेटा को अपडेट करने और मिटाने के लिए ई-टैग का इस्तेमाल करना
अपडेट करने/मिटाने के अनुरोधों पर ई-टैग इस्तेमाल करने से यह पक्का हो जाता है कि कई क्लाइंट अनजाने में एक-दूसरे के बदलावों को ओवरराइट नहीं करते हैं. इस मामले में, If-Match हेडर के साथ एक ई-टैग शामिल किया गया है:
If-Match: ETAG GOES HERE
अगर अनुरोध में मौजूद ETag, सर्वर पर ETag से मेल खाता है, तो अपडेट/मिटाना सफल हो जाता है. हालांकि, ETag का मेल न खाने का मतलब है कि एंट्री बदल गई है और अपडेट किया गया/मिटाया नहीं जा सका. इस मामले में, ऐप्लिकेशन को डेटा के नए इंस्टेंस का अनुरोध करना चाहिए और फिर अपडेट करें/मिटाएं.
कुछ मामलों में, हो सकता है कि आप प्रविष्टि में किए गए किसी भी अन्य परिवर्तन पर ध्यान दिए बिना, अपने परिवर्तन लागू करने के लिए बाध्य करना चाहें. ऐसा करने के लिए, If-Match हेडर में * पास करें.
If-Match: *
ध्यान रखें कि यह बदलाव दूसरे क्लाइंट के बदलावों को बदल देगा, इसलिए इसे ध्यान से इस्तेमाल करें.
सिर्फ़ मज़बूत ETag की जानकारी अपडेट की जा सकती है या मिटाई जा सकती है. कमज़ोर ETag के बारे में बताने से गड़बड़ी हो सकती है. इस मामले से बचने के लिए, JavaScript क्लाइंट अपडेट करने और अनुरोधों को मिटाने पर कमज़ोर ETag सेट नहीं करेगा.
ई-टैग का इस्तेमाल उसी तरह किया जाता है जैसे शर्तों के साथ किया जाता है:
function updateData(entry, service) {
var etag = entry.getEtag();
var opt_params = {};
opt_params['etag'] = etag; // Or use '*' to force an update.
service.updateEntry(successHandler, errorHandler, opt_params);
}
function successHandler(response) {
// Successful update
}
function errorHandler(errorObj) {
// ERROR - Update failed. Could be due to an ETag mismatch, but check the
// error message to make sure. An ETag error will be in the format:
// Mismatch: etags = ["Qnc-fTVSLyp7ImA9WxJbFEsDRAw."], version = [1249675665358000]
}
अपडेट करते समय, ETag के बारे में दो जगहों पर बताया जा सकता है:
- एंट्री में,
getEtag()औरsetEtag()तरीकों का इस्तेमाल किया जाता है. - हेडर में,
opt_paramsऑब्जेक्ट का इस्तेमाल करके (जैसा कि ऊपर दिखाया गया है).
पिछले GET अनुरोध से लोड की गई एंट्री में पहले से ही ETag फ़ील्ड सेट होगा. इसलिए, opt_params ऑब्जेक्ट में एक ही ईटैग को शामिल करना ज़रूरी नहीं है. ऐसे मामलों में जहां किसी ETag को एंट्री बॉडी और opt_params दोनों में बताया गया है, उनमें opt_params में ETag को प्राथमिकता दी जाएगी. यह कुछ भ्रम की स्थिति पैदा कर सकता है. इसलिए, अगर आपको शर्तों के साथ अपडेट करने में समस्याएं आ रही हैं, तो पक्का करें कि आपने एंट्री और opt_params ऑब्जेक्ट, दोनों में ETag की जांच की हो.
इसे आसान बनाने के लिए, google.gdata.Entry कक्षाओं की अपनी updateEntry() और deleteEntry() मैथड भी हैं. अगर एंट्री क्लास में पहले से ही ETag है, तो आपको उसे अनुरोध में जोड़ने की ज़रूरत नहीं है. क्लाइंट लाइब्रेरी आपके लिए यह काम अपने-आप कर देगी. उदाहरण के लिए:
// entry was loaded from a previous request. No need to specify // an ETag in opt_params here, it is added automatically. entry.deleteEntry(successHandler, errorHandler);
इसे ठीक से सेट करने पर, आपको चिंता किए बिना ई-टैग का फ़ायदा मिलेगा. हालांकि, अगर आपको '*' का इस्तेमाल करके अपडेट करना है, तो आपको हमेशा opt_params ऑब्जेक्ट को 'etag' = '*' के साथ शामिल करना चाहिए.
काम के शर्तों वाले अपडेट, Contacts में शर्तों के साथ अपडेट में देखे जा सकते हैं. इस सैंपल में पहले एक टेस्ट कॉन्टैक्ट ग्रुप बनाया जाता है, जिसमें इस सैंपल के इस्तेमाल किए गए सभी डेटा बनाए जाएंगे. जब आप सैंपल का इस्तेमाल कर लें, तो इस संपर्क ग्रुप को बेझिझक मिटा दें. इसके बाद नमूना, संपर्क समूह की सामग्री के साथ दो iframe लोड करता है. आप एक iframe में अपडेट कर सकते हैं और यह देख सकते हैं कि इससे दूसरे iframe में अपडेट कैसे प्रभावित होते हैं. इसे इस्तेमाल करने के तरीके की ज़्यादा जानकारी के लिए, नमूने पर जाएं.
सैंपल
- Blogger में शर्तों के साथ डेटा वापस पाना - इसमें Blogger हर पांच सेकंड में पोल लगाता है और अपडेट की जांच करता है.
- संपर्क में शर्त के साथ अपडेट - संपर्क डेटा के साथ दो अलग-अलग iframe दिखाता है, ताकि आप फिर से बना सकें कि संपर्क बनाते/मिटाते या अपडेट करते समय दो क्लाइंट कैसे इंटरैक्ट कर सकते हैं.
रेफ़रंस
क्लास लाइब्रेरी और क्लाइंट लाइब्रेरी से दिए गए तरीकों के बारे में जानने के लिए, JavaScript क्लाइंट लाइब्रेरी का एपीआई रेफ़रंस (JSdoc फ़ॉर्मैट में) देखें.