Avviso: questo documento è stato ritirato. Per informazioni sull'autorizzazione di app per Android tramite OAuth 2.0, consulta la documentazione sull'autorizzazione di Android 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 alle attività di Google Tasks di un utente e come sia possibile avere un oggetto servizio API Tasks pronto per l'uso nella tua applicazione Android.
Affinché la tua applicazione Android possa utilizzare l'API Tasks, sono necessari diversi passaggi, è necessario:
- Seleziona l'Account Google dell'utente
- Ottenere un token di accesso OAuth 2.0 da AccountManager per l'API Tasks
- Identifica il progetto e configura l'oggetto di servizio Tasks.
- Effettuare chiamate all'API Tasks
Importazione della libreria client di Google
Gli esempi che troverai in questo documento utilizzano la libreria client delle API di Google per Java. Dovrai aggiungere i jar seguenti all'applicazione Android. A tale scopo, inserisci i jar elencati di seguito nella cartella /assets nella directory principale della tua applicazione per Android. Controlla anche la presenza di nuove versioni man mano che il documento diventa precedente.
Importa i file jar della libreria client delle API di Google e le relative estensioni Android (tutti parte di 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 jar specifico di Tasks:
Importa le dipendenze (che fanno 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 in Android
A partire da Android 2.0, l'AccountManager gestisce gli account che hai registrato nel tuo ambiente, ovvero quelli elencati in Impostazioni > Account e sincronizzazione. In particolare, gestisce il flusso di autorizzazione e può generare i token di autorizzazione necessari per accedere ai dati utilizzando le API.
Per poter utilizzare AccountManager per recuperare gli account e richiedere i 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 il quale vuoi accedere alle attività. L'AccountManager non gestisce solo gli Account Google, ma anche account di altri fornitori. Pertanto, dovrai richiedere specificatamente gli Account Google utilizzando il codice seguente:
AccountManager accountManager = AccountManager.get(activity); Account[] accounts = accountManager.getAccountsByType("com.google");
In alternativa, la libreria client delle API di Google per Java include 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, dovresti richiedere 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 di switch/caso nel metodo onCreateDialog dell'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; }
Chiamando showDialog(DIALOG_ACCOUNTS) verrà visualizzata la finestra di dialogo del selettore account.
Flusso di autorizzazione delle API di Google su Android
Ora che l'utente ha scelto un account, possiamo chiedere all'AccountManager di emettere un token di accesso OAuth 2.0 per l'API Tasks. A questo scopo, richiama il metodo AccountManager.getAuthToken(). Durante la chiamata a AccountManager.getAuthToken(), AccountManager si occuperà di contattare l'endpoint di autorizzazione delle API di Google. Dopo aver recuperato il token di autorizzazione, AccountManager esegue l'elemento 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 Probabilmente già saprai, l'AccountManager di Android supporta in modo sperimentale OAuth 2.0. Quando imposti AUTH_TOKEN_TYPE, devi solo aggiungere oauth2: all'ambito dell'API a cui vuoi accedere. Quindi per l'API Tasks puoi utilizzare:
String AUTH_TOKEN_TYPE = "oauth2:https://www.googleapis.com/auth/tasks";
Il problema quando utilizzi il valore precedente come AUTH_TOKEN_TYPE è che la stringa oauth2:https://www.googleapis.com/auth/tasks verrà visualizzata nella finestra di dialogo di autorizzazione come il nome del prodotto Google a cui vuoi accedere. Per ovviare a questo problema, per l'API Tasks esistono degli alias AUTH_TOKEN_TYPE speciali, in formato leggibile. Equivale a utilizzare l'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 attività, che equivale all'ambito di sola lettura dell'API Tasks: oauth2:https://www.googleapis.com/auth/tasks.readonly.
Durante la chiamata a AccountManager.getAuthToken(), AccountManager controllerà se la tua applicazione è stata autorizzata ad accedere all'API Tasks. Se la tua applicazione non è ancora stata autorizzata, da AccountManager viene avviata una attività che mostra una finestra di dialogo di autorizzazione per l'utente, in modo che possa consentire o negare l'applicazione a utilizzare l'API Tasks sul suo account.
Se l'utente nega l'accesso dell'applicazione all'API Tasks, verrà generata un'OperationCanceledException durante la chiamata future.getResult(). Dovresti gestire questa operazione più agevolmente, 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 del servizio API Tasks
Ora che la tua applicazione ha l'autorizzazione per accedere all'API Tasks e che gli è stato fornito un token di accesso, ti serve anche una chiave API che devi ottenere da un progetto nella Console API di Google poiché è obbligatoria per effettuare chiamate all'API Tasks. A tale scopo, procedi nel seguente modo:
- Crea un progetto o utilizzane uno esistente
- Abilita l'API Tasks sul tuo progetto attivando l'opzione API Tasks
- La chiave API è disponibile in Accesso API > Accesso semplice all'API > Chiave API
La chiave API è obbligatoria in quanto identifica l'applicazione e consente quindi all'API di dedurre la quota e di utilizzare le regole di quota definite per il tuo progetto. Devi specificare la chiave API nell'oggetto 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 }
accessToken è valido solo per un determinato periodo di tempo, quindi dovrai ottenerne uno nuovo alla scadenza. Esistono due modi per gestire questa situazione:
- Richiedi un accessToken a AccountManager ogni volta che effettui richieste tramite l'API. Poiché AccountManager memorizza nella cache il token, questa soluzione è accettabile.
- Continua a utilizzare il tuo accessToken fino a quando non ricevi l'errore 403. A quel punto, richiedi un nuovo token a AccountManager.
Manipolazione delle attività tramite l'API
A questo punto dovresti avere un oggetto servizio 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 l'accesso a Internet al manifest della tua applicazione Android. In caso contrario, 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 alla libreria client delle API di Google per il repository Java di esempio 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 una visualizzazione Lista.
Segui queste instructions per eseguire l'esempio e non esitare a pubblicare il tuo feedback o le tue domande nel forum dell'API di Google Tasks.