ใช้ Tasks API ใน Android

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

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

หากต้องการให้แอปพลิเคชัน Android ใช้ Tasks API ได้หลายขั้นตอน คุณต้องดำเนินการดังนี้

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

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

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

นำเข้า Jars ไลบรารีของไคลเอ็นต์ 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 ดังนี้

• 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

บัญชี Google ใน Android

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

บัญชีที่ลงทะเบียนในระบบ 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();

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

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

คุณสามารถสร้างกล่องโต้ตอบที่ใช้โค้ดสวิตช์/เคสต่อไปนี้ในเมธอด 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 APIs ใน 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 เวอร์ชันทดลอง คุณเพียงต้องใส่คำนำหน้าขอบเขตของ API ที่ต้องการเข้าถึงด้วย oauth2: เมื่อตั้งค่า 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 ที่คุณต้องการเข้าถึง เพื่อหลีกเลี่ยงปัญหานี้ มีชื่อแทน AUTH_TOKEN_TYPE ที่มนุษย์อ่านได้ง่ายสำหรับ Tasks API ซึ่งเทียบเท่ากับการใช้ขอบเขต 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 ในระหว่างการเรียกใช้ OperationCanceledException คุณควรจัดการเรื่องนี้อย่างค่อยเป็นค่อยไป เช่น ขอเลือกบัญชีอีกครั้ง หรือแสดงข้อความที่มีปุ่มสำหรับให้สิทธิ์การเข้าถึงอีกครั้ง

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

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

1. สร้างโปรเจ็กต์หรือใช้โปรเจ็กต์ที่มีอยู่
2. เปิดใช้ Tasks API ในโปรเจ็กต์โดยสลับสวิตช์ Tasks API เป็นเปิด
3. ดูคีย์ 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

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

ในตอนนี้ คุณควรมีออบเจ็กต์บริการ 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 มิเช่นนั้นคำขอข้างต้นที่ส่งไปยังปลายทาง API ของ Tasks จะไม่สำเร็จ

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

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

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

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

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