ใช้ Tasks API ใน Android

คำเตือน: เอกสารนี้เลิกใช้งานแล้ว ดูข้อมูลเกี่ยวกับการให้สิทธิ์แอป Android โดยใช้ OAuth 2.0 ได้ที่เอกสารประกอบเกี่ยวกับการให้สิทธิ์บริการ Google Play ของ Android

เอกสารนี้อธิบายวิธีใช้ Tasks API กับ OAuth 2.0 ใน Android ซึ่งอธิบายกลไกการให้สิทธิ์เพื่อเข้าถึง Google Tasks ของผู้ใช้ และวิธีสร้างออบเจ็กต์ service ของ Tasks API ที่พร้อมใช้งานในแอปพลิเคชัน Android

แอปพลิเคชัน Android ต้องใช้ขั้นตอนหลายขั้นตอนจึงจะใช้ Tasks API ได้ ดังนี้

  1. เลือกบัญชี Google ของผู้ใช้
  2. รับโทเค็นการเข้าถึง OAuth 2.0 จาก AccountManager สำหรับ Task API
  3. ระบุโปรเจ็กต์และตั้งค่า Service Object ของ Tasks
  4. เรียกใช้ Tasks API

การนําเข้าไลบรารีของไคลเอ็นต์ Google

ตัวอย่างที่คุณจะเห็นในเอกสารนี้ใช้ไลบรารีของไคลเอ็นต์ Google APIs สำหรับ Java คุณจะต้องเพิ่มไฟล์ jar ต่อไปนี้ลงในแอปพลิเคชัน Android โดยวางไฟล์ jar ที่ระบุไว้ด้านล่างในโฟลเดอร์ /assets ที่รูทของแอปพลิเคชัน Android นอกจากนี้ โปรดตรวจสอบเวอร์ชันใหม่ด้วยเมื่อเอกสารนี้เก่าขึ้น

นําเข้าไฟล์ JAR ของไลบรารีของไคลเอ็นต์ Google APIs และส่วนขยาย 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

นําเข้าไฟล์ jar ของ Tasks โดยเฉพาะ โดยทำดังนี้

นําเข้า Dependency (ทั้งหมดเป็นส่วนหนึ่งของ 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

บัญชี Google ใน Android

ตั้งแต่ Android 2.0 เป็นต้นไป AccountManager จะจัดการบัญชีที่คุณลงทะเบียนไว้ในสภาพแวดล้อม ซึ่งแสดงอยู่ในส่วนการตั้งค่า > บัญชีและการซิงค์ กล่าวโดยละเอียดคือ จัดการขั้นตอนการให้สิทธิ์และสร้างโทเค็นการให้สิทธิ์ที่จําเป็นสําหรับการเข้าถึงข้อมูลโดยใช้ API

บัญชีที่ลงทะเบียนในสภาพแวดล้อม Android
บัญชีที่ลงทะเบียนในสภาพแวดล้อม Android

หากต้องการใช้ AccountManager เพื่อรับบัญชีและขอโทเค็นการให้สิทธิ์ คุณต้องเพิ่มสิทธิ์ต่อไปนี้ในไฟล์ Manifest ของแอปพลิเคชัน Android

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

คุณสามารถใช้ AccountManager เพื่อรับบัญชี Google ที่คุณต้องการเข้าถึง Tasks AccountManager ไม่เพียงจัดการบัญชี Google เท่านั้น แต่ยังจัดการบัญชีจากผู้ให้บริการรายอื่นด้วย คุณจึงต้องขอบัญชี Google โดยเฉพาะโดยใช้รหัสด้านล่างนี้

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

หรือจะใช้ไลบรารีของไคลเอ็นต์ Google APIs สำหรับ Java ที่มี GoogleAccountManager ซึ่งจัดการเฉพาะบัญชี Google ก็ได้

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

หากมีบัญชี Google มากกว่า 1 บัญชีในอุปกรณ์ Android คุณควรแจ้งให้ผู้ใช้เลือกบัญชีที่ต้องการใช้ด้วยกล่องโต้ตอบที่อาจมีลักษณะดังนี้

กล่องโต้ตอบเลือกบัญชี
กล่องโต้ตอบเลือกบัญชี

คุณสามารถสร้างกล่องโต้ตอบดังกล่าวได้โดยใช้โค้ด Switch/Case ต่อไปนี้ในเมธอด 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) จะแสดงกล่องโต้ตอบเครื่องมือเลือกบัญชี

ขั้นตอนการให้สิทธิ์ Google API ใน Android

เมื่อผู้ใช้เลือกบัญชีแล้ว เราสามารถขอให้ AccountManager ออกโทเค็นการเข้าถึง OAuth 2.0 สําหรับ Task API ซึ่งทำได้โดยการเรียกใช้เมธอด AccountManager.getAuthToken() ในระหว่างการเรียก AccountManager.getAuthToken() นั้น AccountManager จะเป็นผู้ติดต่อปลายทางการให้สิทธิ์ของ Google APIs เมื่อ 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);

