Используйте API Задач на Android

Предупреждение: этот документ устарел. Информацию об авторизации приложений Android с использованием OAuth 2.0 см. в документации по авторизации служб Android Play .

В этом документе объясняется, как использовать API задач с OAuth 2.0 на Android. В нем описываются механизмы авторизации для получения доступа к задачам Google пользователя и то, как вы можете иметь готовый к использованию объект службы API задач в своем приложении Android.

Чтобы ваше Android-приложение могло использовать Tasks API, необходимо выполнить несколько шагов:

  1. Выберите учетную запись Google пользователя.
  2. Получите токен доступа OAuth 2.0 из AccountManager для Task API.
  3. Определите свой проект и настройте службу задач. Объект
  4. Выполнение вызовов API задач

Импорт клиентской библиотеки Google

В примерах, которые вы найдете в этом документе, используется клиентская библиотека API Google для Java . Вам нужно будет добавить следующие jar-файлы в свое приложение для Android. Для этого поместите перечисленные ниже jar-файлы в папку /assets в корне вашего приложения для Android. Также проверяйте наличие новых версий по мере старения этого документа.

Импортируйте jar-файлы клиентской библиотеки 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

Импортируйте конкретный jar-файл Tasks:

Импортировать зависимости (вся часть google-api-java-client-1.4.1-beta.zip ):

  • Commons-кодек-1.3.jar
  • gson-1.6.jar
  • гуава-r09.jar
  • httpclient-4.0.3.jar
  • httpcore-4.0.1.jar
  • Джексон-ядро-ASL-1.6.7.jar
  • jsr305-1.3.9.jar

Аккаунты Google в Android

Начиная с Android 2.0, AccountManager управляет учетными записями, которые вы зарегистрировали в своей среде и которые перечислены в разделе «Настройки» > «Учетные записи и синхронизация» . В частности, он обрабатывает поток авторизации и может генерировать токены авторизации, необходимые для доступа к данным с помощью API.

Аккаунты, зарегистрированные в вашей среде Android
Аккаунты, зарегистрированные в вашей среде Android

Чтобы иметь возможность использовать AccountManager для получения учетных записей и запроса токенов авторизации, вам необходимо добавить следующие разрешения в манифест приложения Android:

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

Вы можете использовать AccountManager , чтобы получить учетную запись Google, для которой вы хотите получить доступ к задачам. AccountManager управляет не только учетными записями Google, но и учетными записями других поставщиков. Поэтому вам нужно будет специально запросить учетные записи Google, используя приведенный ниже код:

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

В качестве альтернативы клиентская библиотека API Google для Java поставляется с 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) отобразит диалоговое окно выбора учетной записи.

Процесс авторизации API Google на Android

Теперь, когда пользователь выбрал учетную запись, мы можем попросить AccountManager выдать токен доступа OAuth 2.0 для Task API. Это делается путем вызова метода AccountManager.getAuthToken() . Во время вызова AccountManager.getAuthToken() AccountManager позаботится о соединении с конечной точкой авторизации API Google. Когда 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 . Итак, для API задач вы можете использовать:

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

Проблема при использовании приведенного выше значения в качестве AUTH_TOKEN_TYPE заключается в том, что строка oauth2:https://www.googleapis.com/auth/tasks будет отображаться в диалоговом окне авторизации как имя продукта Google, к которому вы хотите получить доступ. Чтобы обойти эту проблему, для API задач существуют специальные удобочитаемые псевдонимы AUTH_TOKEN_TYPE . Они эквивалентны использованию области OAuth 2.0. Например, вы можете использовать:

String AUTH_TOKEN_TYPE = "Manage your tasks";

Вы также можете использовать псевдоним AUTH_TOKEN_TYPE . Просмотр задач , который эквивалентен области доступа только для чтения API задач: oauth2:https://www.googleapis.com/auth/tasks.readonly .

Во время вызова AccountManager.getAuthToken() AccountManager проверит, разрешено ли вашему приложению доступ к API задач. Если ваше приложение еще не авторизовано, AccountManager запускает действие , которое отображает диалоговое окно авторизации для пользователя, чтобы он мог разрешить или запретить вашему приложению использовать API задач в своей учетной записи.

Диалог авторизации
Диалог авторизации

Если пользователь запрещает вашему приложению доступ к API задач, во время вызова Future.getResult() будет выброшено исключение OperationCanceledException . Вы должны справиться с этим изящно, например, попросив снова выбрать учетную запись или отобразив сообщение с кнопкой для повторного авторизации доступа.

Идентификация вашего приложения и настройка объекта службы Tasks API

Теперь, когда ваше приложение имеет авторизацию для доступа к API задач и ему предоставлен токен доступа, вам также понадобится ключ API , который вам нужно получить из проекта в консоли API Google, поскольку он является обязательным для выполнения вызовов API задач. Для этого выполните следующие действия:

  1. Создайте проект или используйте существующий
  2. Включите API задач в своем проекте, переключив переключатель API задач в положение ВКЛ.
  3. Ключ API можно найти в разделе «Доступ к API» > «Простой доступ к API» > «Ключ API».

Получение ключа API из консоли API
Получение ключа API из консоли API

Ключ API является обязательным, поскольку он идентифицирует ваше приложение и, следовательно, позволяет API вычитать квоту и использовать правила квот, определенные для вашего проекта. Вам необходимо указать ключ API для вашего объекта службы задач:

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 способа справиться с этим:

  • Запрашивайте токен доступа к AccountManager каждый раз, когда вы делаете запросы через API. Поскольку AccountManager кэширует токен, это решение приемлемо.
  • Продолжайте использовать свой accessToken , пока не получите ошибку 403, после чего вы запросите новый токен для AccountManager .

Управление задачами через API

На этом этапе у вас должен быть полностью настроен объект службы API задач, который вы можете использовать для запроса API в соответствии с Руководством разработчика 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" />

Образец заявления

Недавно мы добавили новый образец в репозиторий примеров клиентской библиотеки Google API для Java, который поможет вам начать работу с Tasks API и OAuth 2.0 на Android. Пример представляет собой простое, но полностью работающее приложение Android, которое запрашивает авторизацию для использования API задач и отображает задачи списка задач по умолчанию в ListView.

Отображение задач в списке задач по умолчанию в ListView
Отображение задач в списке задач по умолчанию в ListView

Следуйте этим инструкциям , чтобы запустить пример, и не стесняйтесь оставлять свои отзывы и вопросы на форуме Google Tasks API .