دمج Google Picker في تطبيقات أجهزة الكمبيوتر والأجهزة الجوّالة

يوضّح هذا المستند كيفية دمج Google Picker في تطبيقات الكمبيوتر والأجهزة الجوّالة باستخدام Google Picker API.

تتيح Google Picker API للمستخدمين اختيار ملفات Google Drive أو تحميلها. يمكن للمستخدمين منح الإذن لتطبيق الكمبيوتر أو الجهاز الجوّال أو تطبيق الويب بالوصول إلى بياناتهم على Drive، ما يوفّر طريقة آمنة ومصرّح بها للتفاعل مع ملفاتهم.

الميزات

يتضمّن Google Picker عدة ميزات:

  • مظهر مشابه لواجهة مستخدم Google Drive UI
  • عدّة طرق عرض تعرض معاينات وصورًا مصغّرة لملفات Drive
  • طرق عرض تمت فلترتها مسبقًا ولا تعرض سوى أنواع ملفات معيّنة (مثل ملفات PDF أو الصور) أو مجلدات معيّنة
  • إعادة توجيه إلى Google Picker ضمن علامة تبويب جديدة في المتصفّح التلقائي للمستخدم

يُرجى العِلم أنّه على الرغم من إمكانية اختيار الملفات وتحميلها باستخدام Google Picker، لا يسمح للمستخدمين بتنظيم الملفات أو نقلها أو نسخها من مجلد إلى آخر. لإدارة الملفات، يجب استخدام إما Google Drive API أو واجهة مستخدم Drive.

المتطلبات الأساسية

يجب أن تلتزم التطبيقات التي تستخدم Google Picker بجميع بنود الخدمة الحالية. الأهم من ذلك هو تحديد هويتك بشكل صحيح في طلباتك.

يجب أيضًا أن يكون لديك مشروع على Google Cloud.

إعداد البيئة

لبدء استخدام Google Picker API، يجب إعداد البيئة.

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

قبل استخدام Google APIs، عليك تفعيلها في مشروع على Google Cloud. يمكنك تفعيل واجهة برمجة تطبيق واحدة أو أكثر في مشروع واحد على Google Cloud.

إعداد المصادقة والتفويض

لمصادقة المستخدمين النهائيين والوصول إلى بيانات المستخدمين في تطبيقك، عليك إنشاء معرّف عميل واحد أو أكثر لبروتوكول OAuth 2.0. يُستخدم معرّف العميل لتعريف تطبيق واحد على خوادم OAuth من Google. إذا كان تطبيقك يعمل على منصات متعددة، عليك إنشاء معرّف عميل منفصل لكل منصة.

تفويض بيانات اعتماد تطبيق كمبيوتر

لإنشاء معرّف عميل لبروتوكول OAuth 2.0، اتّبِع الخطوات التالية:

  1. في Google API Console، انتقِل إلى "القائمة" > منصة مصادقة Google > العملاء.

    الانتقال إلى "العملاء"

  2. انقر على إنشاء عميل.
  3. انقر على نوع التطبيق > تطبيق كمبيوتر.
  4. في حقل الاسم ، اكتب اسمًا لبيانات الاعتماد. لا يظهر هذا الاسم إلا في Google API Console.
  5. انقر على إنشاء.

    تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا ضمن "معرّفات عملاء OAuth 2.0".

لكي تحصل التطبيقات على إذن الوصول إلى الملفات التي تم منحها سابقًا، عليك اتّباع الخطوات التالية:

  1. عليك الحصول على رمز OAuth 2.0 المميّز بنطاق drive.file أو drive أو drive.readonly باستخدام هذه التعليمات: استخدام بروتوكول OAuth 2.0 للدخول إلى Google APIs. لمزيد من المعلومات عن النطاقات، يُرجى الاطّلاع على اختيار نطاقات Google Drive API.

  2. مرِّر رمز OAuth 2.0 المميّز إلى Drive API لقراءة الملفات وتعديلها التي سبق أن منح المستخدم الإذن بالوصول إليها.

تفويض بيانات اعتماد تطبيقك للأجهزة الجوّالة

لإنشاء معرّف عميل لبروتوكول OAuth 2.0، اتّبِع الخطوات الواردة ضمن تفويض بيانات اعتماد تطبيق للأجهزة الجوّالة.

تفويض بيانات اعتماد تطبيق الويب

