از Tasks API در اندروید استفاده کنید

هشدار: این سند منسوخ شده است. برای کسب اطلاعات در مورد مجوز دادن به برنامه‌های Android با استفاده از OAuth 2.0، لطفاً به مستندات مجوز خدمات Android Play نگاهی بیندازید.

این سند نحوه استفاده از Tasks API با OAuth 2.0 در اندروید را توضیح می دهد. مکانیسم‌های مجوز برای دسترسی به Google Tasks کاربر و نحوه استفاده از سرویس Tasks API Object را در برنامه Android خود شرح می‌دهد.

برای اینکه برنامه اندروید شما از Tasks API استفاده کند چندین مرحله لازم است، باید:

1. حساب Google کاربر را انتخاب کنید
2. یک نشانه دسترسی OAuth 2.0 از AccountManager برای Task API دریافت کنید
3. پروژه خود را شناسایی کرده و سرویس Tasks را راه اندازی کنید شیء
4. با Tasks API تماس بگیرید

وارد کردن کتابخانه مشتری Google

نمونه هایی که در این سند خواهید یافت از کتابخانه سرویس گیرنده Google APIs برای جاوا استفاده می کنند. شما باید jar های زیر را به برنامه اندروید خود اضافه کنید، برای انجام این کار، jar های لیست شده در زیر را در پوشه /assets در ریشه برنامه اندروید خود قرار دهید. با قدیمی شدن این سند، نسخه های جدید را نیز بررسی کنید.

شیشه‌های کتابخانه سرویس گیرنده Google APIs و برنامه‌های افزودنی 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.jar
• guava-r09.jar
• httpclient-4.0.3.jar
• httpcore-4.0.1.jar
• jackson-core-asl-1.6.7.jar
• jsr305-1.3.9.jar

حساب های گوگل در اندروید

از Android 2.0، AccountManager حساب‌هایی را که در محیط خود ثبت کرده‌اید مدیریت می‌کند، حساب‌هایی که در زیر تنظیمات > حساب‌ها و همگام‌سازی فهرست شده‌اند. به طور خاص، جریان مجوز را کنترل می کند و می تواند توکن های مجوزی را ایجاد کند که برای دسترسی به داده ها با استفاده از API ها مورد نیاز است.

حساب های ثبت شده در محیط اندروید شما

برای اینکه بتوانید از AccountManager برای دریافت حساب‌ها و درخواست نشانه‌های مجوز استفاده کنید، باید مجوزهای زیر را در مانیفست برنامه Android خود اضافه کنید:

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

می‌توانید از AccountManager برای دریافت حساب Google که می‌خواهید به آن Tasks دسترسی داشته باشید، استفاده کنید. AccountManager نه تنها حساب‌های Google را مدیریت می‌کند، بلکه حساب‌های سایر فروشندگان را نیز مدیریت می‌کند. بنابراین باید با استفاده از کد زیر به طور خاص حساب های گوگل را درخواست کنید:

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

از طرف دیگر، کتابخانه سرویس گیرنده Google APIs برای جاوا همراه با GoogleAccountManager است که فقط حساب‌های Google را مدیریت می‌کند:

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

اگر بیش از یک حساب Google در دستگاه Android موجود است، باید از کاربر بخواهید حسابی را که می‌خواهد از آن استفاده کند، با گفتگویی که می‌تواند به شکل زیر باشد:

گفتگوی حساب را انتخاب کنید

می توانید با استفاده از کد سوئیچ/مورد زیر در متد 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) گفتگوی انتخابگر حساب نمایش داده می شود.

جریان مجوز Google API در Android

اکنون که کاربر حسابی را انتخاب کرده است، می‌توانیم از AccountManager بخواهیم که یک نشانه دسترسی OAuth 2.0 برای Task API صادر کند. این کار با فراخوانی متد 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 پشتیبانی آزمایشی دارد. فقط باید دامنه API را که می‌خواهید با oauth2 به آن دسترسی داشته باشید پیشوند کنید: هنگام تنظیم AUTH_TOKEN_TYPE . بنابراین برای Tasks API می توانید از:

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

