本頁面由 Cloud Translation API 翻譯而成。

在 Android 上使用 Tasks API

警告：這份文件已淘汰。如要瞭解如何使用 OAuth 2.0 授權 Android 應用程式，請參閱 Android Play 服務授權說明文件。

本文說明如何在 Android 上使用 Tasks API 搭配 OAuth 2.0。說明取得使用者 Google Tasks 存取權的授權機制，以及如何在 Android 應用程式中使用 Tasks API service 物件。

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

選取使用者的 Google 帳戶
從 Task API 的 AccountManager 取得 OAuth 2.0 存取權憑證
找出專案並設定 Tasks service Object
呼叫 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-services-tasks-v1-1.1.0-beta.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 環境中註冊的帳戶

如要使用 AccountManager 取得帳戶及要求授權權杖，您必須在 Android 應用程式資訊清單中新增下列權限：

<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 用戶端程式庫提供 GoogleAccountManager，只處理 Google 帳戶：

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 為 Task API 發出 OAuth 2.0 存取權杖。方法是呼叫 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。如果應用程式尚未獲得授權，AccountManager 會啟動Activity，並向使用者顯示授權對話方塊，讓使用者允許或拒絕應用程式在其帳戶上使用 Tasks API。

授權對話方塊

如果使用者拒絕應用程式存取 Tasks API，系統會在 future.getResult() 呼叫期間擲回 OperationCanceledException。您應妥善處理這類情況，例如要求使用者再次選擇帳戶，或顯示訊息並提供按鈕，讓使用者再次授予存取權。

找出應用程式並設定 Tasks API 服務物件

您的應用程式現在已獲得存取 Tasks API 的授權，並且已獲得存取權，您還需要一個 API 金鑰，您必須在 Google API 控制台中的專案中取得這項金鑰，因為這項金鑰是發出 Tasks API 呼叫的必要條件。步驟如下：

建立專案或使用現有專案
將 Tasks API 切換鈕切換為「ON」，即可在專案中啟用 Tasks API。
API 金鑰位於「API 存取權」>「簡易 API 存取權」>「API 金鑰」

從 API 控制台取得 API 金鑰

API 金鑰是必填項目，可用於識別應用程式，讓 API 扣除配額並使用專案定義的配額規則。您需要在 Tasks service 物件上指定 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 會快取權杖，因此這個解決方案是可行的。
請持續使用 accessToken，直到出現 403 錯誤為止，然後向 AccountManager 要求新的權杖。

透過 API 操作工作

此時，您應該已完成 Tasks API service 物件的完整設定，可根據 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" />

應用程式範例

我們最近在 Google API 用戶端程式庫 (適用於 Java) 範例存放區中新增了範例，協助您開始在 Android 上使用 Tasks API 和 OAuth 2.0。這個範例是簡單但完全可用的 Android 應用程式，會要求授權使用 Tasks API，並在 ListView 中顯示預設工作清單的工作。

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

請按照操作說明執行範例，並隨時在 Google Tasks API 論壇發布您的意見回饋或問題。