इस दस्तावेज़ में बताया गया है कि Google डेटा एपीआई ("GData") क्वेरी भेजने और लौटाए गए जवाबों को समझने के लिए, .NET क्लाइंट लाइब्रेरी का इस्तेमाल कैसे किया जाए.
Google, कई तरह की प्रोग्रामिंग भाषाओं में GData की सुविधा वाली सेवाओं के साथ इंटरैक्ट करने के लिए, क्लाइंट लाइब्रेरी का सेट उपलब्ध कराता है. इन लाइब्रेरी का इस्तेमाल करके, आप GData अनुरोध बना सकते हैं, उन्हें किसी सेवा को भेज सकते हैं और जवाब पा सकते हैं.
यह दस्तावेज़ क्लाइंट लाइब्रेरी के C# वर्शन के सामान्य इस्तेमाल के उदाहरणों के साथ, GData क्लाइंट लिखने के बारे में अन्य जानकारी भी देता है. इस दस्तावेज़ के आखिर में, NDOC फ़ॉर्मैट में C# क्लाइंट लाइब्रेरी के लिए, रेफ़रंस दस्तावेज़ का लिंक है.
इस क्लाइंट लाइब्रेरी का इस्तेमाल करने के लिए, आपके पास .NET 1.1 रनटाइम की ज़रूरत होती है. साथ ही, आपके पास सभी पैच का ऐक्सेस होना चाहिए.
.NET क्लाइंट लाइब्रेरी डाउनलोड करें.
इस गाइड के उदाहरण, Google Calendar API का इस्तेमाल करते हैं, लेकिन Calendar एपीआई का इस्तेमाल करने के लिए, यह गाइड सटीक या अप-टू-डेट गाइड नहीं है. किसी खास सेवा के डेटा एपीआई के साथ .NET क्लाइंट लाइब्रेरी का इस्तेमाल करने के बारे में जानकारी पाने के लिए, सेवा से जुड़े खास दस्तावेज़ देखें. उदाहरण के लिए, अगर आप Calendar के साथ काम कर रहे हैं, तो Calendar Data API डेवलपर की गाइड पढ़ें.
विषय सूची
दर्शक
यह दस्तावेज़ C# प्रोग्रामर के लिए है जो GData सेवाओं के साथ सहभागिता करने वाले क्लाइंट ऐप्लिकेशन लिखना चाहते हैं.
इस दस्तावेज़ में यह माना गया है कि आप Google डेटा एपीआई प्रोटोकॉल से जुड़े सामान्य आइडिया समझते हैं. यह भी माना जाता है कि आपको C# में प्रोग्राम करना आता है.
डेटा मॉडल की खास जानकारी
C# क्लाइंट लाइब्रेरी, Google Data API के इस्तेमाल किए जाने वाले एलिमेंट और डेटा टाइप से जुड़ी क्लास का एक सेट उपलब्ध कराती है. उदाहरण के लिए, एक फ़ीड क्लास होती है, जो <atom:feed> एलिमेंट से जुड़ी होती है. इसमें एंट्री बनाने, अलग-अलग सब-एलिमेंट की वैल्यू पाने, और उन्हें सेट करने के कई तरीके होते हैं. यहां एक एंट्री क्लास भी है, जो <atom:entry> एलिमेंट से जुड़ी है. 'Google डेटा एपीआई' में बताए गए हर एलिमेंट की अपनी अलग क्लास होती है; जानकारी के लिए दस्तावेज़ों का दस्तावेज़ देखें.
लाइब्रेरी, ऐटम के कॉन्टेंट को अपने-आप पार्स कर सकती है. साथ ही, ऐटम के एलिमेंट की वैल्यू को सही ऑब्जेक्ट में डाल सकती है. उदाहरण के लिए, getFeed तरीके को एक फ़ीड मिलता है, उसे पार्स किया जाता है, और नतीजे के तौर पर वैल्यू दिखाने वाला फ़ीड ऑब्जेक्ट दिखाया जाता है.
किसी सेवा में कोई फ़ीड या एंट्री भेजने के लिए, कोई फ़ीड या एंट्री ऑब्जेक्ट बनाया जाता है. इसके बाद, ऑब्जेक्ट का अपने-आप एक्सएमएल में अनुवाद करने और उसे भेजने के लिए किसी लाइब्रेरी मेथड को कॉल किया जाता है, जैसे कि insert तरीका.
ज़रूरत पड़ने पर आप खुद पार्स और/या एक्सएमएल जनरेट कर सकते हैं; इसका सबसे आसान तरीका है, किसी सही तीसरे पक्ष की लाइब्रेरी का इस्तेमाल करना.
जिस तरह Google Data API का एक्सएमएल सिंटैक्स एक्सटेंसिबल होता है उसी तरह संबंधित ऑब्जेक्ट मॉडल भी एक्सटेंसिबल होता है. उदाहरण के लिए, क्लाइंट लाइब्रेरी Google डेटा नेमस्पेस में बताए गए एलिमेंट से जुड़ी क्लास उपलब्ध कराती है.
ट्यूटोरियल और उदाहरण
नीचे दिए गए उदाहरणों में दिखाया गया है कि C# क्लाइंट लाइब्रेरी का इस्तेमाल करके, GData के अनुरोध कैसे भेजें.
उन्हें और मज़बूत बनाने के लिए, ये उदाहरण किसी खास सेवा से इंटरैक्ट करने का तरीका बताते हैं: Google कैलेंडर. हम उन जगहों की जानकारी देंगे जहां Calendar, Google की दूसरी सेवाओं से अलग है. इससे, आपको इन उदाहरणों को दूसरी सेवाओं के साथ इस्तेमाल करने में मदद मिलेगी. कैलेंडर के बारे में ज़्यादा जानकारी के लिए, Google Calendar Data API दस्तावेज़ देखें.
अपना क्लाइंट बनाना और उसे चलाना
इस दस्तावेज़ में उदाहरण शामिल करने के लिए, आपको स्टेटमेंट का इस्तेमाल करके इन उदाहरणों का इस्तेमाल करना होगा:
using Google.GData.Client;
फ़ीड का अनुरोध करना
जैसा कि Google Calendar Data API दस्तावेज़ में बताया गया है, Calendar को यह एचटीटीपी अनुरोध भेजकर, Calendar फ़ीड का अनुरोध किया जा सकता है:
GET http://www.google.com/calendar/feeds/userID/private/full
बेशक, आपको उपयोगकर्ता के ईमेल पते से userID बदलना होगा; ज़्यादा जानकारी के लिए कैलेंडर दस्तावेज़ देखें. इसके बजाय, आप कैलेंडर के साथ सहभागिता करने के लिए विशेष डिफ़ॉल्ट URL (कैलेंडर दस्तावेज़ में बताए गए अनुसार) का उपयोग कर सकते हैं, लेकिन इस दस्तावेज़ में हम उपयोगकर्ता आईडी वाले निजी पूरे फ़ीड URL का उपयोग करेंगे.
आपको सही पुष्टि भी करनी होगी. ध्यान दें कि हम जिस पुष्टि करने वाले सिस्टम (जिसमें "इंस्टॉल किए गए ऐप्लिकेशन के लिए Google की पुष्टि का इस्तेमाल किया गया है") का इस्तेमाल सिर्फ़ डेस्कटॉप क्लाइंट जैसे इंस्टॉल किए गए क्लाइंट ऐप्लिकेशन में किया जा सकता है, वेब ऐप्लिकेशन में इस्तेमाल के लिए नहीं. पुष्टि करने के बारे में ज़्यादा जानकारी के लिए, Google खाते की पुष्टि करें दस्तावेज़ देखें.
C# क्लाइंट लाइब्रेरी का इस्तेमाल करके, कैलेंडर पते का अनुरोध करने के लिए, "jo@gmail.com" और पासवर्ड "mypassword" इस्तेमाल करने वाले उपयोगकर्ता के लिए, नीचे दिया गया कोड इस्तेमाल करें:
// Create a query and service object:
FeedQuery query = new FeedQuery();
Service service = new Service("cl", "exampleCo-exampleApp-1"));
// Set your credentials:
service.setUserCredentials("jo@gmail.com", "mypassword");
// Create the query object:
query.Uri = new Uri("http://www.google.com/calendar/feeds/jo@gmail.com/private/full");
// Tell the service to query:
AtomFeed calFeed = service.Query(query);
Service क्लास, GData सेवा के साथ क्लाइंट कनेक्शन (पुष्टि करने के साथ) के बारे में बताती है. क्लाइंट लाइब्रेरी का इस्तेमाल करके, किसी सेवा को क्वेरी भेजने के लिए सामान्य प्रक्रिया में ये चरण शामिल हैं:
- सही यूआरएल पाएं या बनाएं.
- अगर किसी सेवा के लिए डेटा भेजा जा रहा है (उदाहरण के लिए, अगर कोई नई एंट्री डाली जा रही है), तो क्लाइंट लाइब्रेरी क्लास का इस्तेमाल करके, रॉ डेटा को ऑब्जेक्ट में बदलें. (अगर फ़ीड का अनुरोध किया जा रहा है, तो यह चरण लागू नहीं होता, जैसा कि हम इस उदाहरण में कर रहे हैं.)
- सेवा का नाम (जैसे कि कैलेंडर के लिए
"cl") और अपने ऐप्लिकेशन का नाम (companyName-applicationName-versionIDफ़ॉर्म में) सेट करके एक नयाServiceइंस्टेंस बनाएं. - सही क्रेडेंशियल सेट करें.
- अनुरोध भेजने और नतीजे पाने के लिए, पुष्टि करने का कोई तरीका अपनाएं.
service.setUserCredentials का तरीका, service.Credentials प्रॉपर्टी को एक स्टैंडर्ड .NET नेटवर्क क्रेडेंशियल ऑब्जेक्ट के साथ सेट करता है.
क्रेडेंशियल उस उपयोगकर्ता के आईडी और पासवर्ड पर सेट किए जाते हैं, जिसकी ओर से आपका क्लाइंट क्वेरी भेज रहा है. इस दस्तावेज़ के उदाहरणों में, पुष्टि करने वाले "इंस्टॉल किए गए ऐप्लिकेशन के लिए पुष्टि करना" सिस्टम का इस्तेमाल किया गया है. पुष्टि करने के दूसरे सिस्टम के बारे में ज़्यादा जानने के लिए, Google खाते की पुष्टि करना दस्तावेज़ देखें.
पूरे फ़ीड का अनुरोध करने के लिए, service.Query का इस्तेमाल किया जाता है. इसमें FeedQuery ऑब्जेक्ट लिया जाता है और उस यूआरएल पर मिलने वाला पूरा फ़ीड दिखाया जाता है. हम बाद में इस दस्तावेज़ में ज़्यादा खास क्वेरी भेजने का तरीका दिखाएंगे.
Service क्लास के अन्य तरीकों की तरह, Query भी पुष्टि और रीडायरेक्ट को ज़रूरत के हिसाब से मैनेज करता है.
नया आइटम शामिल किया जा रहा है
कैलेंडर फ़ीड में कोई आइटम डालने के लिए, आप इस कोड का इस्तेमाल कर सकते हैं:
AtomEntry entry = new AtomEntry();
AtomPerson author = new AtomPerson(AtomPersonType.Author);
author.Name = "Jo March";
author.Email = "jo@gmail.com";
entry.Authors.Add(author);
entry.Title.Text = "Tennis with Beth";
entry.Content.Content = "Meet for a quick lesson.";
Uri postUri = new Uri("http://www.google.com/calendar/feeds/jo@gmail.com/private/full");
// Send the request and receive the response:
AtomEntry insertedEntry = service.Insert(postUri, entry);
यूआरएल सेट करने के बाद, हम एक AtomEntry ऑब्जेक्ट बनाते हैं.
एंट्री का शीर्षक AtomTextConstruct है. यह एक ऐसी क्लास है जिसमें कई तरह के टेक्स्ट होते हैं (सादा टेक्स्ट, एचटीएमएल या एक्सएचटीएमएल). एंट्री कॉन्टेंट को AtomContent ऑब्जेक्ट के तौर पर दिखाया जाता है. इस क्लास में सादा टेक्स्ट या अन्य तरह का कॉन्टेंट हो सकता है. इसमें एक्सएमएल और बाइनरी डेटा भी शामिल है.
हर लेखक का नाम, यूआरआई, और ईमेल पता होता है. (इस उदाहरण में, हम यूआरआई छोड़ रहे हैं.) एंट्री के Authors कलेक्शन में AtomAuthor ऑब्जेक्ट जोड़कर, लेखक को एंट्री में जोड़ा जा सकता है.
हम उसी Service ऑब्जेक्ट का इस्तेमाल कर रहे हैं जो हमने पिछले उदाहरण में बनाया था. इस मामले में, Insert को कॉल करने का तरीका है जो आइटम को बताए गए इंसर्शन यूआरएल पर भेजता है.
इस सेवा से बनाई गई नई एंट्री दिखती है. इसमें सर्वर के जनरेट किए गए अन्य एलिमेंट शामिल हो सकते हैं. जैसे, एंट्री के लिए यूआरएल में बदलाव करना.
ऊपर दिया गया कोड POST http://www.google.com/calendar/feeds/jo@gmail.com/private/full (सही पुष्टि के साथ) भेजने और एंट्री देने के बराबर है.
किसी खास एंट्री का अनुरोध करना
नीचे दिए गए कोड से, पिछले उदाहरण में डाली गई खास एंट्री का अनुरोध किया जा सकता है.
उदाहरणों की शृंखला के संदर्भ में, उस एंट्री को वापस लाना ज़रूरी नहीं है, क्योंकि Calendar में पहले से ही डाली गई एंट्री ही दिखती है; लेकिन जब आपको किसी एंट्री का यूआरएल पता होता है, तो वही तकनीक लागू हो सकती है.
FeedQuery singleQuery = new FeedQuery(); singleQuery.Uri = new Uri(newEntry.SelfUri.ToString()); AtomFeed newFeed = service.Query(singleQuery); AtomEntry retrievedEntry = newFeed.Entries[0];
डाले गए एंट्री में एक प्रॉपर्टी, SelfUri है, जो ToString() ऑब्जेक्ट का इस्तेमाल करके, एक AtomUri ऑब्जेक्ट दिखाती है. इसका इस्तेमाल एक नया यूआरआई ऑब्जेक्ट बनाने के लिए किया जा सकता है.
इसके बाद, नए ऐटम फ़ीड का ऑब्जेक्ट पाने के लिए, हमें सेवा के Query तरीके पर कॉल करना होगा. ऐसा सिर्फ़ एंट्री कलेक्शन में, एक एंट्री के लिए करना होगा.
ऊपर दिया गया कोड सही पुष्टि के साथ, कैलेंडर पर GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID भेजने के बराबर है.
कोई एंट्री खोजना
पूरे टेक्स्ट की खोज से पहला मिलान पाने के लिए, इस कोड का इस्तेमाल करें:
FeedQuery myQuery = new Query(feedUrl);
myQuery.Query = "Tennis";
AtomFeed myResultsFeed = myService.Query(myQuery);
if (myResultsFeed.Entries.Count > 0) {
AtomEntry firstMatchEntry = myResultsFeed.Entries[0];
String myEntryTitle = firstMatchEntry.Title.Text;
}
यह उदाहरण एक FeedQuery ऑब्जेक्ट बनाने से शुरू होता है, जिसमें ज़्यादातर यूआरएल और उससे जुड़े क्वेरी पैरामीटर शामिल होते हैं. हर एक GData क्वेरी पैरामीटर में एक प्रॉपर्टी होती है.
FeedQuery बनाने के बाद, हम इसे सेवा के Query तरीके को पास करते हैं, जिससे क्वेरी फ़ीड वाला फ़ीड मिलता है. इसका दूसरा तरीका यह है कि आप खुद यूआरएल बनाएं (फ़ीड यूआरएल में क्वेरी पैरामीटर जोड़कर) और फिर Query तरीके को कॉल करें. हालांकि, FeedQuery मैथड, ऐब्स्ट्रैक्शन की एक उपयोगी लेयर देता है, ताकि आपको यूआरएल खुद न बनाना पड़े.
फ़ीड का Entries संग्रह, फ़ीड में एंट्री की सूची दिखाता है; Entries.Count, फ़ीड में एंट्री की संख्या दिखाता है.
इस मामले में, अगर क्वेरी से कोई नतीजा मिलता है, तो हम AtomEntry ऑब्जेक्ट को मैच करने वाला पहला नतीजा असाइन करते हैं. इसके बाद, एंट्री का शीर्षक वापस पाने के लिए, हम AtomEntry क्लास की Title प्रॉपर्टी का इस्तेमाल करते हैं.
ऊपर दिया गया कोड, GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full?q=Tennis को कैलेंडर पर भेजने के बराबर है.
कैटगरी के हिसाब से क्वेरी करना
ध्यान दें: Google Calendar, लेबल को इवेंट से नहीं जोड़ता है. इसलिए, यह उदाहरण Calendar के साथ काम नहीं करता.
पहले पूरे टेक्स्ट की खोज से मेल खाने वाली और किसी खास श्रेणी के या सभी खास लेबल वाली सभी एंट्री वाले फ़ीड को वापस पाने के लिए, नीचे दिए गए कोड का इस्तेमाल करें:
AtomCategory myCategory = new AtomCategory("by_jo");
QueryCategory myCategoryFilter = new QueryCategory(myCategory);
myQuery.Categories.Add(myCategoryFilter);
AtomFeed myCategoryResultsFeed = myService.Query(myQuery);
बेशक, AtomCategory क्लास किसी कैटगरी फ़िल्टर में इस्तेमाल की जाने वाली कैटगरी को दिखाती है. QueryCategory क्लास में कई कैटगरी हो सकती हैं, लेकिन इस मामले में हम सिर्फ़ एक कैटगरी वाला फ़िल्टर बना रहे हैं.
इसके बाद, उस फ़िल्टर को मौजूदा क्वेरी में जोड़ दिया जाता है. इसमें, पिछले उदाहरण में इस्तेमाल की गई, पूरे टेक्स्ट वाली क्वेरी स्ट्रिंग शामिल होती है.
हम सेवा को क्वेरी भेजने के लिए फिर से Query तरीके का इस्तेमाल करते हैं.
अगर कैलेंडर में कैटगरी खोजने की अनुमति है, तो ऊपर दिया गया कोड, Calendar पर GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/-/by_jo?q=Tennis को भेजने के बराबर होगा.
किसी आइटम को अपडेट करना
किसी मौजूदा आइटम को अपडेट करने के लिए, इस कोड का इस्तेमाल करें. नीचे दिए गए उदाहरण में, हम पहले से पुनर्प्राप्त की गई प्रविष्टि के शीर्षक को उसके पुराने टेक्स्ट ("बेथ के साथ टेनिस") से "ज़रूरी मीटिंग" में बदल रहे हैं.
retrievedEntry.Title.Text = "Important meeting"; retrievedEntry.Update();
पहले हमने उस एंट्री के लिए एक नया शीर्षक सेट किया था जो हमने पहले फ़ेच की थी. इसके बाद, हम अपडेट की गई एंट्री को सेवा पर भेजने के लिए, Upate तरीके पर कॉल करते हैं.
सेवा, इस एंट्री के नए वर्शन के लिए नए यूआरएल के साथ अपडेट की गई एंट्री को दिखाती है. (एंट्री वर्शन के बारे में ज़्यादा जानकारी के लिए, v1 प्रोटोकॉल संदर्भ दस्तावेज़ का ऑप्टिमाइज़ेशन कॉनकरेंसी सेक्शन देखें.)
ऊपर दी गई कोड, मूल एंट्री को बदलने के लिए (ऐटम फ़ॉर्मैट में) नई जानकारी के साथ, सेवा को PUT http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID भेजने जैसा ही है.
कोई आइटम मिटाना
किसी मौजूदा आइटम को मिटाने के लिए, इस कोड का इस्तेमाल करें:
updateEntry.Delete();
मिटाने के लिए इस्तेमाल किया जाने वाला यूआरएल और यूआरएल में बदलाव, एक ही है. इसलिए, यह उदाहरण पिछले वाले से काफ़ी मिलता-जुलता है, सिवाय इसके कि हम Update के बजाय Delete तरीके को कॉल कर रहे हैं.
ऊपर दिया गया कोड, DELETE http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID को सेवा में भेजने के करीब बराबर है.
Google Calendar फ़ीड के साथ काम करना
ऊपर दिए गए उदाहरण सामान्य GData फ़ीड के साथ काम करने के लिए Google डेटा C# API को इस्तेमाल करने का तरीका बताते हैं. हालांकि, जब आप खास तौर पर Google Calendar फ़ीड के साथ काम कर रहे हों, तो फ़ीड में कैलेंडर का काफ़ी डेटा मौजूद होता है. इस डेटा को बेस एपीआई लाइब्रेरी में, ऐटम-ओरिएंटेशन वाले स्टैंडर्ड ऑब्जेक्ट से आसानी से ऐक्सेस नहीं किया जा सकता. उन फ़ीड से इंटरैक्ट करने में आपकी मदद करने के लिए, हम ये एक्सटेंशन उपलब्ध कराते हैं:
using Google.GData.Extensions; using Google.GData.Calendar;
एक्सटेंशन नेमस्पेस, सामान्य तौर पर एक्सटेंशन से डील करता है; कैलेंडर नेमस्पेस आपको पसंद के मुताबिक बनाई गई कैलेंडर सेवा, फ़ीड, और क्वेरी ऑब्जेक्ट का ऐक्सेस देता है. C+ API इंस्टॉलेशन की /सैंपल सबडायरेक्ट्री में इन एक्सटेंशन के इस्तेमाल के बारे में ज़्यादा जानकारी मिल सकती है. नीचे दिए गए ऑब्जेक्ट जोड़े जाते हैं:
- इवेंट क्वेरी
- FeedQuery का एक सब-क्लास, जो आपको Calendar सेवा (स्टार्ट-मिन और स्टार्ट-मैक्स) के लिए दो कस्टम पैरामीटर सेट करने की अनुमति देता है.
- कैलेंडर सेवा
- सेवा का एक सब-क्लास, जो इवेंट फ़ीड दिखा सकता है.
- इवेंट फ़ीड
- ऐटफ़ीड का एक सब-क्लास, जो इवेंट से जुड़ी जानकारी दिखाता है.
- इवेंट के लिए प्रवेश शुल्क
- AtomEntry का एक सब-क्लास, जिसमें कैलेंडर डेटा से जुड़ी अतिरिक्त प्रॉपर्टी होती हैं.
खास क्लास के बारे में ज़्यादा जानकारी के लिए, एपीआई दस्तावेज़ और सैंपल प्रोग्राम देखें.
रेफ़रंस
C# क्लाइंट लाइब्रेरी के बारे में रेफ़रंस जानकारी, पहचान दस्तावेज़ देखें.