.NET क्लाइंट लाइब्रेरी के डेवलपर के लिए गाइड

इस दस्तावेज़ में, Google Data API ("GData") क्वेरी भेजने और मिले हुए जवाबों को समझने के लिए, .NET क्लाइंट लाइब्रेरी का इस्तेमाल करने का तरीका बताया गया है.

Google, GData की सुविधा वाली सेवाओं के साथ इंटरैक्ट करने के लिए, कई प्रोग्रामिंग भाषाओं में क्लाइंट लाइब्रेरी का सेट उपलब्ध कराता है. इन लाइब्रेरी का इस्तेमाल करके, GData अनुरोध बनाए जा सकते हैं. साथ ही, उन्हें किसी सेवा पर भेजा जा सकता है और जवाब पाए जा सकते हैं.

इस दस्तावेज़ में, क्लाइंट लाइब्रेरी के C# वर्शन के सामान्य इस्तेमाल के कुछ उदाहरण दिए गए हैं. इसके बाद, GData क्लाइंट लिखने के बारे में अन्य जानकारी दी गई है. इस दस्तावेज़ के आखिर में, NDoc फ़ॉर्मैट में C# क्लाइंट लाइब्रेरी के रेफ़रंस दस्तावेज़ का लिंक दिया गया है.

इस क्लाइंट लाइब्रेरी का इस्तेमाल करने के लिए, आपके पास .NET 1.1 रनटाइम होना चाहिए. साथ ही, आपको सभी पैच के बारे में भी जानकारी होनी चाहिए.

.NET क्लाइंट लाइब्रेरी डाउनलोड करें.

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

सामग्री

  1. दर्शक
  2. डेटा मॉडल के बारे में खास जानकारी
  3. ट्यूटोरियल और उदाहरण
  4. Reference

ऑडियंस

यह दस्तावेज़, C# प्रोग्रामर के लिए है. ये प्रोग्रामर, ऐसे क्लाइंट ऐप्लिकेशन लिखना चाहते हैं जो GData सेवाओं के साथ इंटरैक्ट कर सकें.

इस दस्तावेज़ में यह मान लिया गया है कि आपको Google Data APIs प्रोटोकॉल के बारे में सामान्य जानकारी है. इसमें यह भी माना गया है कि आपको C# में प्रोग्रामिंग करना आता है.

डेटा मॉडल की खास जानकारी

C# क्लाइंट लाइब्रेरी, क्लास का एक सेट उपलब्ध कराती है. ये क्लास, Google Data API में इस्तेमाल किए गए एलिमेंट और डेटा टाइप से मेल खाती हैं. उदाहरण के लिए, एक Feed क्लास है, जो <atom:feed> एलिमेंट से मेल खाती है. इसमें एंट्री बनाने, अलग-अलग सब-एलिमेंट की वैल्यू पाने और सेट करने के तरीके शामिल हैं. इसमें एक एंट्री क्लास भी होती है, जो <atom:entry> एलिमेंट से मेल खाती है. Google Data API में तय किए गए हर एलिमेंट की अपनी क्लास नहीं होती. ज़्यादा जानकारी के लिए, रेफ़रंस दस्तावेज़ देखें.

यह लाइब्रेरी, Atom कॉन्टेंट को अपने-आप पार्स कर सकती है. साथ ही, Atom एलिमेंट की वैल्यू को सही ऑब्जेक्ट में डाल सकती है. उदाहरण के लिए, getFeed तरीके से फ़ीड मिलता है, उसे पार्स किया जाता है, और नतीजे के तौर पर मिली वैल्यू के साथ Feed ऑब्जेक्ट मिलता है.

किसी सेवा को फ़ीड या एंट्री भेजने के लिए, फ़ीड या एंट्री ऑब्जेक्ट बनाया जाता है. इसके बाद, ऑब्जेक्ट को एक्सएमएल में अपने-आप बदलने और उसे भेजने के लिए, लाइब्रेरी के किसी तरीके (जैसे कि insert तरीका) को कॉल किया जाता है.

अगर आपको पसंद है, तो XML को खुद पार्स और/या जनरेट किया जा सकता है. ऐसा करने का सबसे आसान तरीका, तीसरे पक्ष की सही लाइब्रेरी का इस्तेमाल करना है.

