Java क्लाइंट लाइब्रेरी का इस्तेमाल करना

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

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

यह दस्तावेज़ सामान्य उपयोग के उदाहरणों के साथ, Java क्लाइंट लाइब्रेरी का उपयोग करने के बारे में कुछ सामान्य जानकारी देता है.

इस क्लाइंट लाइब्रेरी का इस्तेमाल करने के लिए, आपके पास Java 1.5 होना ज़रूरी है.

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

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

विषय सूची

  1. दर्शक
  2. डेटा मॉडल की खास जानकारी
  3. ट्यूटोरियल और उदाहरण
    1. अपना क्लाइंट बनाना और उसे चलाना
    2. फ़ीड के लिए अनुरोध करना
    3. नया आइटम जोड़ना
    4. किसी खास एंट्री का अनुरोध करना
    5. खोज के नतीजे
    6. कैटगरी के हिसाब से क्वेरी करना
    7. किसी आइटम को अपडेट करना
    8. किसी आइटम को मिटाना
  4. Reference

दर्शक

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

इस दस्तावेज़ में यह माना गया है कि आप Google डेटा एपीआई प्रोटोकॉल से जुड़े सामान्य आइडिया समझते हैं. इसमें यह भी माना जाता है कि आप Java में प्रोग्राम करना जानते हैं.

क्लास लाइब्रेरी और क्लाइंट लाइब्रेरी से दिए गए तरीकों के बारे में जानने के लिए, Java क्लाइंट लाइब्रेरी एपीआई का रेफ़रंस (Javadoc फ़ॉर्मैट में) देखें.

इस दस्तावेज़ को पढ़ने के लिए डिज़ाइन किया गया है. इसके अलावा, हर उदाहरण पहले के उदाहरणों के आधार पर बनाया गया है.

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

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

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

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

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

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

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

नीचे दिए गए उदाहरण, Java क्लाइंट लाइब्रेरी का इस्तेमाल करके, अलग-अलग डेटा एपीआई अनुरोध भेजने का तरीका दिखाते हैं.

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

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

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

import com.google.gdata.client.*;
import com.google.gdata.client.calendar.*;
import com.google.gdata.data.*;
import com.google.gdata.data.extensions.*;
import com.google.gdata.util.*;
import java.net.URL;

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

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

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

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

आपको सही पुष्टि भी करनी होगी. इस उदाहरण और कैलेंडर दस्तावेज़ में पहले उदाहरण के बीच मुख्य अंतर यह है कि (1) इस उदाहरण में प्रमाणीकरण शामिल है और (2) इस उदाहरण में कैलेंडर-विशिष्ट CalendarService क्लास के बजाय ज़्यादा सामान्य GoogleService क्लास का उपयोग किया गया है.

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

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

// Set up the URL and the object that will handle the connection:
URL feedUrl = new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
GoogleService myService = new GoogleService("cl", "exampleCo-exampleApp-1");
myService.setUserCredentials("liz@gmail.com", "mypassword");

// Mark the feed as an Event feed:
new EventFeed().declareExtensions(myService.getExtensionProfile());

// Send the request and receive the response:
Feed myFeed = myService.getFeed(feedUrl, Feed.class);

GoogleService क्लास, GData सेवा का इस्तेमाल करके पुष्टि किए गए क्लाइंट कनेक्शन के बारे में बताती है. क्लाइंट लाइब्रेरी का इस्तेमाल करके, किसी सेवा को क्वेरी भेजने के लिए सामान्य प्रक्रिया में ये चरण शामिल हैं:

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

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

क्रेडेंशियल सेट करने के बाद, declareExtensions तरीके को कॉल करके यह बताएं कि फ़ीड किस एक्सटेंशन का इस्तेमाल करेगा. इस मामले में, हम कह रहे हैं कि फ़ीड एक इवेंट फ़ीड है और इसलिए हम इवेंट प्रकार के ज़रिए तय किए गए एक्सटेंशन का इस्तेमाल करेंगे.

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

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

नया आइटम शामिल किया जा रहा है

नया कैलेंडर इवेंट बनाने के लिए, आपको इस कोड का इस्तेमाल करना होगा:

URL postUrl =
  new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
EventEntry myEntry = new EventEntry();

myEntry.setTitle(new PlainTextConstruct("Tennis with Darcy"));
myEntry.setContent(new PlainTextConstruct("Meet for a quick lesson."));

Person author = new Person("Elizabeth Bennet", null, "liz@gmail.com");
myEntry.getAuthors().add(author);

DateTime startTime = DateTime.parseDateTime("2006-04-17T15:00:00-08:00");
DateTime endTime = DateTime.parseDateTime("2006-04-17T17:00:00-08:00");
When eventTimes = new When();
eventTimes.setStartTime(startTime);
eventTimes.setEndTime(endTime);
myEntry.addTime(eventTimes);

// Send the request and receive the response:
EventEntry insertedEntry = myService.insert(postUrl, myEntry);