ดังที่คุณอาจทราบอยู่แล้ว AccountManager ของ Android รองรับ OAuth 2.0 แบบทดลอง คุณเพียงแค่ต้องใส่ oauth2: ไว้หน้าขอบเขตของ API ที่ต้องการเข้าถึงเมื่อตั้งค่า AUTH_TOKEN_TYPE ดังนั้นสําหรับ 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 จะเริ่มต้นกิจกรรม ซึ่งจะแสดงกล่องโต้ตอบการให้สิทธิ์แก่ผู้ใช้เพื่อให้ผู้ใช้อนุญาตหรือปฏิเสธไม่ให้แอปพลิเคชันของคุณใช้ Tasks API ในบัญชี

กล่องโต้ตอบการให้สิทธิ์
กล่องโต้ตอบการให้สิทธิ์

หากผู้ใช้ปฏิเสธการเข้าถึง Tasks API ของแอปพลิเคชัน ระบบจะแสดงข้อยกเว้น OperationCanceledException ระหว่างการเรียก future.getResult() คุณควรจัดการปัญหานี้อย่างเหมาะสม เช่น ขอให้เลือกบัญชีอีกครั้งหรือแสดงข้อความพร้อมปุ่มให้ให้สิทธิ์เข้าถึงอีกครั้ง

การระบุแอปพลิเคชันและการตั้งค่าออบเจ็กต์บริการ Tasks API

เมื่อแอปพลิเคชันได้รับสิทธิ์เข้าถึง Tasks API และได้รับโทเค็นการเข้าถึงแล้ว คุณจะต้องมีคีย์ API ที่ได้รับจากโปรเจ็กต์ในคอนโซล Google API ด้วย เนื่องจากเป็นสิ่งจําเป็นสำหรับการเรียกใช้ Tasks API โดยทำตามขั้นตอนต่อไปนี้

  1. สร้างโปรเจ็กต์หรือใช้โปรเจ็กต์ที่มีอยู่
  2. เปิดใช้ Tasks API ในโปรเจ็กต์โดยสลับสวิตช์ Tasks API เป็นเปิด
  3. คีย์ API ดูได้ที่สิทธิ์เข้าถึง API > สิทธิ์เข้าถึง API แบบง่าย > คีย์ API

การรับคีย์ API จากคอนโซล API
การขอคีย์ API จากคอนโซล API

คุณต้องใช้คีย์ API เนื่องจากคีย์จะระบุแอปพลิเคชันของคุณและอนุญาตให้ API หักโควต้าและใช้กฎโควต้าที่กำหนดไว้สำหรับโปรเจ็กต์ คุณต้องระบุคีย์ API ในออบเจ็กต์ service ของ 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
}

accessToken จะมีผลเป็นระยะเวลาหนึ่งเท่านั้น คุณจึงจะต้องขอใหม่เมื่อหมดอายุ การจัดการปัญหานี้ทำได้ 2 วิธีดังนี้

  • ขอ accessToken จาก AccountManager ทุกครั้งที่คุณส่งคําขอผ่าน API เนื่องจาก AccountManager แคชโทเค็นไว้ โซลูชันนี้จึงยอมรับได้
  • ใช้ accessToken ต่อไปจนกว่าจะได้รับข้อผิดพลาด 403 เมื่อถึงจุดนั้น ให้ขอโทเค็นใหม่จาก AccountManager

การจัดการงานผ่าน API

ณ จุดนี้ คุณควรมีออบเจ็กต์ service ของ Tasks API ที่สร้างขึ้นอย่างสมบูรณ์แล้ว ซึ่งคุณใช้เพื่อค้นหา API ได้ตามคู่มือนักพัฒนาซอฟต์แวร์ Tasks 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();

อย่าลืมเพิ่มสิทธิ์ในการเข้าถึงอินเทอร์เน็ตลงในไฟล์ Manifest ของแอปพลิเคชัน Android มิเช่นนั้นคําขอข้างต้นไปยังปลายทาง Tasks API จะดำเนินการไม่สำเร็จ

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

แอปพลิเคชันตัวอย่าง

เมื่อเร็วๆ นี้เราได้เพิ่มตัวอย่างใหม่ลงในที่เก็บตัวอย่างของไลบรารีของไคลเอ็นต์ Google APIs สำหรับ Java เพื่อช่วยให้คุณเริ่มต้นใช้งาน Tasks API และ OAuth 2.0 บน Android ได้ ตัวอย่างนี้เป็นแอปพลิเคชัน Android ที่เรียบง่ายแต่ใช้งานได้จริง ซึ่งขอสิทธิ์ใช้ Tasks API และแสดงงานของรายการงานเริ่มต้นใน ListView

การแสดงงานในรายการงานเริ่มต้นใน ListView
การแสดงงานในรายการงานเริ่มต้นใน ListView

ทำตามวิธีการเหล่านี้เพื่อเรียกใช้ตัวอย่าง และโปรดโพสต์ความคิดเห็นหรือคำถามในฟอรัม Google Tasks API