Android पर Tasks API का इस्तेमाल करना

चेतावनी: यह दस्तावेज़ अब काम नहीं करता. OAuth 2.0 का इस्तेमाल करके, Android ऐप्लिकेशन को अनुमति देने के बारे में जानकारी के लिए, कृपया Android Play services को अनुमति देने से जुड़ा दस्तावेज़.

इस दस्तावेज़ में Android पर OAuth 2.0 के साथ Tasks API का इस्तेमाल करने का तरीका बताया गया है. यह उपयोगकर्ता के Google Tasks का ऐक्सेस पाने के लिए, अनुमति पाने के तरीके के बारे में बताता है. साथ ही, यह भी बताता है कि कैसे अपने Android ऐप्लिकेशन में Tasks API सेवा ऑब्जेक्ट को इस्तेमाल करने के लिए तैयार रखा जा सकता है.

आपके Android ऐप्लिकेशन को Tasks API का इस्तेमाल करने के लिए कई चरणों को पूरा करना होगा. इसके लिए:

1. उपयोगकर्ता का Google खाता चुनें
2. Task API के लिए, AccountManager से OAuth 2.0 का ऐक्सेस टोकन पाएं
3. अपने प्रोजेक्ट को पहचानें और Tasks सेवा ऑब्जेक्ट सेट अप करें
4. Tasks एपीआई को कॉल करना

Google की क्लाइंट लाइब्रेरी इंपोर्ट करना

इस दस्तावेज़ में दिए गए सैंपल, Java के लिए Google API क्लाइंट लाइब्रेरी का इस्तेमाल करते हैं. आपको अपने Android ऐप्लिकेशन में ये जार जोड़ने होंगे. ऐसा करने के लिए, नीचे दी गई सूची में शामिल जार को अपने Android ऐप्लिकेशन के रूट में /assets फ़ोल्डर में रखें. साथ ही, फ़ाइल के नए वर्शन भी देखें, क्योंकि यह पुराना होता जा रहा है.

Google API क्लाइंट लाइब्रेरी जार और उसके Android एक्सटेंशन (google-api-java-client-1.4.1-beta.zip के सभी हिस्से) इंपोर्ट करें:

• google-api-client-1.4.1-beta.jar
• google-api-client-extensions-android2-1.4.1-beta.jar
• google-api-client-googleapis-1.4.1-beta.jar
• google-api-client-googleapis-extensions-android2-1.4.1-beta.jar

Tasks खास जार इंपोर्ट करें:

• google-api-services-tasks-v1-1.1.0-beta.jar

डिपेंडेंसी इंपोर्ट करें (google-api-java-client-1.4.1-beta.zip के सभी हिस्से):

• कॉमन्स-कोडेक-1.3.जारीर
• जीसन-1.6.जारीर
• अमरूद-r09.Jर
• httpclient-4.0.3.jar
• httpकोर-4.0.1.Jर
• jackson-core-asl-1.6.7.jar
• jsr305-1.3.9.Jर

Android में Google खाते

Android 2.0 के बाद से, AccountManager उन खातों को प्रबंधित करता है जिन्हें आपने अपने वातावरण में पंजीकृत किया है, जो सेटिंग > खाते और सिंक करें. खास तौर पर, यह ऑथराइज़ेशन फ़्लो को मैनेज करता है. साथ ही, यह ऐसे ऑथराइज़ेशन टोकन जनरेट कर सकता है जो एपीआई का इस्तेमाल करके डेटा ऐक्सेस करने के लिए ज़रूरी हैं.

आपके Android एनवायरमेंट में रजिस्टर किए गए खाते

खाते पाने और प्राधिकरण टोकन का अनुरोध करने के लिए AccountManager का इस्तेमाल करने के लिए आपको अपने Android ऐप्लिकेशन मेनिफ़ेस्ट में ये अनुमतियां जोड़नी होंगी:

<uses-permission android:name="android.permission.GET_ACCOUNTS" />
<uses-permission android:name="android.permission.USE_CREDENTIALS" />

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

AccountManager accountManager = AccountManager.get(activity);
Account[] accounts = accountManager.getAccountsByType("com.google");

इसके अलावा, Java के लिए Google API की क्लाइंट लाइब्रेरी में GoogleAccountManager होता है, जो सिर्फ़ Google खातों को मैनेज करता है:

GoogleAccountManager googleAccountManager = new GoogleAccountManager(activity);
Account[] accounts = googleAccountManager.getAccounts();

अगर Android डिवाइस पर एक से ज़्यादा Google खाते मौजूद हैं, तो आपको उपयोगकर्ता को उस खाते का प्रॉम्प्ट भेजना होगा जिसका वह इस्तेमाल करना चाहता है. इसके लिए, डायलॉग बॉक्स इस तरह से दिखेगा:

'खाता चुनें' डायलॉग

आप अपनी गतिविधि के onCreateDialog तरीके में नीचे दिए गए स्विच/केस कोड का इस्तेमाल करके ऐसा डायलॉग बना सकते हैं:

