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

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

ضبط بروتوكول OAuth 2.0 للتفويض

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

يتيح نطاق OAuth drive.file للمستخدمين اختيار الملفات التي يريدون مشاركتها مع تطبيقك. يمنح ذلك المستخدمين مزيدًا من التحكّم والثقة بأنّ وصول تطبيقك إلى ملفاتهم محدود وأكثر أمانًا. في المقابل، قد يؤدي طلب إذن وصول واسع إلى جميع ملفات 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.