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

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

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

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

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

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

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

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

إعداد البيئة

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

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

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

• في Google Cloud Console، فعِّل Google Picker API.

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

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

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

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

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

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

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

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

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

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

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

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 إلى التطبيق الذي تم استدعاؤها منه من خلال عنوان 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. يمكنك أيضًا تخصيص 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.