@Override
protected Dialog onCreateDialog(int id) {
  switch (id) {
    case DIALOG_ACCOUNTS:
      AlertDialog.Builder builder = new AlertDialog.Builder(this);
      builder.setTitle("Select a Google account");
      final Account[] accounts = accountManager.getAccountsByType("com.google");
      final int size = accounts.length;
      String[] names = new String[[]size];
      for (int i = 0; i < size; i++) {
        names[[]i] = accounts[[]i].name;
      }
      builder.setItems(names, new DialogInterface.OnClickListener() {
        public void onClick(DialogInterface dialog, int which) {
          // Stuff to do when the account is selected by the user
          gotAccount(accounts[[]which]);
        }
      });
      return builder.create();
  }
  return null;
}

showDialog(DIALOG_ACCOUNTS) को कॉल करने से खाता चुनने वाला डायलॉग दिखाई देगा.

Android पर Google API का ऑथराइज़ेशन फ़्लो

अब जब उपयोगकर्ता ने वह खाता चुन लिया है, तो हम AccountManager से Task API के लिए OAuth 2.0 ऐक्सेस टोकन जारी करने के लिए कह सकते हैं. ऐसा करने के लिए, AccountManager.getAuthToken() तरीके को कॉल किया जाता है. AccountManager.getAuthToken() को कॉल करते समय Google API के ऑथराइज़ेशन एंडपॉइंट से संपर्क करने के लिए, AccountManager ध्यान रखेगा. जब AccountManager को अनुमति वाला टोकन फिर से मिल जाएगा, तब वह AccountManagerCallback चलाएगा, जिसे आपने तरीके कॉल में तय किया है:

manager.getAuthToken(account, AUTH_TOKEN_TYPE, null, activity, new AccountManagerCallback<Bundle>() {
    public void run(AccountManagerFuture<Bundle> future) {
      try {
        // If the user has authorized your application to use the tasks API
        // a token is available.
        String token = future.getResult().getString(AccountManager.KEY_AUTHTOKEN);
        // Now you can use the Tasks API...
        useTasksAPI(token);
      } catch (OperationCanceledException e) {
        // TODO: The user has denied you access to the API, you should handle that
      } catch (Exception e) {
        handleException(e);
      }
    }
  }, null);

जैसा कि आपको पहले से पता होगा कि Android AccountManager में OAuth 2.0 के लिए एक्सपेरिमेंट के तौर पर काम किया जाता है. AUTH_TOKEN_TYPE सेट करते समय आपको बस oauth2: के साथ जिस एपीआई का ऐक्सेस चाहिए उसके दायरे से पहले उसे प्रीफ़िक्स करना होगा. इसलिए, Tasks API के लिए इसका इस्तेमाल किया जा सकता है:

String AUTH_TOKEN_TYPE = "oauth2:https://www.googleapis.com/auth/tasks";

ऊपर दिए गए मान को AUTH_TOKEN_TYPE के तौर पर इस्तेमाल करते समय समस्या यह है कि अनुमति देने वाले डायलॉग में oauth2:https://www.googleapis.com/auth/tasks उस Google प्रॉडक्ट के नाम के तौर पर दिखेगा जिसे आपको ऐक्सेस करना है. इस समस्या से बचने के लिए, Tasks API के लिए AUTH_TOKEN_TYPE उपनाम मौजूद हैं. खास — लोगों को आसानी से पढ़ा जा सकता है. इनकी मदद से, OAuth 2.0 के स्कोप का इस्तेमाल किया जा सकता है. उदाहरण के लिए, इनका इस्तेमाल किया जा सकता है:

String AUTH_TOKEN_TYPE = "Manage your tasks";

आप AUTH_TOKEN_TYPE उपनाम का भी इस्तेमाल कर सकते हैं अपने टास्क देखें, जो कि Tasks API में मौजूद रीड-ओनली ऐक्सेस के बराबर है स्कोप: oauth2:https://www.googleapis.com/auth/tasks.readonly.

AccountManager.getAuthToken() को कॉल करने के दौरान AccountManager यह जांच करेगा कि आपके ऐप्लिकेशन को Tasks API ऐक्सेस करने की अनुमति मिली है या नहीं. अगर आपके ऐप्लिकेशन को अभी तक अनुमति नहीं मिली है, तो AccountManager एक गतिविधि शुरू कर देता है, जो उपयोगकर्ता को अनुमति देने वाला एक डायलॉग दिखाता है. इससे, उपयोगकर्ता अपने खाते पर Tasks API का इस्तेमाल करने के लिए आपके ऐप्लिकेशन को अनुमति दे या अस्वीकार कर सकते हैं.

प्राधिकरण संवाद

अगर उपयोगकर्ता, Tasks API के लिए आपके ऐप्लिकेशन को ऐक्सेस करने से इनकार करता है, तो OperationCanceledException कॉल के दौरान OperationCanceledException को ट्रिगर किया जाएगा. उदाहरण के लिए, आपको इस बात को अच्छी तरह से मैनेज करना चाहिए. इसके लिए, आपको फिर से खाता चुनने के लिए कहना चाहिए या फिर से ऐक्सेस देने की अनुमति देने के लिए, बटन के साथ मैसेज दिखाना चाहिए.

