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 API में कॉल करना

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 के सभी हिस्से):

• commons-codec-1.3.jar
• gson-1.6.जार
• guava-r09.jar
• httpclient-4.0.3.jar
• httpcore-4.0.1.जार
• jackson-core-asl-1.6.7.jar
• jsr305-1.3.9.jar

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() को कॉल करने के दौरान AccountManager को कॉल करने से, Google API के ऑथराइज़ेशन एंडपॉइंट से संपर्क किया जाएगा. जब 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 के साथ काम करने की सुविधा प्रयोग के तौर पर उपलब्ध है. oauth2: सेट करते समय, आपको बस 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 कुंजी पाना

एपीआई पासकोड का इस्तेमाल करना ज़रूरी है, क्योंकि इससे आपके ऐप्लिकेशन की पहचान होती है. इसलिए, एपीआई को कोटा की कटौती करने और आपके प्रोजेक्ट के लिए तय किए गए कोटा नियमों का इस्तेमाल करने की अनुमति मिलती है. आपको अपने 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 API एंडपॉइंट पर किए गए ऊपर दिए गए अनुरोध काम नहीं करेंगे:

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

ऐप्लिकेशन का नमूना

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

एक ListView में, डिफ़ॉल्ट टास्क की सूची में टास्क दिखाना

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