اختيار نطاقات Google Drive API

يتضمّن هذا المستند معلومات حول المصادقة والتفويض الخاصة بواجهة Google Drive API. قبل قراءة هذا المستند، احرص على قراءة معلومات المصادقة والتفويض العامة في Google Workspace على الرابط مزيد من المعلومات عن المصادقة والتفويض.

ضبط OAuth 2.0 للحصول على إذن

لتفويض تطبيقك، تتطلّب منك Google Drive API تحديد نطاقات OAuth في مكانَين: Google Cloud Console وتطبيقك.

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

ضبط شاشة موافقة بروتوكول OAuth واختيار النطاقات لتحديد المعلومات التي يتم عرضها للمستخدمين ومراجعي التطبيقات، وتسجيل تطبيقك كي تتمكّن من نشره لاحقًا

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

يمكنك تحديد نطاق واحد أو أكثر من نطاقات OAuth في المرة الواحدة ضمن رمز تطبيقك كصفيف.

يوضّح نموذج الرمز البرمجي التالي كيفية تعريف نطاقات OAuth متعددة:

جافا

List<String> SCOPES = Arrays.asList(
  DriveScopes.DRIVE_FILE,
  DriveScopes.DRIVE_METADATA_READONLY
);

Python

SCOPES = [
  "https://www.googleapis.com/auth/drive.file",
  "https://www.googleapis.com/auth/drive.metadata.readonly",
]

Node.js