आपके ऐप्लिकेशन की पहचान करना और Tasks API सर्विस ऑब्जेक्ट सेट अप करना

अब आपके ऐप्लिकेशन के पास Tasks API को ऐक्सेस करने की अनुमति है और उसे ऐक्सेस टोकन मिल गया है. इसलिए, आपको एपीआई पासकोड की भी ज़रूरत होगी. यह पासकोड आपको Google API कंसोल में किसी प्रोजेक्ट से मिलेगा, क्योंकि यह Tasks API कॉल करने के लिए ज़रूरी है. ऐसा करने के लिए, यह तरीका अपनाएं:

1. प्रोजेक्ट बनाएं या किसी मौजूदा प्रोजेक्ट का इस्तेमाल करें
2. Tasks API स्विच को चालू है पर टॉगल करके, अपने प्रोजेक्ट पर Tasks API चालू करें
3. एपीआई पासकोड, एपीआई ऐक्सेस > सरल API पहुंच > एपीआई पासकोड

API कंसोल से API कुंजी पाना

एपीआई पासकोड ज़रूरी है, क्योंकि यह आपके ऐप्लिकेशन की पहचान करता है. इसलिए, एपीआई को कोटा काटने और आपके प्रोजेक्ट के लिए तय किए गए कोटा के नियमों का इस्तेमाल करने की अनुमति मिलती है. आपको अपने Tasks सेवा ऑब्जेक्ट पर एपीआई पासकोड बताना होगा:

useTasksAPI(String accessToken) {
  // Setting up the Tasks API Service
  HttpTransport transport = AndroidHttp.newCompatibleTransport();
  AccessProtectedResource accessProtectedResource = new GoogleAccessProtectedResource(accessToken);
  Tasks service = new Tasks(transport, accessProtectedResource, new JacksonFactory());
  service.accessKey = INSERT_YOUR_API_KEY;
  service.setApplicationName("Google-TasksSample/1.0");

  // TODO: now use the service to query the Tasks API
}

accessToken तय समय के लिए ही मान्य है. इसलिए, इसकी समयसीमा खत्म होने पर आपको एक नया लेना होगा. इसे मैनेज करने के दो तरीके हैं:

• हर बार एपीआई का इस्तेमाल करके अनुरोध करने पर, AccountManager के लिए accessToken का अनुरोध करें. AccountManager टोकन को कैश मेमोरी में सेव करता है, इसलिए इस तरीके का इस्तेमाल किया जा सकता है.
• अपने accessToken का इस्तेमाल तब तक करते रहें, जब तक कि आपको 403 वाली गड़बड़ी का मैसेज न मिले. उस समय आपको AccountManager से नया टोकन भेजने के लिए कहा जाता है.

एपीआई की मदद से टास्क में बदलाव करना

अब आपके पास पूरी तरह से सेट अप किया गया Tasks API सेवा ऑब्जेक्ट होना चाहिए. इसका इस्तेमाल Tasks API डेवलपर की गाइड के मुताबिक, एपीआई से क्वेरी करने के लिए किया जा सकता है. उदाहरण के लिए:

// Getting all the Task lists
List taskLists = service.tasklists.list().execute().items;

// Getting the list of tasks in the default task list
List tasks = service.tasks.list("@default").execute().items;

// Add a task to the default task list
Task task = new Task();
task.title = "New Task";
task.notes = "Please complete me";
task.due = "2010-10-15T12:00:00.000Z";
Task result = service.tasks.insert("@default", task).execute();

अपने Android ऐप्लिकेशन मेनिफ़ेस्ट में इंटरनेट को ऐक्सेस करने की अनुमति जोड़ना न भूलें. ऐसा न करने पर, Tasks एपीआई एंडपॉइंट पर ऊपर दिए गए अनुरोध इंस्टॉल नहीं हो पाएंगे:

<uses-permission android:name="android.permission.INTERNET" />

सैंपल ऐप्लिकेशन

हमने हाल ही में, Java सैंपल डेटा स्टोर करने की जगह के लिए Google API क्लाइंट लाइब्रेरी में एक नया सैंपल जोड़ा है. इससे आपको Android पर Tasks API और OAuth 2.0 का इस्तेमाल शुरू करने में मदद मिलेगी. यह नमूना एक सरल, लेकिन पूरी तरह से काम करने वाला Android ऐप्लिकेशन है, जो Tasks API का इस्तेमाल करने की अनुमति मांगता है और डिफ़ॉल्ट टास्क सूची के टास्क को ListView में दिखाता है.

लिस्ट व्यू में, डिफ़ॉल्ट टास्क की सूची में टास्क दिखाए जा रहे हैं

सैंपल को चलाने के लिए, इन निर्देशों का पालन करें. साथ ही, अपने सुझाव या सवाल Google Tasks API फ़ोरम पर पोस्ट करने में न झिझकें.