यूआरएल सेट करने के बाद, हम एक EventEntry ऑब्जेक्ट बनाते हैं; EventEntry को एब्स्ट्रैक्ट बेस क्लास BaseEntry से मिलता है, जो Entry क्लास के लिए पैरंट क्लास भी है, जो <atom:entry> एलिमेंट को दिखाता है.

EventEntry क्लास, किसी इवेंट टाइप के बारे में बताती है. ज़्यादा जानकारी के लिए, Kinds का दस्तावेज़ देखें. Calendar के अलावा किसी सेवा के लिए, आप EventEntry ऑब्जेक्ट के बजाय, Entry ऑब्जेक्ट को रिटर्न एंट्री असाइन कर सकते हैं.

एंट्री का शीर्षक TextConstruct है. यह एक ऐसी क्लास है जिसमें कई तरह के टेक्स्ट होते हैं (सादा टेक्स्ट, एचटीएमएल या एक्सएचटीएमएल). एंट्री कॉन्टेंट को Content ऑब्जेक्ट के तौर पर दिखाया जाता है. इस क्लास में सादा टेक्स्ट या अन्य तरह का कॉन्टेंट हो सकता है. इसमें एक्सएमएल और बाइनरी डेटा भी शामिल है. हालांकि, setContent वाला तरीका TextConstruct को भी स्वीकार कर सकता है.

हर लेखक का नाम, यूआरआई, और ईमेल पता होता है. (इस उदाहरण में, हम यूआरआई छोड़ रहे हैं.) आप एंट्री के getAuthors().add तरीके को कॉल करके, लेखक को जोड़ सकते हैं.

हम उसी GoogleService ऑब्जेक्ट का इस्तेमाल कर रहे हैं जो हमने पिछले उदाहरण में बनाया था. इस मामले में, insert को कॉल करने का तरीका है जो आइटम को बताए गए इंसर्शन यूआरएल पर भेजता है.

इस सेवा से बनाई गई नई एंट्री दिखती है. इसमें सर्वर के जनरेट किए गए अन्य एलिमेंट शामिल हो सकते हैं. जैसे, एंट्री के लिए यूआरएल में बदलाव करना.

अपवाद के तौर पर, एचटीटीपी स्टेटस कोड दिखाए जाते हैं.

ऊपर दिया गया कोड POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full भेजने (सही पुष्टि करने के साथ) और इवेंट टाइप के तौर पर एंट्री देने के बराबर है.

किसी खास एंट्री का अनुरोध करना

नीचे दिए गए कोड से, पिछले उदाहरण में डाली गई खास एंट्री का अनुरोध किया जा सकता है.

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

URL entryUrl = new URL(insertedEntry.getSelfLink().getHref());
EventEntry retrievedEntry = myService.getEntry(entryUrl, EventEntry.class);

डाले गए एंट्री में एक तरीका, getSelfLink है, जो एक Link ऑब्जेक्ट दिखाता है, जिसमें एंट्री का यूआरएल शामिल होता है. Link क्लास में getHref तरीका होता है जो यूआरएल को String के तौर पर दिखाता है. इससे हम यूआरएल ऑब्जेक्ट बना सकते हैं.

इसके बाद, एंट्री पाने के लिए, हमें बस सेवा के getEntry तरीके पर कॉल करना होगा.

ध्यान दें कि हम getEntry को पैरामीटर के तौर पर EventEntry.class देते हैं. इससे पता चलता है कि हम सिर्फ़ सामान्य एंट्री के बजाय, इवेंट को दिखाने की उम्मीद कर रहे हैं. कैलेंडर के अलावा अन्य सेवाओं के लिए, शायद आप सिर्फ़ Entry.class पास करना चाहें.

ऊपर दिया गया कोड सही पुष्टि के साथ, कैलेंडर पर GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID भेजने के बराबर है.

एंट्री खोजी जा रही हैं

पूरे टेक्स्ट की खोज से पहला मिलान पाने के लिए, इस कोड का इस्तेमाल करें:

Query myQuery = new Query(feedUrl);
myQuery.setFullTextQuery("Tennis");
Feed myResultsFeed = myService.query(myQuery, Feed.class);
if (myResultsFeed.getEntries().size() > 0) {
  Entry firstMatchEntry = myResultsFeed.getEntries().get(0);
  String myEntryTitle = firstMatchEntry.getTitle().getPlainText();
}

यह उदाहरण एक Query ऑब्जेक्ट बनाने से शुरू होता है, जिसमें ज़्यादातर यूआरएल और उससे जुड़े क्वेरी पैरामीटर शामिल होते हैं. हर एक मानक GData क्वेरी पैरामीटर में सेटर विधि होती है. addCustomParameter तरीके का इस्तेमाल करके, किसी खास सेवा के लिए कस्टम क्वेरी पैरामीटर भी सेट किए जा सकते हैं.