Google Data API के एक्सएमएल सिंटैक्स की तरह ही, इससे जुड़ा ऑब्जेक्ट मॉडल भी बढ़ाया जा सकता है. उदाहरण के लिए, क्लाइंट लाइब्रेरी, Google Data नेमस्पेस में तय किए गए एलिमेंट के हिसाब से क्लास उपलब्ध कराती है.

ट्यूटोरियल और उदाहरण

यहां दिए गए उदाहरणों में, C# क्लाइंट लाइब्रेरी का इस्तेमाल करके अलग-अलग GData अनुरोध भेजने का तरीका बताया गया है.

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

क्लाइंट बनाना और उसे चलाना

इस दस्तावेज़ में दिए गए उदाहरणों को कंपाइल करने के लिए, आपको इस using स्टेटमेंट का इस्तेमाल करना होगा:

using Google.GData.Client;

फ़ीड का अनुरोध करना

Google Calendar Data API के दस्तावेज़ में बताए गए तरीके से, Calendar फ़ीड का अनुरोध किया जा सकता है. इसके लिए, Calendar को यह एचटीटीपी अनुरोध भेजें:

GET http://www.google.com/calendar/feeds/userID/private/full

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

आपको पुष्टि करने का सही तरीका भी अपनाना होगा. ध्यान दें कि यहां इस्तेमाल किया जा रहा पुष्टि करने वाला सिस्टम ("इंस्टॉल किए गए ऐप्लिकेशन के लिए Google की पुष्टि करने की सुविधा" के नाम से जाना जाता है) सिर्फ़ इंस्टॉल किए गए क्लाइंट ऐप्लिकेशन, जैसे कि डेस्कटॉप क्लाइंट में इस्तेमाल किया जा सकता है. इसे वेब ऐप्लिकेशन में इस्तेमाल नहीं किया जा सकता. प्रमाणीकरण के बारे में ज़्यादा जानकारी के लिए, Google खाते के प्रमाणीकरण से जुड़ा दस्तावेज़ देखें.

C# क्लाइंट लाइब्रेरी का इस्तेमाल करके, "jo@gmail.com" ईमेल पते और "mypassword" पासवर्ड वाले उपयोगकर्ता के लिए, Calendar फ़ीड का अनुरोध करने के लिए, इस कोड का इस्तेमाल करें:

// 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 सेवा से क्लाइंट कनेक्शन (पुष्टि के साथ) को दिखाती है. क्लाइंट लाइब्रेरी का इस्तेमाल करके, किसी सेवा को क्वेरी भेजने की सामान्य प्रक्रिया में ये चरण शामिल होते हैं:

  1. सही यूआरएल पाएं या बनाएं.
  2. अगर आपको किसी सेवा को डेटा भेजना है (उदाहरण के लिए, अगर आपको नई एंट्री डालनी है), तो क्लाइंट लाइब्रेरी क्लास का इस्तेमाल करके, रॉ डेटा को ऑब्जेक्ट में बदलें. (अगर आपको सिर्फ़ फ़ीड का अनुरोध करना है, तो यह चरण लागू नहीं होता. जैसा कि इस उदाहरण में किया गया है.)
  3. एक नया Service इंस्टेंस बनाएं. इसमें सेवा का नाम (जैसे, Calendar के लिए "cl") और आपके ऐप्लिकेशन का नाम (companyName-applicationName-versionID के तौर पर) सेट करें.
  4. सही क्रेडेंशियल सेट करें.
  5. अनुरोध भेजने और नतीजे पाने के लिए, किसी तरीके को कॉल करें.

service.setUserCredentials तरीके से, service.Credentials प्रॉपर्टी को स्टैंडर्ड .NET नेटवर्क क्रेडेंशियल ऑब्जेक्ट के साथ सेट किया जाता है. क्रेडेंशियल, उस उपयोगकर्ता के आईडी और पासवर्ड पर सेट किए जाते हैं जिसकी ओर से आपका क्लाइंट क्वेरी भेज रहा है. इस दस्तावेज़ में दिए गए उदाहरणों में, "इंस्टॉल किए गए ऐप्लिकेशन के लिए पुष्टि" पुष्टि करने वाले सिस्टम का इस्तेमाल किया गया है. पुष्टि करने वाले अन्य सिस्टम के बारे में ज़्यादा जानने के लिए, Google खाते की पुष्टि से जुड़ा दस्तावेज़ देखें.

