Cette page a été traduite par l'API Cloud Translation.

Utiliser l'API Tasks sur Android

Avertissement: Ce document est obsolète. Pour en savoir plus sur l'autorisation des applications Android à l'aide d'OAuth 2.0, consultez la documentation sur l'autorisation des services Android Play.

Ce document explique comment utiliser l'API Tasks avec OAuth 2.0 sur Android. Il décrit les mécanismes d'autorisation permettant d'accéder à Google Tasks d'un utilisateur et comment disposer d'un objet service API Tasks prêt à l'emploi dans votre application Android.

Pour que votre application Android puisse utiliser l'API Tasks, vous devez suivre plusieurs étapes:

Sélectionnez le compte Google de l'utilisateur.
Obtenir un jeton d'accès OAuth 2.0 auprès du AccountManager pour l'API Task
Identifier votre projet et configurer l'objet de service Tasks
Appeler l'API Tasks

Importer la bibliothèque cliente de Google

Les exemples de ce document utilisent la bibliothèque cliente des API Google pour Java. Vous devez ajouter les fichiers JAR suivants à votre application Android. Pour ce faire, placez les fichiers JAR listés ci-dessous dans le dossier /assets à la racine de votre application Android. Recherchez également de nouvelles versions à mesure que ce document vieillit.

Importez les fichiers JAR de la bibliothèque cliente des API Google et ses extensions Android (qui font toutes partie de 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

Importez le fichier JAR spécifique à Tasks:

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

Importez les dépendances (toutes incluses dans 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

Comptes Google sur Android

Depuis Android 2.0, AccountManager gère les comptes que vous avez enregistrés dans votre environnement, ceux qui sont listés sous Settings > Accounts & sync (Paramètres > Comptes et synchronisation). Plus précisément, il gère le flux d'autorisation et peut générer des jetons d'autorisation requis pour accéder aux données à l'aide d'API.

Comptes enregistrés dans votre environnement Android

Pour pouvoir utiliser AccountManager pour obtenir des comptes et demander des jetons d'autorisation, vous devez ajouter les autorisations suivantes dans le fichier manifeste de votre application Android:

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

Vous pouvez utiliser AccountManager pour obtenir le compte Google pour lequel vous souhaitez accéder à Tasks. AccountManager gère non seulement les comptes Google, mais aussi ceux d'autres fournisseurs. Vous devez donc demander spécifiquement des comptes Google à l'aide du code ci-dessous:

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

La bibliothèque cliente des API Google pour Java est également fournie avec un GoogleAccountManager qui ne gère que les comptes Google:

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

Si plusieurs comptes Google sont disponibles sur l'appareil Android, vous devez demander à l'utilisateur de choisir celui qu'il souhaite utiliser à l'aide d'une boîte de dialogue qui peut se présenter comme suit:

Boîte de dialogue de choix du compte

Vous pouvez créer une telle boîte de dialogue à l'aide du code switch/case suivant dans la méthode onCreateDialog de votre activité:

@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;
}

L'appel de showDialog(DIALOG_ACCOUNTS) affiche la boîte de dialogue de sélection du compte.

Flux d'autorisation des API Google sur Android

Maintenant que l'utilisateur a choisi un compte, nous pouvons demander à AccountManager d'émettre un jeton d'accès OAuth 2.0 pour l'API Task. Pour ce faire, appelez la méthode AccountManager.getAuthToken(). Lors de l'appel AccountManager.getAuthToken(), AccountManager se charge de contacter le point de terminaison d'autorisation des API Google. Lorsque le AccountManager a récupéré le jeton d'autorisation, il exécute le AccountManagerCallback que vous avez défini dans l'appel de méthode:

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);

Comme vous le savez peut-être déjà, le AccountManager d'Android est compatible de manière expérimentale avec OAuth 2.0. Il vous suffit de préfixer le champ d'application de l'API à laquelle vous souhaitez accéder par oauth2: lorsque vous définissez AUTH_TOKEN_TYPE. Pour l'API Tasks, vous pouvez utiliser:

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

