Avertissement: Ce document est obsolète. Pour en savoir plus sur l'autorisation des applications Android avec OAuth 2.0, consultez le 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 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
- 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 devrez ajouter les fichiers JAR suivants à votre application Android. Pour ce faire, placez ceux listés ci-dessous dans le dossier /assets, à la racine de votre application Android. Recherchez également de nouvelles versions au fur et à mesure de l'ancienneté de ce document.
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 aux tâches:
Importez les dépendances (qui font partie de 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, le AccountManager gère les comptes que vous avez enregistrés dans votre environnement, c'est-à-dire ceux qui sont répertoriés sous Settings > Comptes et la synchronisation. Plus précisément, il gère le flux d'autorisation et peut générer les jetons d'autorisation requis pour accéder aux données à l'aide d'API.
Pour pouvoir utiliser AccountManager afin d'obtenir des comptes et de 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 voulez accéder à Tasks. Le AccountManager gère non seulement les comptes Google, mais également les comptes d'autres fournisseurs. Par conséquent, vous devez demander spécifiquement des comptes Google en utilisant le code ci-dessous:
AccountManager accountManager = AccountManager.get(activity);
Account[] accounts = accountManager.getAccountsByType("com.google");
Par ailleurs, la bibliothèque cliente des API Google pour Java est 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 inviter l'utilisateur à indiquer le compte qu'il souhaite utiliser avec une boîte de dialogue semblable à celle-ci:
Vous pouvez créer une boîte de dialogue de ce type en utilisant le commutateur/le code de cas 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;
}
Si vous appelez showDialog(DIALOG_ACCOUNTS), la boîte de dialogue du sélecteur de compte s'affiche.
Flux d'autorisation des API Google sur Android
Maintenant que l'utilisateur a choisi un compte, nous pouvons demander au 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 chargera de contacter le point de terminaison d'autorisation des API Google. Une fois que AccountManager a récupéré le jeton d'autorisation, il exécute le rappel 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 offre une compatibilité expérimentale avec OAuth 2.0. Il vous suffit d'ajouter oauth2: au champ d'application de l'API à laquelle vous souhaitez accéder lorsque vous définissez AUTH_TOKEN_TYPE. Ainsi, pour l'API Tasks, vous pouvez utiliser:
String AUTH_TOKEN_TYPE = "oauth2:https://www.googleapis.com/auth/tasks";
Le problème lié à l'utilisation de la valeur ci-dessus comme AUTH_TOKEN_TYPE est que la chaîne oauth2:https://www.googleapis.com/auth/tasks sera affichée 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, il existe des alias AUTH_TOKEN_TYPE spéciaux et lisibles pour l'API Tasks. Ils correspondent à l'utilisation du 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. Afficher vos tâches, ce qui équivaut à l'API Tasks en lecture seule champ d'application: 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 pour que l'utilisateur puisse autoriser ou refuser votre application à utiliser l'API Tasks sur son compte.
Si l'utilisateur refuse l'accès de votre application à l'API Tasks, une exception OperationCanceledException sera générée lors de l'appel future.getResult(). Pour éviter cela, vous devez, par exemple, demander à sélectionner de nouveau le compte ou afficher 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'un jeton d'accès lui a été attribué, vous avez 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 à l'API Tasks. Pour cela, procédez comme suit:
- Créer un projet ou utiliser un projet existant
- Activez l'API Tasks sur votre projet en basculant le bouton de l'API Tasks sur ACTIVÉ.
- La clé API se trouve sous Accès à l'API > Accès simple à l'API > Clé API
La clé API est obligatoire, car elle identifie votre application et 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 dans votre 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 une certaine période. Vous devrez donc en obtenir un nouveau lorsqu'il arrivera à expiration. Il existe deux façons de gérer cela:
- Demandez un accessToken au AccountManager à chaque fois que vous effectuez des demandes via l'API. Étant donné que l'élément AccountManager met en cache le jeton, cette solution est acceptable.
- Continuez à utiliser votre accessToken jusqu'à ce qu'une erreur 403 s'affiche, auquel cas vous demandez un nouveau jeton au AccountManager.
Manipuler des tâches via 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 une ListView.
Suivez ces instructions pour exécuter l'exemple, et n'hésitez pas à nous faire part de vos commentaires ou questions sur le forum consacré à l'API Google Tasks.