Avviso: questo documento è deprecato. Per informazioni sull'autorizzazione delle app per Android che utilizzano OAuth 2.0, consulta la documentazione sull'autorizzazione di Google Play Services.
Questo documento spiega come utilizzare l'API Tasks con OAuth 2.0 su Android. Descrive i meccanismi di autorizzazione per ottenere l'accesso a Google Tasks di un utente e come avere un oggetto service dell'API Tasks pronto per l'uso nella tua applicazione Android.
Affinché l'applicazione per Android possa utilizzare l'API Tasks, sono necessari diversi passaggi:
- Seleziona l'Account Google dell'utente
- Ottenere un token di accesso OAuth 2.0 da AccountManager per l'API Task
- Identifica il tuo progetto e configura l'oggetto del servizio Tasks
- Effettuare chiamate all'API Tasks
Importazione della libreria client di Google
I sample che troverai in questo documento utilizzano la libreria client delle API di Google per Java. Dovrai aggiungere i seguenti file JAR alla tua applicazione Android. Per farlo, posiziona i file JAR elencati di seguito nella cartella /assets nella directory principale della tua applicazione Android. Controlla anche se sono disponibili nuove versioni man mano che questo documento diventa meno recente.
Importa i file JAR della libreria client delle API di Google e le relative estensioni per Android (tutte incluse in 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
Importa il file jar specifico di Tasks:
Importa le dipendenze (tutte parte di 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
Account Google su Android
Da Android 2.0, AccountManager gestisce gli account che hai registrato nel tuo ambiente, quelli elencati in Impostazioni > Account e sincronizzazione. In particolare, gestisce il flusso di autorizzazione e può generare token di autorizzazione necessari per accedere ai dati utilizzando le API.
Per poter utilizzare AccountManager per recuperare gli account e richiedere token di autorizzazione, devi aggiungere le seguenti autorizzazioni nel file manifest dell'applicazione Android:
<uses-permission android:name="android.permission.GET_ACCOUNTS" /> <uses-permission android:name="android.permission.USE_CREDENTIALS" />
Puoi utilizzare AccountManager per ottenere l'Account Google per cui vuoi accedere a Tasks. AccountManager gestisce non solo gli Account Google, ma anche gli account di altri fornitori. Pertanto, dovrai chiedere specificamente gli Account Google utilizzando il codice riportato di seguito:
AccountManager accountManager = AccountManager.get(activity);
Account[] accounts = accountManager.getAccountsByType("com.google");In alternativa, la libreria client delle API di Google per Java è dotata di un GoogleAccountManager che gestisce solo gli Account Google:
GoogleAccountManager googleAccountManager = new GoogleAccountManager(activity); Account[] accounts = googleAccountManager.getAccounts();
Se sul dispositivo Android sono disponibili più Account Google, devi chiedere all'utente l'account che vuole utilizzare con una finestra di dialogo simile alla seguente:
Puoi creare una finestra di dialogo di questo tipo utilizzando il seguente codice switch/case nel metodo onCreateDialog della tua attività:
@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'istruzione showDialog(DIALOG_ACCOUNTS) mostra la finestra di dialogo per la scelta dell'account.
Flusso di autorizzazione delle API Google su Android
Ora che l'utente ha scelto un account, possiamo chiedere ad AccountManager di emettere un token di accesso OAuth 2.0 per l'API Task. Per farlo, chiama il metodo AccountManager.getAuthToken(). Durante la chiamata AccountManager.getAuthToken(), AccountManager si occuperà di contattare l'endpoint di autorizzazione delle API di Google. Quando AccountManager ha recuperato il token di autorizzazione, eseguirà AccountManagerCallback che hai definito nella chiamata al metodo:
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);
Come forse già sai, AccountManager di Android supporta in via sperimentale OAuth 2.0. Devi solo anteporre l'ambito dell'API a cui vuoi accedere con oauth2: quando imposti AUTH_TOKEN_TYPE. Pertanto, per l'API Tasks puoi utilizzare:
String AUTH_TOKEN_TYPE = "oauth2:https://www.googleapis.com/auth/tasks";
Il problema che si verifica quando si utilizza il valore riportato sopra come AUTH_TOKEN_TYPE è che la stringa oauth2:https://www.googleapis.com/auth/tasks verrà visualizzata nella finestra di dialogo di autorizzazione come nome del prodotto Google a cui vuoi accedere. Per aggirare il problema, esistono alias AUTH_TOKEN_TYPE speciali leggibili da persone per l'API Tasks. Sono equivalenti all'utilizzo dell'ambito OAuth 2.0. Ad esempio, puoi utilizzare:
String AUTH_TOKEN_TYPE = "Manage your tasks";
Puoi anche utilizzare l'alias AUTH_TOKEN_TYPE Visualizza le tue attività, che è equivalente all'ambito di sola lettura dell'API Tasks: oauth2:https://www.googleapis.com/auth/tasks.readonly.
Durante la chiamata AccountManager.getAuthToken(), AccountManager controllerà se la tua applicazione è stata autorizzata ad accedere all'API Tasks. Se la tua applicazione non è ancora stata autorizzata, AccountManager avvia un'attività che mostra all'utente una finestra di dialogo di autorizzazione per consentirgli di consentire o negare all'applicazione di utilizzare l'API Tasks sul suo account.
Se l'utente nega alla tua applicazione l'accesso all'API Tasks, verrà lanciata un'eccezione OperationCanceledException durante la chiamata future.getResult(). Devi gestire la situazione in modo elegante, ad esempio chiedendo di scegliere di nuovo l'account o mostrando un messaggio con un pulsante per autorizzare di nuovo l'accesso.
Identificazione dell'applicazione e configurazione dell'oggetto servizio dell'API Tasks
Ora che la tua applicazione dispone dell'autorizzazione per accedere all'API Tasks e che le è stato assegnato un token di accesso, devi anche disporre di una chiave API che devi recuperare da un progetto nella console API di Google, in quanto è obbligatoria per effettuare chiamate all'API Tasks. Per farlo, segui questi passaggi:
- Crea un progetto o utilizzane uno esistente
- Abilita l'API Tasks nel tuo progetto impostando l'opzione su ON.
- La chiave API è disponibile in Accesso API > Accesso API semplice > Chiave API
La chiave API è obbligatoria perché identifica la tua applicazione e consente quindi all'API di detrarre la quota e utilizzare le regole di quota definite per il progetto. Devi specificare la chiave API nell'oggetto service di 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
}L'attributo accessToken è valido solo per un determinato periodo di tempo, quindi dovrai ottenerne uno nuovo alla scadenza. Esistono due modi per gestire questo problema:
- Richiedi un accessToken ad AccountManager ogni volta che effettui richieste tramite l'API. Poiché AccountManager memorizza nella cache il token, questa soluzione è accettabile.
- Continua a utilizzare l'attributo accessToken finché non ricevi un errore 403, a quel punto richiedi un nuovo token ad AccountManager.
Manipolare le attività tramite l'API
A questo punto dovresti avere un oggetto service dell'API Tasks completamente configurato che puoi utilizzare per eseguire query sull'API come indicato nella Guida per gli sviluppatori dell'API Tasks, ad esempio:
// 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();
Non dimenticare di aggiungere l'autorizzazione per accedere a internet al file manifest dell'applicazione Android, altrimenti le richieste precedenti agli endpoint dell'API Tasks non andranno a buon fine:
<uses-permission android:name="android.permission.INTERNET" />
Applicazione di esempio
Di recente abbiamo aggiunto un nuovo esempio al repository di esempi della libreria client delle API di Google per Java per aiutarti a iniziare a utilizzare l'API Tasks e OAuth 2.0 su Android. L'esempio è un'applicazione Android semplice, ma completamente funzionante, che richiede l'autorizzazione per utilizzare l'API Tasks e visualizzare le attività dell'elenco di attività predefinito in un ListView.
Segui queste istruzioni per eseguire il sample e non esitare a pubblicare il tuo feedback o le tue domande nel forum dell'API Google Tasks.