Aviso: este documento está obsoleto. Para ver informações sobre como autorizar apps Android usando o OAuth 2.0, consulte a documentação de autorização do Android Play Services.
Este documento explica como usar a API Tasks com o OAuth 2.0 no Android. Ele descreve os mecanismos de autorização para ter acesso ao Google Tarefas de um usuário e como você pode ter um objeto service pronto para uso da API Tasks em seu aplicativo Android.
Para que o aplicativo Android use a API Tasks várias etapas são necessárias, você precisa:
- Selecionar a Conta do Google do usuário
- Receba um token de acesso do OAuth 2.0 do AccountManager para a API Task
- Identifique seu projeto e configure o objeto de serviço do Tasks
- Fazer chamadas para a API Tasks
Importação da biblioteca de cliente do Google
Os exemplos que se encontram neste documento usam a biblioteca cliente de APIs do Google para Java. Adicione estes jars ao app Android. Para isso, coloque os jars listados abaixo na pasta /assets na raiz do app Android. Verifique também se há novas versões à medida que este documento for evoluindo.
Importe os jars da biblioteca de cliente das APIs do Google e as extensões do Android (todas parte 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
Importe o jar específico do Tasks:
Importar dependências (todas as partes 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
Contas do Google no Android
Desde o Android 2.0, o AccountManager gerencia as contas que você registrou no ambiente, aquelas que estão listadas em Configurações > Contas e sincronização. Especificamente, ele lida com o fluxo de autorização e pode gerar tokens de autorização necessários para acessar dados usando APIs.
Para usar o AccountManager para receber contas e solicitar tokens de autorização, adicione as seguintes permissões ao manifesto do aplicativo Android:
<uses-permission android:name="android.permission.GET_ACCOUNTS" /> <uses-permission android:name="android.permission.USE_CREDENTIALS" />
Use o AccountManager para criar a Conta do Google com a qual você quer acessar as Tarefas. O AccountManager gerencia Contas do Google e de outros fornecedores. Portanto, você precisará solicitar especificamente as Contas do Google usando o código abaixo:
AccountManager accountManager = AccountManager.get(activity);
Account[] accounts = accountManager.getAccountsByType("com.google");
Como alternativa, a biblioteca cliente de APIs do Google para Java vem com um GoogleAccountManager que lida apenas com contas do Google:
GoogleAccountManager googleAccountManager = new GoogleAccountManager(activity); Account[] accounts = googleAccountManager.getAccounts();
Se mais de uma Conta do Google estiver disponível no dispositivo Android, solicite ao usuário a conta que ele quer usar com uma caixa de diálogo parecida com esta:
Você pode criar essa caixa de diálogo usando o seguinte código de chave/caso no método onCreateDialog da sua atividade:
@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;
}
A caixa de diálogo do seletor de conta será exibida ao chamar showDialog(DIALOG_ACCOUNTS).
Fluxo de autorização das APIs do Google no Android
Agora que o usuário escolheu uma conta, podemos pedir ao AccountManager para emitir um token de acesso do OAuth 2.0 para a API Task. Para isso, chame o método AccountManager.getAuthToken(). Durante AccountManager.getAuthToken(), chame AccountManager para entrar em contato com o ponto de extremidade de autorização das APIs do Google. Quando o AccountManager recupera o token de autorização, ele executa o AccountManagerCallback definido na chamada do método:
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);
Como você já deve saber, o AccountManager do Android oferece suporte experimental para OAuth 2.0. Basta prefixar o escopo da API que quer acessar com oauth2: ao definir o AUTH_TOKEN_TYPE. Portanto, para a API Tasks, você pode usar:
String AUTH_TOKEN_TYPE = "oauth2:https://www.googleapis.com/auth/tasks";
O problema ao usar o valor acima como AUTH_TOKEN_TYPE é que a string oauth2:https://www.googleapis.com/auth/tasks será exibida na caixa de diálogo de autorização como o nome do produto do Google que você quer acessar. Para contornar esse problema, existem aliases AUTH_TOKEN_TYPE especiais legíveis por humanos para a API Tasks. Eles são equivalentes a usar o escopo do OAuth 2.0. Por exemplo, você pode usar:
String AUTH_TOKEN_TYPE = "Manage your tasks";
Também é possível usar o alias AUTH_TOKEN_TYPE View your tasks, que é equivalente ao escopo somente leitura da API Tasks: oauth2:https://www.googleapis.com/auth/tasks.readonly.
Durante a chamada AccountManager.getAuthToken(), o AccountManager verifica se o aplicativo foi autorizado a acessar a API Tasks. Se seu aplicativo ainda não tiver sido autorizado, uma Activity será iniciada pelo AccountManager, que exibe uma caixa de diálogo de autorização ao usuário para que ele possa Permitir ou Negar que seu aplicativo use a API Tasks na conta dele.
Se o usuário negar o acesso do aplicativo à API Tasks, uma OperationCanceledException será gerada durante a chamada future.getResult(). Você deve lidar com isso normalmente, por exemplo, pedindo para escolher a conta novamente ou exibindo uma mensagem com um botão para autorizar o acesso novamente.
Identificar seu aplicativo e configurar o objeto de serviço da API Tasks
Agora que seu aplicativo tem autorização para acessar a API Tasks e recebeu um token de acesso, você também precisa de uma chave de API, que será obtida de um projeto no Console de APIs do Google, já que ela é obrigatória para fazer chamadas da API Tasks. Para fazer isso, siga estas etapas:
- Criar um projeto ou usar um existente
- Mude a chave da API Tasks para ATIVADA para ativar a API Tasks no projeto.
- A Chave de API pode ser encontrada em Acesso à API > Acesso simples à API > Chave de API
A chave de API é obrigatória, porque identifica seu aplicativo e, portanto, permite que a API deduza a cota e use as regras de cota definidas para seu projeto. É necessário especificar a chave de API no objeto service do 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
}
O accessToken é válido somente por um determinado período, portanto, você precisará adquirir um novo quando ele expirar. Há duas maneiras de lidar com isso:
- Solicite um accessToken ao AccountManager sempre que você fizer solicitações pela API. Como o AccountManager armazena o token em cache, essa solução é aceitável.
- Continue usando seu accessToken até receber o erro 403. Quando você solicitar um novo token ao AccountManager.
Manipulação de tarefas por meio da API
Neste ponto, você já deve ter um objeto service da API Tasks totalmente configurado, que pode ser usado para consultar a API de acordo com o Guia para desenvolvedores da API Tasks, por exemplo:
// 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ão se esqueça de adicionar a permissão de acesso à Internet ao manifesto do aplicativo Android, caso contrário, as solicitações acima para os endpoints da API Tasks falharão:
<uses-permission android:name="android.permission.INTERNET" />
Exemplo de aplicativo
Recentemente, adicionamos uma nova amostra ao repositório de exemplos da biblioteca de cliente das APIs do Google para Java para ajudar você a começar a usar a API Tasks e o OAuth 2.0 no Android. O exemplo é um aplicativo Android simples, mas totalmente funcional, que solicita autorização para usar a API Tasks e exibe as tarefas da lista de tarefas padrão em um ListView.
Siga estas instructions para executar o exemplo e fique à vontade para enviar feedback ou dúvidas no Fórum da API Google Tasks.