استخدام واجهة برمجة تطبيقات "مهام Google" على Android

تحذير: تم إيقاف هذا المستند نهائيًا. للحصول على معلومات عن تفويض تطبيقات Android باستخدام بروتوكول OAuth 2.0، يُرجى الاطّلاع على مستندات تفويض "خدمات Google Play".

يوضّح هذا المستند كيفية استخدام واجهة Tasks API مع بروتوكول OAuth 2.0 على Android. ويوضّح آليات التفويض للوصول إلى "مهام Google" الخاصة بالمستخدم وكيفية الحصول على عنصر خدمة Tasks API جاهز للاستخدام في تطبيق Android.

لكي يستخدم تطبيق Android واجهة برمجة التطبيقات Tasks API، يجب اتّباع عدة خطوات:

1. اختيار حساب المستخدم على Google
2. الحصول على رمز مميّز للوصول إلى OAuth 2.0 من AccountManager لواجهة برمجة التطبيقات Task API
3. تحديد مشروعك وإعداد كائن الخدمة في "مهام Google"
4. إجراء طلبات بيانات من واجهة برمجة التطبيقات Tasks API

استيراد مكتبة برامج Google

تستخدِم النماذج الواردة في هذا المستند مكتبة برامج Google APIs للغة Java. ستحتاج إلى إضافة حِزم JAR التالية إلى تطبيق Android. لإجراء ذلك، ضَع حِزم JAR المدرَجة أدناه في مجلد /assets في جذر تطبيق Android. يمكنك أيضًا البحث عن إصدارات جديدة عندما يصبح هذا المستند قديمًا.

استورِد حِزم مكتبة برامج 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 الخاصة بتطبيق "مهام Google":

• 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

منذ الإصدار 2.0 من Android، يدير AccountManager الحسابات التي سجّلتها في بيئتك، وهي الحسابات المدرَجة ضمن الإعدادات > الحسابات والمزامنة. وعلى وجه التحديد، يعالج هذا الإطار عملية التفويض ويمكنه إنشاء الرموز المميّزة للتفويض المطلوبة للوصول إلى البيانات باستخدام واجهات برمجة التطبيقات.

الحسابات المسجَّلة في بيئة Android

لكي تتمكّن من استخدام AccountManager للحصول على الحسابات وطلب الرموز المميّزة للتفويض، عليك إضافة الأذونات التالية في بيان تطبيق Android:

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

يمكنك استخدام AccountManager للحصول على حساب Google الذي تريد الوصول إلى "مهام Google" من خلاله. لا يدير 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، عليك أن تطلب من المستخدم تحديد الحساب الذي يريد استخدامه من خلال مربّع حوار قد يبدو على النحو التالي:

مربّع حوار اختيار الحساب

يمكنك إنشاء مربّع حوار مماثل باستخدام رمز التبديل/الحالة التالي في طريقة 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. ما عليك سوى إضافة 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 وتم منحه رمزًا مميّزًا للوصول، ستحتاج أيضًا إلى مفتاح واجهة برمجة التطبيقات الذي يجب الحصول عليه من مشروع في وحدة تحكّم Google APIs Console لأنّه إلزامي لإجراء طلبات البيانات من واجهة برمجة التطبيقات Tasks API. اتّبِع الخطوات التالية لإجراء ذلك:

1. إنشاء مشروع أو استخدام مشروع حالي
2. فعِّل واجهة برمجة التطبيقات Tasks API في مشروعك من خلال تبديل مفتاح واجهة برمجة التطبيقات Tasks API إلى تفعيل.
3. يمكن العثور على مفتاح واجهة برمجة التطبيقات في الوصول إلى واجهة برمجة التطبيقات > الوصول البسيط إلى واجهة برمجة التطبيقات > مفتاح واجهة برمجة التطبيقات.

الحصول على مفتاح واجهة برمجة التطبيقات من "وحدة تحكّم واجهات برمجة التطبيقات"

مفتاح واجهة برمجة التطبيقات إلزامي لأنّه يحدِّد تطبيقك، وبالتالي يسمح لواجهة برمجة التطبيقات بخصم الحصة واستخدام قواعد الحصة المحدَّدة لمشروعك. عليك تحديد مفتاح واجهة برمجة التطبيقات في عنصر خدمة "مهام Google":

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 صالحًا إلا لفترة زمنية معيّنة، لذا عليك الحصول على رمز جديد عند انتهاء صلاحيته. هناك طريقتان لحلّ هذه المشكلة:

• اطلب accessToken من AccountManager في كل مرة تُقدّم فيها طلبات من خلال واجهة برمجة التطبيقات. وبما أنّ AccountManager يخزّن الرمز المميّز في ذاكرة التخزين المؤقت، يكون هذا الحلّ مقبولًا.
• يُرجى مواصلة استخدام accessToken إلى أن يظهر لك الخطأ 403، وعندها يمكنك طلب رمز مميّز جديد من AccountManager.

التلاعب بالمهام من خلال واجهة برمجة التطبيقات

في هذه المرحلة، من المفترض أن يكون لديك عنصر خدمة Tasks 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();

لا تنسَ إضافة إذن الوصول إلى الإنترنت إلى بيان تطبيق Android، وإلا ستتعذّر الطلبات أعلاه إلى نقاط نهاية Tasks API:

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

نموذج طلب

أضفنا مؤخرًا نموذجًا جديدًا إلى مستودع نماذج مكتبة برامج Google APIs للغة Java لمساعدتك في بدء استخدام واجهة برمجة التطبيقات Tasks API وOAuth 2.0 على Android. العيّنة هي تطبيق Android بسيط يعمل بشكل كامل ويطلب تفويضًا لاستخدام واجهة برمجة التطبيقات Tasks API وعرض مهام قائمة المهام التلقائية في ListView.

عرض المهام في قائمة المهام التلقائية في ListView

اتّبِع هذه التعليمات لتشغيل العيّنة، ولا تتردد في نشر ملاحظاتك أو أسئلتك في منتدى Google Tasks API.