تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

إعداد OAuth 2.0 للتفويض

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

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

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

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

مواضع الإفصاح عن النطاقات

تتطلّب Drive API نطاقات في Google Cloud Console وعند بدء تشغيل واجهة برمجة التطبيقات في الرمز البرمجي.

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

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

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

كيفية تحديد النطاقات في الرمز البرمجي

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

Java

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'
];

التحقّق من OAuth

قد يتطلّب استخدام نطاقات OAuth معيّنة أن يمر تطبيقك بعملية التحقّق الموضّحة في مركز مساعدة التحقّق من تطبيقات OAuth. اطّلِع على الأسئلة الشائعة حول تطبيقات OAuth لتحديد الحالات التي يجب فيها التحقّق من تطبيقك ونوع التحقّق المطلوب. يُرجى الاطّلاع أيضًا على بنود خدمة Google Drive.

حالات استخدام نطاق محدود

بالنسبة إلى Drive، يمكن لأنواع التطبيقات التالية فقط الوصول إلى النطاقات المحظورة:

تطبيقات الويب والتطبيقات الخاصة بأنظمة تشغيل معيّنة التي توفّر مزامنة محلية أو احتياطية تلقائية لملفات المستخدمين في Drive
تطبيقات الإنتاجية والتطبيقات التعليمية التي قد تتضمّن واجهة المستخدم الخاصة بها التفاعل مع ملفات Drive (أو البيانات الوصفية أو الأذونات الخاصة بها). تشمل تطبيقات الإنتاجية إدارة المهام وتدوين الملاحظات والتواصل بين مجموعات العمل وتطبيقات التعاون في الصفوف الدراسية.
تطبيقات إعداد التقارير والأمان التي توفّر إحصاءات للمستخدمين أو العملاء حول كيفية مشاركة الملفات أو الوصول إليها

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

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

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

مزايا نطاق OAuth لملف 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 غير حسّاسة، فهي تتيح عملية تحقّق أكثر سلاسة.

حفظ رموز إعادة التحميل

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

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