لإنشاء معرّف عميل لبروتوكول OAuth 2.0، اتّبِع الخطوات الواردة ضمن تفويض بيانات الاعتماد لتطبيق ويب.

عرض Google Picker

تعيد Google Picker API للتطبيقات على الكمبيوتر والأجهزة الجوّالة توجيه المستخدم إلى Google Picker ضمن علامة تبويب جديدة في المتصفّح التلقائي للمستخدم. بعد أن يمنح المستخدم الإذن ويختار الملفات ذات الصلة، يعود Google Picker إلى التطبيق الذي تم استدعاؤه من خلال عنوان URL للردّ.

لفتح Google Picker API في صفحة عميل، استخدِم Google Picker API لتطبيقات الويب بدلاً من ذلك. لمزيد من المعلومات، يُرجى الاطّلاع على دمج Google Picker في تطبيقات الويب.

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

  1. اطلب الإذن بالوصول إلى نطاق drive.file لفتح صفحة الوصول إلى OAuth 2.0 في علامة تبويب متصفّح جديدة باستخدام هذه التعليمات: استخدام بروتوكول OAuth 2.0 للدخول إلى Google APIs. لمزيد من المعلومات عن النطاقات، يُرجى الاطّلاع على اختيار نطاقات Google Drive API.

    يُرجى العِلم أنّه لا يُسمح لهذه التطبيقات إلا بنطاق drive.file ولا يمكن دمجه مع أي نطاق آخر.

  2. يقبل عنوان URL لعلامة تبويب المتصفّح الجديدة جميع مَعلمات سلسلة طلبات البحث العادية لبروتوكول OAuth.

    عليك إلحاق مَعلمتَي عنوان URL‏ prompt وtrigger_onepick بطلب عنوان URL لمنح إذن OAuth 2.0. يمكنك أيضًا تخصيص Google Picker بشكل اختياري باستخدام عدة مَعلمات أخرى:

    المَعلمة الوصف الحالة
    prompt=consent طلب الإذن بالوصول إلى الملف مطلوب
    trigger_onepick=true تفعيل Google Picker مطلوب
    allow_multiple=true السماح للمستخدم باختيار ملفات متعددة إذا كانت القيمة "صحيح" اختياري
    mimetypes=MIMETYPES قائمة بأنواع MIME مفصولة بفواصل لفلترة نتائج البحث إذا لم يتم ضبط هذه المَعلمة، يتم عرض الملفات لجميع أنواع MIME في طريقة العرض. اختياري
    file_ids=FILE_IDS قائمة قيم مفصولة بفاصلة لمعرّفات الملفات لفلترة نتائج البحث إذا لم يتم ضبط هذه المَعلمة، يتم عرض جميع الملفات في طريقة العرض. اختياري
    allow_folder_selection=true السماح للمستخدم باختيار المجلدات أيضًا إذا كانت القيمة "صحيح" اختياري

    يوضّح النموذج التالي طلب عنوان URL لمنح إذن OAuth 2.0:

    https://accounts.google.com/o/oauth2/v2/auth? \