Le problème qui se produit lorsque vous utilisez la valeur ci-dessus comme AUTH_TOKEN_TYPE est que la chaîne oauth2:https://www.googleapis.com/auth/tasks s'affiche dans la boîte de dialogue d'autorisation en tant que nom du produit Google auquel vous souhaitez accéder. Pour contourner ce problème, des alias AUTH_TOKEN_TYPE spéciaux (lisibles par l'homme) existent pour l'API Tasks. Ils sont équivalents à l'utilisation du champ d'application OAuth 2.0. Vous pouvez par exemple utiliser:

String AUTH_TOKEN_TYPE = "Manage your tasks";

Vous pouvez également utiliser l'alias AUTH_TOKEN_TYPE Afficher vos tâches, qui équivaut au champ d'application en lecture seule de l'API Tasks: oauth2:https://www.googleapis.com/auth/tasks.readonly.

Lors de l'appel AccountManager.getAuthToken(), AccountManager vérifie si votre application a été autorisée à accéder à l'API Tasks. Si votre application n'a pas encore été autorisée, une activité est lancée par le AccountManager, qui affiche une boîte de dialogue d'autorisation à l'utilisateur afin qu'il puisse autoriser ou refuser votre application à utiliser l'API Tasks sur son compte.

Boîte de dialogue d'autorisation

Si l'utilisateur refuse l'accès de votre application à l'API Tasks, une exception OperationCanceledException est générée lors de l'appel future.getResult(). Vous devez gérer cela de manière élégante, par exemple en demandant à choisir à nouveau le compte ou en affichant un message avec un bouton permettant d'autoriser à nouveau l'accès.

Identifier votre application et configurer l'objet de service de l'API Tasks

Maintenant que votre application est autorisée à accéder à l'API Tasks et qu'elle a reçu un jeton d'accès, vous avez également besoin d'une clé API que vous devez obtenir à partir d'un projet dans la console Google APIs, car elle est obligatoire pour effectuer des appels à l'API Tasks. Pour cela, procédez comme suit:

Créer un projet ou utiliser un projet existant
Activez l'API Tasks dans votre projet en basculant le bouton de l'API Tasks sur ON (Activer).
La clé API se trouve sous API Access > Simple API Access > API Key (Accès à l'API > Accès simple à l'API > Clé API).

Obtenir la clé API à partir de la console APIs

La clé API est obligatoire, car elle identifie votre application et permet donc à l'API de déduire des quotas et d'utiliser les règles de quota définies pour votre projet. Vous devez spécifier la clé API dans l'objet service 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
}

Le accessToken n'est valide que pendant un certain temps. Vous devrez donc en obtenir un nouveau lorsqu'il expirera. Vous pouvez procéder de deux façons:

Demandez un accessToken au AccountManager chaque fois que vous effectuez des requêtes via l'API. Étant donné que le AccountManager met en cache le jeton, cette solution est acceptable.
Continuez à utiliser votre accessToken jusqu'à ce que vous receviez une erreur 403, auquel cas vous demandez un nouveau jeton à AccountManager.

Manipuler des tâches via l'API

À ce stade, vous devriez disposer d'un objet service API Tasks entièrement configuré que vous pouvez utiliser pour interroger l'API conformément au guide du développeur pour l'API Tasks, par exemple:

// 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();

N'oubliez pas d'ajouter l'autorisation d'accès à Internet à votre fichier manifeste d'application Android, sinon les requêtes ci-dessus aux points de terminaison de l'API Tasks échoueront:

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

Exemple d'application

Nous avons récemment ajouté un nouvel exemple au dépôt d'exemples de la bibliothèque cliente des API Google pour Java pour vous aider à vous familiariser avec l'API Tasks et OAuth 2.0 sur Android. Il s'agit d'une application Android simple, mais entièrement fonctionnelle, qui demande l'autorisation d'utiliser l'API Tasks et d'afficher les tâches de la liste de tâches par défaut dans une ListView.

Afficher les tâches dans la liste de tâches par défaut dans une ListView

Suivez ces instructions pour exécuter l'exemple. N'hésitez pas à poster vos commentaires ou vos questions sur le forum de l'API Google Tasks.

Utiliser l'API Tasks sur Android Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.