const SCOPES = [
  'https://www.googleapis.com/auth/drive.file',
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

للاطّلاع على كيفية تحديد النطاقات واستخدامها في نموذج رمز برمجي كامل، راجِع أدلة البدء السريع.

نطاقات Drive API

لتحديد مستوى الوصول الممنوح لتطبيقك، عليك تحديد نطاقات الأذونات والإفصاح عنها. نطاق التفويض هو سلسلة معرّف الموارد المنتظم (URI) في OAuth 2.0 تتضمّن اسم تطبيق Google Workspace ونوع البيانات التي يمكنه الوصول إليها ومستوى الوصول. النطاقات هي طلبات تطبيقك للعمل مع بيانات Google Workspace، بما في ذلك بيانات حسابات المستخدمين على Google.

عند تثبيت تطبيقك، يُطلب من المستخدم التحقّق من صحة النطاقات التي يستخدمها التطبيق. وبشكل عام، عليك اختيار النطاق الأكثر تركيزًا وتجنُّب طلب نطاقات لا يحتاجها تطبيقك. يمنح المستخدمون إذن الوصول إلى النطاقات المحدودة والموضّحة بوضوح بشكل أسهل.

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

النطاقات غير الحسّاسة

يُنصح باستخدام نطاقات Drive API التالية لمعظم حالات الاستخدام:

رمز النطاق الوصف
https://www.googleapis.com/auth/drive.appdata
https://www.googleapis.com/auth/drive.appfolder		 عرض وإدارة بيانات الإعداد الخاصة بالتطبيق في Google Drive
https://www.googleapis.com/auth/drive.install السماح للتطبيقات بالظهور كخيار في القائمة "فتح باستخدام" أو القائمة "جديد"
https://www.googleapis.com/auth/drive.file إنشاء ملفات جديدة على Drive أو تعديل الملفات الحالية التي تفتحها باستخدام تطبيق أو التي يشاركها المستخدم مع تطبيق أثناء استخدام Google Picker API أو أداة اختيار الملفات في التطبيق

النطاقات الحسّاسة

رمز النطاق الوصف
https://www.googleapis.com/auth/drive.apps.readonly عرض التطبيقات التي تم منحها الإذن بالوصول إلى Drive

النطاقات المحظورة

رمز النطاق الوصف
https://www.googleapis.com/auth/drive عرض جميع ملفاتك في Drive وإدارتها
https://www.googleapis.com/auth/drive.readonly عرض جميع ملفات Drive وتنزيلها
https://www.googleapis.com/auth/drive.activity عرض سجلّ الأنشطة للملفات في حسابك على Drive وإضافة نشاط إليه
https://www.googleapis.com/auth/drive.activity.readonly عرض سجلّ الأنشطة للملفات في حسابك على Drive
https://www.googleapis.com/auth/drive.meet.readonly الاطّلاع على ملفات Drive التي تم إنشاؤها أو تعديلها بواسطة Google Meet
https://www.googleapis.com/auth/drive.metadata عرض البيانات الوصفية للملفات وإدارتها في Drive
https://www.googleapis.com/auth/drive.metadata.readonly عرض البيانات الوصفية للملفات في Drive
https://www.googleapis.com/auth/drive.scripts تعديل طريقة عمل النصوص البرمجية لبرمجة تطبيقات Google

تشير النطاقات في الجداول السابقة إلى مستوى حساسيتها، وفقًا للتعريفات التالية:

إذا كان تطبيقك يتطلّب الوصول إلى أي واجهات برمجة تطبيقات أخرى من Google، يمكنك إضافة هذه النطاقات أيضًا. لمزيد من المعلومات عن نطاقات Google API، يُرجى الاطّلاع على استخدام بروتوكول OAuth 2.0 للدخول إلى واجهات Google APIs.

لمزيد من المعلومات حول نطاقات OAuth 2.0 المحدّدة، يُرجى الاطّلاع على نطاقات OAuth 2.0 لـ Google APIs.

مؤهلات النطاقات المحظورة

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

  1. الاحتفاظ بنسخة احتياطية والمزامنة: تطبيقات خاصة بمنصات معيّنة وتطبيقات ويب توفّر مزامنة محلية أو احتياطية تلقائية لملفات المستخدمين على Drive

  2. الإنتاجية والتعليم: التطبيقات التي تتضمّن واجهة مستخدم أساسية قد تتضمّن التفاعل مع ملفات Drive أو البيانات الوصفية أو الأذونات تشمل هذه التطبيقات تطبيقات إدارة المهام وتدوين الملاحظات والتواصل بين مجموعات العمل وتطبيقات التعاون في الصفوف الدراسية.

  3. إعداد التقارير والأمان: التطبيقات التي تقدّم للمستخدمين أو العملاء إحصاءات حول كيفية مشاركة الملفات أو الوصول إليها

لمواصلة استخدام النطاقات المحظورة، عليك إعداد تطبيقك لإثبات ملكية النطاقات المحظورة.

نقل تطبيق حالي من النطاقات المحظورة

إذا كان تطبيق Drive يستخدم نطاقات مقيّدة، ننصحك بنقل البيانات إلى نطاق غير حسّاس في Drive API. يؤدي استخدام نطاقات غير حساسة، مثل drive.file، إلى منح إذن وصول محدود إلى ميزات معيّنة يحتاجها التطبيق لكل ملف.

يمكن أن تنتقل العديد من التطبيقات إلى إذن الوصول إلى كل ملف على حدة بدون إجراء أي تغييرات.

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

مزايا نطاق ملف Drive

يؤدي استخدام نطاق OAuth drive.file مع Google Picker API إلى تحسين تجربة المستخدم وسلامة تطبيقك.

يتيح drive.file نطاق OAuth للمستخدمين اختيار الملفات التي يريدون مشاركتها مع تطبيقك، ما يمنحهم المزيد من التحكّم والثقة في أنّ وصول تطبيقك إلى ملفاتهم محدود وأكثر أمانًا. في المقابل، قد يؤدي طلب الوصول إلى جميع ملفات Drive إلى إحجام المستخدمين عن التفاعل مع تطبيقك.

في ما يلي بعض الأسباب التي تستدعي استخدام النطاق drive.file:

  • سهولة الاستخدام: يعمل النطاق drive.file مع جميع موارد REST في Drive API، ما يعني أنّه يمكنك استخدامه بالطريقة نفسها التي تستخدم بها نطاقات OAuth الأوسع.

  • الميزات: توفّر Google Picker API واجهة مشابهة لواجهة مستخدم Drive. ويشمل ذلك عدّة طرق عرض تعرض معاينات وصورًا مصغّرة لملفات Drive، ونافذة مضمّنة ومنبثقة حتى لا يضطر المستخدمون إلى مغادرة التطبيق الرئيسي.

  • الراحة: يمكن للتطبيقات تطبيق فلاتر على أنواع معيّنة من ملفات Drive (مثل "مستندات Google" و"جداول بيانات Google" والصور) عند استخدام فلتر على ملفات Google Picker.

  • عملية تحقّق مباشرة: بما أنّ drive.file غير حسّاس، يتيح ذلك إجراء عملية تحقّق أكثر سلاسة.

تخزين الرموز المميزة لإعادة التحميل بأمان

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

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

احفظ رموز التحديث المميزة في مساحة تخزين آمنة وطويلة الأمد، وواصِل استخدامها طالما أنّها تظل صالحة.

لمزيد من المعلومات، يُرجى الاطّلاع على استخدام بروتوكول OAuth 2.0 للوصول إلى Google APIs.