在 Android 上使用 Tasks API

警告:這份文件已不適用。如要進一步瞭解如何使用 OAuth 2.0 授權 Android 應用程式,請參閱 Android Play 服務授權說明文件

本文說明如何在 Android 裝置上搭配 OAuth 2.0 使用 Tasks API。內容說明瞭取得使用者 Google Tasks 存取權的授權機制,以及如何準備好在 Android 應用程式中使用 Tasks API 服務物件。

如要讓 Android 應用程式使用 Tasks API,您必須完成以下幾個步驟:

  1. 選取使用者的 Google 帳戶
  2. 透過 AccountManager 取得 Task API 的 OAuth 2.0 存取權杖
  3. 找出專案並設定工作服務物件
  4. 呼叫 Tasks API

匯入 Google 用戶端程式庫

本文件提供的範例使用的是 Java 適用的 Google API 用戶端程式庫。您必須將下列 jar 新增至 Android 應用程式,並將下列 jar 移至您 Android 應用程式根目錄的 /assets 資料夾中。此外,也請在舊版文件中檢查新版本。

匯入 Google API 用戶端程式庫 jar 及其 Android 擴充功能 (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

匯入 Tasks 專屬的 jar:

匯入依附元件 (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

在 Android 中使用 Google 帳戶

從 Android 2.0 開始,AccountManager 會管理您已在環境中註冊的帳戶 (列在「設定」>「帳戶與同步處理」下方)。具體來說,它會處理授權流程,並產生透過 API 存取資料所需的授權權杖。

在 Android 環境中註冊的帳戶
在 Android 環境中註冊的帳戶

您必須在 Android 應用程式資訊清單中新增以下權限,才能使用 AccountManager 取得帳戶及要求授權權杖:

<uses-permission android:name="android.permission.GET_ACCOUNTS" />
<uses-permission android:name="android.permission.USE_CREDENTIALS" />

您可以使用 AccountManager 取得要存取 Tasks 的 Google 帳戶。AccountManager 不僅可以管理 Google 帳戶,也能管理其他供應商的帳戶。因此,您必須使用下方代碼特別申請 Google 帳戶:

AccountManager accountManager = AccountManager.get(activity);
Account[] accounts = accountManager.getAccountsByType("com.google");

或者,Java 適用的 Google API 用戶端程式庫隨附只處理 Google 帳戶的 GoogleAccountManager

GoogleAccountManager googleAccountManager = new GoogleAccountManager(activity);
Account[] accounts = googleAccountManager.getAccounts();

如果 Android 裝置上有多個 Google 帳戶,您應該要提示使用者使用要使用的帳戶,如下所示:

選擇帳戶對話框
選擇帳戶對話框

您可以在活動的 onCreateDialog 方法中使用以下開關/案例程式碼,建構這類對話方塊:

@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;
}

呼叫 showDialog(DIALOG_ACCOUNTS),系統就會顯示帳戶選擇器對話方塊。

Android 上的 Google API 授權流程

使用者選擇帳戶後,我們可以要求 AccountManager 核發 OAuth 2.0 存取權杖以供 Task API 使用。做法是呼叫 AccountManager.getAuthToken() 方法。在 AccountManager.getAuthToken() 呼叫期間,AccountManager 會負責聯絡 Google API 授權端點。AccountManager 擷取到授權權杖後,就會執行您在方法呼叫中定義的 AccountManagerCallback

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);

可能已經知道 Android AccountManager 提供 OAuth 2.0 的實驗性支援。只要在設定 AUTH_TOKEN_TYPE 時,在要存取的 API 範圍前面加上 oauth2:。如果是 Tasks API,你可以使用:

String AUTH_TOKEN_TYPE = "oauth2:https://www.googleapis.com/auth/tasks";

使用上述值做為 AUTH_TOKEN_TYPE 時,問題是,在授權對話方塊中將 oauth2:https://www.googleapis.com/auth/tasks 字串顯示為要存取的 Google 產品名稱。為解決這個問題,請特別採用容易理解的 Tasks API 別名:AUTH_TOKEN_TYPE 別名。這相當於使用 OAuth 2.0 範圍。舉例來說,您可以使用:

String AUTH_TOKEN_TYPE = "Manage your tasks";

您也可以使用 AUTH_TOKEN_TYPE 別名「查看工作」,這相當於 Tasks API 唯讀範圍:oauth2:https://www.googleapis.com/auth/tasks.readonly

AccountManager.getAuthToken() 呼叫期間,AccountManager 會檢查您的應用程式是否已獲授權,可以存取 Tasks API。如果您的應用程式尚未取得 Activity 授權,由 AccountManager 啟動。該頁面會顯示授權對話方塊,讓使用者能夠「允許」或「拒絕」您的應用程式透過自己的帳戶使用 Tasks API。

授權對話方塊
授權對話方塊

如果使用者拒絕您的應用程式存取 Tasks API,系統會在 future.getResult() 呼叫期間擲回 OperationCanceledException。但請謹慎處理這種情況,例如要求重新選擇帳戶,或顯示訊息以再次提供授權按鈕的按鈕。

識別應用程式並設定 Tasks API 服務物件

您的應用程式已獲得存取 Tasks API 的授權,且已取得存取權杖。您還需要在 Google API 控制台中從專案取得 API 金鑰,因為必須進行 Tasks API 呼叫。步驟如下:

  1. 建立專案或使用現有專案
  2. 將 Tasks API 切換為「開啟」,以便在專案中啟用 Tasks API
  3. 如要查看 API 金鑰,請依序點選 [API 存取權] > [簡易 API 存取權] > [API 金鑰]

從 API 控制台取得 API 金鑰
從 API 控制台取得 API 金鑰

由於 API 金鑰可識別您的應用程式,因此必須強制 API 使用您專案定義的配額限制。您必須在 Tasks 服務物件中指定 API 金鑰

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 僅在特定時間內有效,屆時您必須取得新的存取權杖。有 2 種方式可以處理這個問題:

  • 每次透過 API 提出要求時,都會向 AccountManager 請求 accessToken。由於 AccountManager 會快取這個解決方案的權杖,因此方法是可接受的。
  • 請在收到 403 錯誤時要求 AccountManager 提供新的權杖,否則請繼續使用 accessToken

透過 API 操控工作

此時,您應該已經有完整的 Tasks API 服務物件,可以依據 Tasks API 開發人員指南查詢 API,例如:

// 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();

別忘了在 Android 應用程式資訊清單中新增存取網際網路的權限,否則上述傳送至 Tasks API 端點的要求會失敗:

<uses-permission android:name="android.permission.INTERNET" />

應用程式範例

我們最近為 Java 適用的 Google API 用戶端程式庫範例存放區新增了範例,協助您開始在 Android 上使用 Tasks API 和 OAuth 2.0。此範例是簡單又能正常運作的 Android 應用程式,可要求使用 Tasks API 並在 ListView 中顯示預設工作清單的工作。

在 ListView 的預設工作清單中顯示工作
在 ListView 的預設工作清單中顯示工作

請按照這些instructions執行範例,歡迎隨時前往 Google Tasks API 論壇張貼意見或問題。