Usar a API Tasks no Android

Aviso: este documento foi descontinuado. Para informações sobre como autorizar apps Android que usam 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 às Tarefas Google 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, várias etapas são necessárias:

  1. Selecione a Conta do Google do usuário
  2. Receber um token de acesso do OAuth 2.0 do AccountManager para a API Task
  3. Identificar seu projeto e configurar o objeto de serviço das tarefas
  4. Fazer chamadas para a API Tasks

Como importar a biblioteca de cliente do Google

Os exemplos neste documento usam a biblioteca de cliente de APIs do Google para Java. Você vai precisar adicionar os frascos abaixo ao seu aplicativo Android. Para isso, coloque os frascos listados abaixo na pasta /assets na raiz do seu aplicativo Android. Verifique também se há novas versões à medida que este documento fica mais antigo.

Importe os jars da biblioteca de cliente das APIs do Google e as extensões do Android (todos fazem parte do 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 das tarefas:

Importar dependências (todas fazem 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 no seu ambiente, aquelas listadas em Configurações > Contas e sincronização. Especificamente, ele processa o fluxo de autorização e pode gerar tokens de autorização necessários para acessar dados usando APIs.

Contas registradas no seu ambiente Android
Contas registradas no seu ambiente Android

Para usar o AccountManager e receber contas e solicitar tokens de autorização, adicione 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 em que você quer acessar as Tarefas. O AccountManager não gerencia apenas contas do Google, mas também contas de outros fornecedores. Portanto, você precisa 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 de 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, peça ao usuário para escolher a que ele quer usar com uma caixa de diálogo como esta:

Caixa de diálogo &quot;Escolher uma conta&quot;
Caixa de diálogo "Escolher uma conta"

É possível criar essa caixa de diálogo usando o seguinte código de seleção/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) vai mostrar a caixa de diálogo de seleção de contas.

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 OAuth 2.0 para a API Task. Isso é feito chamando o método AccountManager.getAuthToken(). Durante a chamada AccountManager.getAuthToken(), o AccountManager vai entrar em contato com o endpoint de autorização das APIs do Google. Quando o AccountManager recuperar o token de autorização, ele vai executar o AccountManagerCallback que você definiu na chamada de 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 tem suporte experimental para o OAuth 2.0. Basta prefixar o escopo da API que você quer acessar com oauth2: ao definir AUTH_TOKEN_TYPE. 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 alias especiais AUTH_TOKEN_TYPE legíveis por humanos para a API Tasks. Eles são equivalentes ao uso do 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 de leitura da API Tasks: oauth2:https://www.googleapis.com/auth/tasks.readonly.

Durante a chamada AccountManager.getAuthToken(), o AccountManager verifica se o app foi autorizado a acessar a API Tasks. Se o app ainda não tiver sido autorizado, uma atividade será iniciada pelo AccountManager, que mostra uma caixa de diálogo de autorização para que o usuário possa permitir ou negar o uso da API Tasks no app.

Diálogo de autorização
Diálogo de autorização

Se o usuário negar o acesso do seu aplicativo à API Tasks, uma OperationCanceledException será gerada durante a chamada future.getResult(). Você precisa lidar com isso de maneira adequada, por exemplo, pedindo para escolher a conta novamente ou mostrando uma mensagem com um botão para autorizar o acesso novamente.

Como 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 precisa ser obtida de um projeto no Console de APIs do Google, porque ela é obrigatória para fazer chamadas da API Tasks. Para isso, siga estas etapas:

  1. Criar um projeto ou usar um que já existe
  2. Ative a API Tasks no seu projeto mudando a chave para ATIVADO.
  3. A chave de API pode ser encontrada em Acesso à API > Acesso simples à API > Chave de API.

Como acessar a chave de API no Console de APIs
Como acessar a chave de API no Console de APIs

A chave de API é obrigatória, porque identifica seu aplicativo e permite que a API deduza a cota e use as regras definidas para seu projeto. É necessário especificar a chave de API no objeto service das 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
}

O accessToken é válido apenas por um determinado período. Portanto, você precisará gerar um novo quando ele expirar. Há duas maneiras de fazer isso:

  • Solicite um accessToken ao AccountManager sempre que fizer solicitações pela API. Como o AccountManager armazena em cache o token, essa solução é aceitável.
  • Continue usando o accessToken até receber um erro 403, momento em que você solicita um novo token ao AccountManager.

Como manipular tarefas pela API

Neste ponto, você deve ter um objeto de serviço da API Tasks totalmente configurado, que pode ser usado para consultar a API conforme o guia para desenvolvedores da API Tasks, por exemplo:

// Getting all the Task lists
List taskLists = 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 aplicativo 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 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 padrão da lista de tarefas em uma ListView.

Mostrar as tarefas na lista padrão em um ListView
Mostrar as tarefas na lista de tarefas padrão em um ListView

Siga estas instruções para executar o exemplo e não hesite em postar seu feedback ou perguntas no fórum da API Google Tasks.