مشکل هنگام استفاده از مقدار بالا به عنوان AUTH_TOKEN_TYPE این است که رشته oauth2:https://www.googleapis.com/auth/tasks در گفتگوی مجوز به عنوان نام محصول Google که می خواهید به آن دسترسی داشته باشید نمایش داده می شود. برای حل این مشکل، نام مستعار AUTH_TOKEN_TYPE ویژه - قابل خواندن برای انسان - برای Tasks API وجود دارد. آنها معادل استفاده از محدوده 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 را داشته است یا خیر. اگر برنامه شما هنوز مجوز نگرفته است، یک Activity توسط AccountManager شروع می شود که یک گفتگوی مجوز را به کاربر نمایش می دهد تا بتواند به برنامه شما اجازه یا رد استفاده از Tasks API را در حساب خود بدهد.

گفتگوی مجوز

اگر کاربر دسترسی برنامه شما به Tasks API را رد کند، در طول فراخوانی ()future.getResult یک OperationCanceledException پرتاب می شود. برای مثال، با درخواست برای انتخاب مجدد حساب یا نمایش پیامی با دکمه ای برای مجوز مجدد دسترسی، باید با این کار به خوبی رفتار کنید.

شناسایی برنامه شما و راه اندازی Tasks API Service Object

اکنون که برنامه شما مجوز دسترسی به Tasks API را دارد و یک نشانه دسترسی به آن داده شده است، به یک کلید API نیز نیاز دارید که باید از پروژه ای در Google APIs Console دریافت کنید، زیرا برای برقراری تماس های Tasks API اجباری است. برای انجام این کار مراحل زیر را دنبال کنید:

1. یک پروژه ایجاد کنید یا از یک موجود استفاده کنید
2. با روشن کردن کلید Tasks API روی پروژه خود، Tasks API را فعال کنید
3. کلید API را می‌توانید در API Access > Simple API Access > API Key پیدا کنید

دریافت کلید API از کنسول APIs

کلید API اجباری است زیرا برنامه شما را شناسایی می کند و بنابراین به API اجازه می دهد تا سهمیه را کسر کند و از قوانین سهمیه تعریف شده برای پروژه شما استفاده کند. شما باید کلید API را در Object سرویس 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 فقط برای مدت زمان معینی معتبر است، بنابراین پس از انقضای آن باید یک مورد جدید دریافت کنید. 2 راه برای رسیدگی به این موضوع وجود دارد:

• هر بار که از طریق API درخواست می کنید، یک AccessToken به حساب مدیر درخواست کنید. از آنجایی که AccountManager توکن را کش می کند، این راه حل قابل قبول است.
• به استفاده از accessToken خود ادامه دهید تا زمانی که با خطای 403 مواجه شوید و در این مرحله از AccountManager یک توکن جدید بخواهید.

دستکاری وظایف از طریق API

در این مرحله باید یک سرویس Tasks API Object به طور کامل تنظیم کنید که می توانید از آن برای پرس و جو از 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();

فراموش نکنید که مجوز دسترسی به اینترنت را به مانیفست برنامه اندروید خود اضافه کنید، در غیر این صورت درخواست های بالا به نقاط پایانی Tasks API با شکست مواجه خواهند شد:

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

نمونه برنامه

ما اخیراً یک نمونه جدید به مخزن نمونه Google APIs Client Library برای جاوا اضافه کردیم تا به شما در شروع کار با Tasks API و OAuth 2.0 در Android کمک کند. نمونه یک برنامه اندرویدی ساده اما کاملاً کارآمد است که برای استفاده از Tasks API و نمایش وظایف لیست وظایف پیش‌فرض در ListView مجوز درخواست می‌کند.

نمایش وظایف در لیست وظایف پیش فرض در ListView

برای اجرای نمونه، این دستورالعمل‌ها را دنبال کنید و در ارسال بازخورد یا سؤالات خود به تالار گفتگوی Google Tasks API تردید نکنید.