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

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

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

لكي يتمكن تطبيق Android من استخدام واجهة برمجة تطبيقات مهام Google، هناك عدة خطوات لازمة، تحتاج إلى:

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

استيراد مكتبة عملاء Google

تستخدم النماذج التي ستجدها في هذا المستند مكتبة عملاء Google APIs للغة Java. يجب إضافة الأوعية التالية إلى تطبيق Android. لتنفيذ ذلك، يجب وضع الأواني المدرجة أدناه في المجلد /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

استورِد وعاء "مهام 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

منذ نظام التشغيل Android 2.0، يدير 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. إذًا بالنسبة إلى واجهة برمجة تطبيقات "مهام Google"، يمكنك استخدام:

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 لواجهة برمجة تطبيقات مهام Google، ويمكن للمستخدمين قراءتها. يكافئ استخدام نطاق OAuth 2.0. على سبيل المثال، يمكنك استخدام:

String AUTH_TOKEN_TYPE = "Manage your tasks";

يمكنك أيضًا استخدام الاسم المستعار AUTH_TOKEN_TYPE عرض المهام الذي يعادل نطاق القراءة فقط لواجهة برمجة تطبيقات "مهام Google": oauth2:https://www.googleapis.com/auth/tasks.readonly.

أثناء AccountManager.getAuthToken()، يمكنك الاتصال بـ AccountManager للتحقق مما إذا كان قد تم تفويض تطبيقك للوصول إلى واجهة برمجة تطبيقات "مهام Google". إذا لم يكن قد تم تفويض تطبيقك، يبدأ النشاط بواسطة AccountManager والذي يعرض مربع حوار تفويض للمستخدم حتى يتمكن من السماح أو رفض تطبيقك باستخدام واجهة برمجة تطبيقات مهام Google في حسابه.

مربع حوار التفويض

إذا رفض المستخدم وصول تطبيقك إلى واجهة برمجة تطبيقات مهام Google، سيتم طرح OperationCanceledException أثناء استدعاء future.getResult(). يجب التعامل مع هذا الأمر بشكل مرن على سبيل المثال عن طريق طلب اختيار الحساب مرة أخرى أو عرض رسالة تحتوي على زر للسماح بالوصول مرة أخرى.

تحديد تطبيقك وإعداد كائن خدمة واجهة برمجة تطبيقات "مهام Google"

بعد أن أصبح لدى تطبيقك إذن بالوصول إلى واجهة برمجة تطبيقات "مهام Google" وتم منحه رمز الدخول، عليك أيضًا الحصول على مفتاح واجهة برمجة التطبيقات الذي تحتاجه للحصول عليه من مشروع في وحدة تحكم واجهات برمجة تطبيقات Google لأنه إلزامي لإجراء طلبات بيانات من واجهة برمجة التطبيقات في "مهام Google". للقيام بذلك، اتبع الخطوات التالية:

1. إنشاء مشروع أو استخدام مشروع حالي
2. يمكنك تفعيل واجهة برمجة تطبيقات "مهام Google" في مشروعك من خلال تبديل مفتاح تبديل واجهة برمجة تطبيقات "مهام Google" إلى تفعيل.
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.

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

في هذه المرحلة، يجب أن يكون لديك عنصر خدمة لواجهة برمجة تطبيقات "مهام Google" تم إعداده بالكامل ويمكنك استخدامه لطلب البحث عن واجهة برمجة التطبيقات وفقًا لدليل مطوّر برامج واجهة برمجة تطبيقات "مهام Google"، على سبيل المثال:

// 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، وإلا سيتعذّر تنفيذ الطلبات أعلاه لنقاط نهاية واجهة برمجة تطبيقات "مهام Google":

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

نموذج تطبيق

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

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

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