Aviso: este documento foi descontinuado. Para mais 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 obter acesso ao Google Tarefas de um usuário e como você pode ter um objeto service da API Tasks pronto para uso no seu aplicativo Android.
Para que seu aplicativo Android use a API Tasks, são necessárias várias etapas:
- Selecione a Conta do Google do usuário
- Obtenha um token de acesso OAuth 2.0 do AccountManager para a API Task
- Identifique seu projeto e configure o objeto de serviço "Tarefas"
- Fazer chamadas para a API Tasks
Importação da biblioteca cliente do Google
Os exemplos que você encontrará neste documento usam a biblioteca de cliente de APIs do Google para Java. Adicione os seguintes jars ao app Android. Para isso, coloque os jars listados abaixo na pasta /assets na raiz do app Android. Verifique também novas versões à medida que o documento ficar mais antigo.
Importe os jars da biblioteca de cliente das APIs do Google e as respectivas extensões 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:
Importe dependências (todas parte 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 em seu ambiente, as 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.
Se quiser usar o AccountManager para receber contas e solicitar tokens de autorização, será necessário adicionar as seguintes permissões ao manifesto do app Android:
<uses-permission android:name="android.permission.GET_ACCOUNTS" /> <uses-permission android:name="android.permission.USE_CREDENTIALS" />
Use o AccountManager para acessar a Conta do Google que você quer acessar as tarefas. Além de gerenciar as Contas do Google, o AccountManager gerencia contas de outros fornecedores. Portanto, você precisará solicitar especificamente 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 em uma caixa de diálogo como 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;
}
Chamar showDialog(DIALOG_ACCOUNTS) exibirá a caixa de diálogo do seletor de conta.
Fluxo de autorização de APIs do Google no Android
Agora que o usuário escolheu uma conta, podemos pedir ao AccountManager para emitir um token de acesso OAuth 2.0 para a API Task. Para fazer isso, chame o método AccountManager.getAuthToken(). Durante a chamada AccountManager.getAuthToken(), o AccountManager faz o contato com o endpoint de autorização das APIs do Google. Quando o AccountManager recuperar o token de autorização, ele executará 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 ao OAuth 2.0. Basta usar oauth2: como prefixo do escopo da API que você quer acessar ao definir o AUTH_TOKEN_TYPE. Portanto, para a API Tasks, é possível 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 é exibida na caixa de diálogo de autorização como o nome do produto do Google que você quer acessar. Para contornar isso, existem aliases AUTH_TOKEN_TYPE especiais (legíveis por humanos) para a API Tasks. Eles são equivalentes ao uso do escopo OAuth 2.0. Por exemplo, é possível usar:
String AUTH_TOKEN_TYPE = "Manage your tasks";
Você também pode usar o alias AUTH_TOKEN_TYPE. Visualizar suas tarefas, que é equivalente à API Tasks somente leitura escopo: 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 foi autorizado, uma Activity é iniciada pelo AccountManager, que exibe uma caixa de diálogo de autorização ao usuário para que ele possa Permitir ou Negar seu aplicativo a usar 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 com cuidado, por exemplo, pedindo para escolher a conta novamente ou exibindo uma mensagem com um botão para autorizar o acesso novamente.
Como identificar seu aplicativo e configurar o objeto de serviço da API de tarefas
Agora que seu aplicativo tem autorização para acessar a API Tasks e que ele recebeu um token de acesso, você também precisa de uma chave de API, que você precisa obter de um projeto no Console de APIs do Google, já que ela é obrigatória para fazer chamadas da API Tasks. Para isso, siga estas etapas:
- Criar um projeto ou usar um existente
- Alterne a chave da API Tasks para ATIVADO 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 permite que a API deduza a cota e use as regras de cota definidas para seu projeto. Você precisa especificar a chave de API no seu objeto service do Tarefas:
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
}
Como o accessToken só é válido por um determinado período, você precisará receber um novo quando ele expirar. Há duas maneiras de lidar com isso:
- Solicite um accessToken ao AccountManager sempre que 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. Nesse momento, você solicita um novo token para o AccountManager.
Manipulação de tarefas por meio da API
Neste ponto, você tem 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 para acessar a Internet ao manifesto do app Android. Caso contrário, as solicitações acima para os endpoints da API Tasks vão falhar:
<uses-permission android:name="android.permission.INTERNET" />
Exemplo de aplicativo
Recentemente, adicionamos um novo exemplo à biblioteca de cliente de 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 exibir as tarefas da lista de tarefas padrão em uma ListView.
Siga estas instruções para executar o exemplo e fique à vontade para postar feedback ou perguntas no Fórum da API Google Tasks.