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 aux tâches Google d'un utilisateur et explique comment disposer d'un objet service de l'API Tasks prêt à l'emploi dans votre application Android.
Pour que votre application Android utilise l'API Tasks, plusieurs étapes sont nécessaires:
- Sélectionnez le compte Google de l'utilisateur.
- Obtenir un jeton d'accès OAuth 2.0 auprès de AccountManager pour l'API Task
- Identifier votre projet et configurer l'objet de service Tasks
- Effectuer des appels à l'API Tasks
Importer la bibliothèque cliente de Google
Les exemples présentés dans 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 répertoriés ci-dessous dans le dossier /assets à la racine de votre application Android. Vérifiez également si de nouvelles versions sont disponibles au fur et à mesure que ce document gagne en ancienneté.
Importez les fichiers JAR de la bibliothèque cliente des API Google et ses extensions Android (qui font tous 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:
Importez les dépendances (c'est-à-dire 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 dans Android
Depuis Android 2.0, le AccountManager gère les comptes que vous avez enregistrés dans votre environnement, c'est-à-dire ceux répertoriés sous Paramètres > Comptes et synchronisation. Plus précisément, elle gère le flux d'autorisation et peut générer les jetons d'autorisation nécessaires pour accéder aux données à l'aide d'API.
Afin de 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 aux tâches. Le AccountManager gère non seulement les comptes Google, mais également ceux d'autres fournisseurs. Par conséquent, vous devrez demander des comptes Google spécifiques à 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 propose également 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 le compte qu'il souhaite utiliser dans une boîte de dialogue semblable à celle-ci:
Vous pouvez créer une boîte de dialogue de ce type en utilisant le 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;
}
Le fait d'appeler showDialog(DIALOG_ACCOUNTS) affiche la boîte de dialogue du sélecteur de 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 de la méthode AccountManager.getAuthToken(), le gestionnaire de comptes AccountManager se charge de contacter le point de terminaison d'autorisation des API Google. Lorsque 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 Android propose une compatibilité expérimentale avec OAuth 2.0. Il vous suffit d'ajouter le préfixe oauth2: au champ d'application de l'API lorsque vous définissez AUTH_TOKEN_TYPE. Vous pouvez donc utiliser ce qui suit pour l'API Tasks:
String AUTH_TOKEN_TYPE = "oauth2:https://www.googleapis.com/auth/tasks";
Lorsque vous utilisez la valeur ci-dessus comme AUTH_TOKEN_TYPE, le problème 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 voulez accéder. Pour contourner ce problème, il existe des alias AUTH_TOKEN_TYPE spéciaux et lisibles pour l'API Tasks. Cela revient à utiliser le champ d'application OAuth 2.0. Par exemple, vous pouvez utiliser:
String AUTH_TOKEN_TYPE = "Manage your tasks";
Vous pouvez également utiliser l'alias AUTH_TOKEN_TYPE avec View your tasks (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.
Au cours de l'appel AccountManager.getAuthToken(), le gestionnaire 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 démarrée par le AccountManager, qui affiche une boîte de dialogue d'autorisation pour que l'utilisateur puisse autoriser ou refuser l'application à utiliser l'API Tasks sur son compte.
Si l'utilisateur refuse à votre application l'accès à l'API Tasks, une OperationCanceledException est générée lors de l'appel future.getResult(). Vous devez gérer cela correctement, par exemple en demandant à nouveau à choisir le compte ou en affichant un message avec un bouton pour 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 des API Google, car elle est obligatoire pour effectuer des appels d'API Tasks. Pour ce faire, procédez comme suit:
- Créer un projet ou en utiliser un existant
- Activez l'API Tasks sur votre projet en basculant le bouton de l'API Tasks sur ACTIVÉ.
- La clé d'API est disponible sous Accès à l'API > Accès simple à l'API > Clé API
La clé API est obligatoire, car elle identifie votre application. Elle permet donc à l'API de déduire le quota et d'utiliser les règles de quota définies pour votre projet. Vous devez spécifier la clé API sur votre objet de 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 une durée limitée. Vous devrez donc en obtenir un nouveau lorsqu'il arrivera à expiration. Il existe deux façons de procéder:
- Demandez un accessToken au AccountManager chaque fois que vous effectuez des demandes via l'API. Étant donné que le gestionnaire AccountManager met en cache le jeton, cette solution est acceptable.
- Continuez à utiliser votre accessToken jusqu'à ce que vous obteniez une erreur 403, puis demandez un nouveau jeton à AccountManager.
Manipuler des tâches à l'aide de l'API
À ce stade, vous devriez disposer d'un objet service de l'API Tasks entièrement configuré que vous pouvez utiliser pour interroger l'API conformément au guide du développeur de l'API Tasks, par exemple:
// Getting all the Task lists ListtaskLists = 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 au fichier manifeste de votre 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 à la bibliothèque cliente des API Google pour Java pour vous aider à faire vos premiers pas avec l'API Tasks et OAuth 2.0 sur Android. L'exemple est 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 un ListView.
Pour exécuter l'exemple, suivez instructions et n'hésitez pas à publier vos commentaires ou questions sur le Forum consacré à l'API Google Tasks.