client_id=CLIENT_ID \
&scope=https://www.googleapis.com/auth/drive.file \
&redirect_uri=REDIRECT_URI \
&response_type=code \
&access_type=offline \
&prompt=consent \
&trigger_onepick=true

    غيِّر القيم في السلسلة على الشكل التالي:

    • CLIENT_ID: معرّف عميل تطبيقك

    • REDIRECT_URI: المكان الذي يعيد إليه خادم منح الإذن توجيه متصفّح المستخدم بعد المصادقة الناجحة على سبيل المثال، https://www.cymbalgroup.com/oauth2callback

      يجب أن يكون redirect_uri المحدّد عنوان URL عامًا يستخدم HTTPS. إذا أردت استخدام بروتوكول مخصّص أو عنوان URL للمضيف المحلي لـ redirect_uri، عليك استخدام عنوان URL عام يستخدم HTTPS ثم يعيد التوجيه إلى البروتوكول المخصّص أو عنوان URL للمضيف المحلي.

  3. بعد أن يمنح المستخدم الإذن ويختار الملفات ذات الصلة، يعيد OAuth التوجيه إلى redirect_uri المحدّد في الطلب مع إلحاق مَعلمات عنوان URL التالية:

    • picked_file_ids: إذا منح المستخدم الإذن واختار ملفات، تكون هذه القيمة قائمة بمعرّفات الملفات المحدّدة مفصولة بفواصل.

    • code: رمز الدخول أو رمز التفويض استنادًا إلى مَعلمة response_type التي تم ضبطها في الطلب تتضمّن هذه المَعلمة رمز تفويض جديدًا .

    • scope: النطاقات المضمّنة في الطلب

    • error: إذا ألغى المستخدم الطلب ضمن مسار الموافقة، يتم عرض خطأ.

    يوضّح النموذج التالي استجابة عنوان URL لمنح إذن OAuth 2.0:

    https://REDIRECT_URI?picked_file_ids=PICKED_FILE_IDS&code=CODE&scope=SCOPES

  4. يجب أن تبدّل التطبيقات رمز التفويض من الخطوة 3 برمز OAuth 2.0 مميّز جديد. لمزيد من المعلومات، يُرجى الاطّلاع على تبديل رمز التفويض برموز التجديد والدخول والدخول.

  5. يمكن للتطبيقات بعد ذلك استخدام معرّفات الملفات من مَعلمة عنوان URL في الخطوة 3 ورمز OAuth 2.0 المميّز الذي تم الحصول عليه في الخطوة 4 لاستدعاء Drive API. لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة على Google Drive API.

استخدام Google Picker مع تطبيقات Android

يمكنك أيضًا استخدام Google Picker في تطبيقات Android للأجهزة الجوّالة.

تفويض بيانات اعتماد تطبيق للأجهزة الجوّالة

لاستخدام Google Picker في تطبيق Android، عليك منح المستخدمين الإذن باستخدام OAuth 2.0، على غرار تطبيقات الكمبيوتر. لمعرفة تفاصيل عن مصادقة Android، يُرجى الاطّلاع على منح الإذن بالوصول إلى بيانات مستخدمي Google.

لعرض Google Picker أثناء منح الإذن، أنشِئ AuthorizationRequest واستخدِم مَعلمة المصدر PICKER_OAUTH_TRIGGER في العنصر AuthorizationRequest.ResourceParameter.

عند إنشاء AuthorizationRequest:

  • استخدِم نطاق drive.file.

  • استدعِ setOptOutIncludingGrantedScopes إلى true للتأكّد من أنّ الرمز المميّز الذي يتم عرضه مخصّص لنطاق drive.file فقط وليس لأي نطاقات تم منحها سابقًا.

  • اضبط الحقل AuthorizationRequest.Prompt على CONSENT لطلب موافقة المستخدم حتى إذا تم منحها من قبل.

  • يمكنك اختياريًا استخدام عامل التشغيل "أو" (|) على مستوى البت لضبط حقل AuthorizationRequest.Prompt على SELECT_ACCOUNT أيضًا للسماح للمستخدم باختيار حساب قبل عرض طلب الموافقة.

استدعاء Google Picker

على غرار تطبيقات الكمبيوتر، يمكنك تخصيص Google Picker باستخدام عدة مَعلمات اختيارية:

  • PICKER_ALLOW_MULTIPLE: يسمح للمستخدمين باختيار ملفات متعددة.
  • PICKER_MIMETYPES: يقبل قائمة بأنواع MIME مفصولة بفواصل لفلترة نتائج البحث. إذا لم يتم ضبط هذه المَعلمة، يتم عرض الملفات لجميع أنواع MIME في طريقة العرض.
  • PICKER_FILE_IDS: يقبل قائمة قيم مفصولة بفاصلة لمعرّفات الملفات لفلترة نتائج البحث. إذا لم يتم ضبط هذه المَعلمة، يتم عرض جميع الملفات في طريقة العرض.
  • PICKER_ALLOW_FOLDER_SELECTION: يسمح للمستخدمين باختيار المجلدات أيضًا.

لمزيد من المعلومات عن المَعلمات الاختيارية في تطبيقات الكمبيوتر، يُرجى الاطّلاع على عرض Google Picker.

بعد أن يمنح المستخدم الإذن ويختار الملفات ذات الصلة، يتم عرض العنصر getTokenResponseParams لمصدر AuthorizationResult. إذا منح المستخدم الإذن، يحتوي هذا العنصر على قيمة picked_file_ids، وهي قائمة بمعرّفات الملفات المحدّدة مفصولة بفواصل.