पूरे फ़ीड का अनुरोध करने के लिए, service.Query तरीके का इस्तेमाल करें. यह FeedQuery ऑब्जेक्ट लेता है और उस यूआरएल पर मौजूद पूरा फ़ीड दिखाता है. हम इस दस्तावेज़ में आगे बताएंगे कि ज़्यादा सटीक क्वेरी कैसे भेजी जाती हैं.

Service क्लास के अन्य तरीकों की तरह, Query भी पुष्टि करने और रीडायरेक्ट करने की प्रोसेस को ज़रूरत के मुताबिक मैनेज करता है.

नया आइटम डालना

किसी आइटम को Calendar फ़ीड में डालने के लिए, इस कोड का इस्तेमाल किया जा सकता है:

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. यह एक AtomUri ऑब्जेक्ट दिखाता है. इस ऑब्जेक्ट के ToString() तरीके का इस्तेमाल करके, एक नया यूआरआई ऑब्जेक्ट बनाया जा सकता है.

इसके बाद, हमें सिर्फ़ सेवा के Query मेथड को कॉल करना होगा, ताकि हमें एक नया AtomFeed ऑब्जेक्ट मिल सके. इसमें सिर्फ़ एक एंट्री होगी.

ऊपर दिया गया कोड, Calendar को 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 प्रॉपर्टी का इस्तेमाल करते हैं.

ऊपर दिया गया कोड, Calendar में 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 में कैटगरी के हिसाब से खोज करने की सुविधा होती, तो ऊपर दिया गया कोड, 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 Data C# API का इस्तेमाल करने का तरीका बताया गया है. हालांकि, Google Calendar फ़ीड के साथ काम करते समय, फ़ीड में कैलेंडर से जुड़ा काफ़ी डेटा होता है. इसे बेस एपीआई लाइब्रेरी में मौजूद स्टैंडर्ड एटम-ओरिएंटेड ऑब्जेक्ट का इस्तेमाल करके आसानी से ऐक्सेस नहीं किया जा सकता. उन फ़ीड के साथ इंटरैक्ट करने में आपकी मदद करने के लिए, हम ये एक्सटेंशन उपलब्ध कराते हैं:

using Google.GData.Extensions;
using Google.GData.Calendar;

Extensions नेमस्पेस, सामान्य तौर पर एक्सटेंशन से जुड़ा होता है. वहीं, Calendar नेमस्पेस से आपको कैलेंडर की पसंद के मुताबिक सेवा, फ़ीड, और क्वेरी ऑब्जेक्ट का ऐक्सेस मिलता है. C# API इंस्टॉलेशन की /Samples सबडायरेक्ट्री में, इन एक्सटेंशन के इस्तेमाल का ज़्यादा जानकारी वाला उदाहरण देखा जा सकता है. ये ऑब्जेक्ट जोड़े गए हैं:

EventQuery
यह FeedQuery की सबक्लास है. इसकी मदद से, Calendar सेवा के लिए दो कस्टम पैरामीटर (start-min और start-max) सेट किए जा सकते हैं.
CalendarService
सेवा की एक सबक्लास, जो इवेंट फ़ीड दिखा सकती है.
EventFeed
यह AtomFeed का सबक्लास है. इससे EventEntries का पता चलता है.
EventEntry
यह AtomEntry की सबक्लास है. इसमें कैलेंडर डेटा से जुड़ी अतिरिक्त प्रॉपर्टी होती हैं.

उन खास क्लास के बारे में ज़्यादा जानने के लिए, एपीआई से जुड़े दस्तावेज़ और सैंपल प्रोग्राम देखें.

रेफ़रंस

C# क्लाइंट लाइब्रेरी के बारे में रेफ़रंस जानकारी के लिए, रेफ़रंस दस्तावेज़ देखें.

वापस सबसे ऊपर जाएं