Query बनाने के बाद, हम इसे सेवा के query तरीके को पास करते हैं, जिससे क्वेरी फ़ीड वाला फ़ीड मिलता है. इसका दूसरा तरीका यह है कि आप खुद यूआरएल बनाएं (फ़ीड यूआरएल में क्वेरी पैरामीटर जोड़कर) और फिर getFeed तरीके को कॉल करें. हालांकि, query मैथड, ऐब्स्ट्रैक्शन की एक उपयोगी लेयर देता है, ताकि आपको यूआरएल खुद न बनाना पड़े.

फ़ीड का getEntries तरीका, फ़ीड में एंट्री की सूची दिखाता है; getEntries().size, फ़ीड में एंट्री की संख्या दिखाता है.

इस मामले में, अगर क्वेरी से कोई नतीजा मिलता है, तो हम Entry ऑब्जेक्ट को मैच करने वाला पहला नतीजा असाइन करते हैं. इसके बाद, हम एंट्री का शीर्षक वापस पाने और उसे टेक्स्ट में बदलने के लिए, Entry क्लास के getTitle().getPlainText तरीके का इस्तेमाल करते हैं.

ऊपर दिया गया कोड, GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full?q=Tennis को कैलेंडर पर भेजने के बराबर है.

कैटगरी के हिसाब से क्वेरी करना

ध्यान दें: Google Calendar, लेबल को इवेंट से नहीं जोड़ता है. इसलिए, यह उदाहरण Calendar के साथ काम नहीं करता.

पहले पूरे टेक्स्ट की खोज से मेल खाने वाली और किसी खास श्रेणी के या सभी खास लेबल वाली सभी एंट्री वाले फ़ीड को वापस पाने के लिए, नीचे दिए गए कोड का इस्तेमाल करें:

Category myCategory = new Category("by_liz");
CategoryFilter myCategoryFilter = new CategoryFilter(myCategory);
myQuery.addCategoryFilter(myCategoryFilter);
Feed myCategoryResultsFeed = myService.query(myQuery, Feed.class);

बेशक, Category क्लास किसी कैटगरी फ़िल्टर में इस्तेमाल की जाने वाली कैटगरी को दिखाती है. Query.CategoryFilter क्लास में कई कैटगरी हो सकती हैं, लेकिन इस मामले में हम सिर्फ़ एक कैटगरी वाला फ़िल्टर बना रहे हैं.

इसके बाद, उस फ़िल्टर को मौजूदा क्वेरी में जोड़ दिया जाता है. इसमें, पिछले उदाहरण में इस्तेमाल की गई, पूरे टेक्स्ट वाली क्वेरी स्ट्रिंग शामिल होती है.

हम सेवा को क्वेरी भेजने के लिए फिर से query तरीके का इस्तेमाल करते हैं.

अगर कैलेंडर में कैटगरी खोजने की अनुमति है, तो ऊपर दिया गया कोड, Calendar पर GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/-/by_liz?q=Tennis को भेजने के बराबर होगा.

किसी आइटम को अपडेट करना

किसी मौजूदा आइटम को अपडेट करने के लिए, इस कोड का इस्तेमाल करें. इस उदाहरण में, हम पहले प्राप्त की गई प्रविष्टि के शीर्षक को उसके पुराने लेख ("डर्नी के साथ टेनिस") से "ज़रूरी मीटिंग" में बदल रहे हैं.

retrievedEntry.setTitle(new PlainTextConstruct("Important meeting"));
URL editUrl = new URL(retrievedEntry.getEditLink().getHref());
EventEntry updatedEntry = myService.update(editUrl, myEntry);

पहले हमने उस एंट्री के लिए एक नया शीर्षक सेट किया था जो हमने पहले फ़ेच की थी. इसके बाद, हमें getEditLink तरीके का इस्तेमाल करके, यूआरएल में बदलाव करने का यूआरएल मिलता है. इसके बाद, हम अपडेट की गई एंट्री भेजने के लिए, सेवा के update तरीके को कॉल करते हैं.

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

ऊपर दी गई कोड, मूल एंट्री को बदलने के लिए (ऐटम फ़ॉर्मैट में) नई जानकारी के साथ, सेवा को PUT http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID भेजने जैसा ही है.

कोई आइटम मिटाना

अपडेट की गई एंट्री मिटाने के लिए, नीचे दिए गए कोड का इस्तेमाल करें:

URL deleteUrl = new URL(updatedEntry.getEditLink().getHref());
myService.delete(deleteUrl);

मिटाने के लिए इस्तेमाल किया जाने वाला यूआरएल और यूआरएल में बदलाव, एक ही है. इसलिए, यह उदाहरण पिछले वाले से काफ़ी मिलता-जुलता है, सिवाय इसके कि हम update के बजाय delete तरीके को कॉल कर रहे हैं.

ऊपर दिया गया कोड, DELETE http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID को सेवा में भेजने के करीब बराबर है.

रेफ़रंस

क्लास लाइब्रेरी और क्लाइंट लाइब्रेरी से दिए गए तरीकों के बारे में जानने के लिए, Java क्लाइंट लाइब्रेरी एपीआई का रेफ़रंस (Javadoc फ़ॉर्मैट में) देखें.

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