ใช้ Tasks API ใน Android

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

เอกสารนี้จะอธิบายวิธีใช้ Tasks API กับ OAuth 2.0 ใน Android โดยจะอธิบายกลไกการให้สิทธิ์เพื่อรับสิทธิ์เข้าถึง Google Tasks ของผู้ใช้ รวมถึงวิธีเตรียมออบเจ็กต์ service API ของ 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 นอกจากนี้ให้ตรวจหาเวอร์ชันใหม่เมื่อเอกสารนี้เก่ามากขึ้น

นำเข้า 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

นำเข้าทรัพยากร Dependency (ทั้งหมดของ google-api-java-client-1.4.1-beta.zip) ดังนี้

  • Commons-codec-1.3.jar
  • Gson-1.6.jar
  • ฝรั่ง 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 บนอุปกรณ์ Android มากกว่า 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 ที่คุณต้องการเข้าถึง ในการแก้ปัญหานี้ 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 APIs ด้วย เนื่องจากจำเป็นสำหรับการเรียก Tasks API โดยทำตามขั้นตอนต่อไปนี้

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

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

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

อย่าลืมเพิ่มสิทธิ์เข้าถึงอินเทอร์เน็ตลงในไฟล์ 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 ได้ทุกเมื่อ