نظرة عامة على تطبيقات أجهزة الكمبيوتر والأجهزة الجوّالة

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

تعمل Google Picker كصفحة "فتح ملف" للملفات المخزّنة على Drive وتتضمّن عدة ميزات:

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

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

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

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

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

إعداد البيئة

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

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

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

إنشاء مفتاح واجهة برمجة تطبيقات

مفتاح واجهة برمجة التطبيقات هو سلسلة طويلة تحتوي على أحرف كبيرة وصغيرة وأرقام وشرطات سفلية وواصلات، مثل AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe. تُستخدَم طريقة المصادقة هذه للوصول بشكل مجهول إلى البيانات المتاحة للجميع، مثل ملفات Google Workspace التي تتم مشاركتها باستخدام إعداد المشاركة "أي مستخدم على الإنترنت لديه هذا الرابط". لمزيد من التفاصيل، يُرجى الاطّلاع على مقالة إدارة مفاتيح واجهة برمجة التطبيقات.

لإنشاء مفتاح واجهة برمجة تطبيقات:

  1. في Google Cloud Console، انتقِل إلى "القائمة" > واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد.

    الانتقال إلى "بيانات الاعتماد"

  2. انقر على إنشاء بيانات اعتماد > مفتاح واجهة برمجة تطبيقات.
  3. يظهر مفتاح واجهة برمجة التطبيقات الجديد.
    • انقر على "نسخ" لنسخ مفتاح واجهة برمجة التطبيقات لاستخدامه في رمز تطبيقك. يمكنك أيضًا العثور على مفتاح واجهة برمجة التطبيقات في قسم "مفاتيح واجهة برمجة التطبيقات" ضمن بيانات اعتماد مشروعك.
    • لمنع الاستخدام غير المصرّح به، ننصحك بتقييد الأماكن وواجهات برمجة التطبيقات التي يمكن استخدام مفتاح واجهة برمجة التطبيقات فيها. لمزيد من التفاصيل، يُرجى الاطّلاع على مقالة إضافة قيود على واجهة برمجة التطبيقات.

السماح ببيانات اعتماد لتطبيق كمبيوتر مكتبي

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

عرض Google Picker

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

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

  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:

    المَعلمة الوصف الحالة
    prompt=consent طلب الإذن بالوصول إلى الملف مطلوب
    trigger_onepick=true تفعيل Google Picker مطلوب

    يمكنك أيضًا تخصيص 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:

  • استخدِم النطاق https://www.googleapis.com/auth/drive.file.
  • استدعِ setOptOutIncludingGrantedScopes(true) للتأكّد من أنّ الرمز المميّز الذي يتم عرضه مخصّص فقط للنطاق https://www.googleapis.com/auth/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، وهي قائمة بمعرّفات الملفات المحدّدة مفصولة بفواصل.