این سند حاوی اطلاعات مربوط به مجوز و احراز هویت مختص API گوگل درایو است. قبل از مطالعه این سند، حتماً اطلاعات عمومی احراز هویت و مجوز Google Workspace را در بخش «درباره احراز هویت و مجوز بیشتر بدانید» مطالعه کنید.
پیکربندی OAuth 2.0 برای احراز هویت
برای تأیید اعتبار برنامهتان، API گوگل درایو از شما میخواهد که محدودههای OAuth را در دو مکان تعریف کنید: کنسول گوگل کلود و برنامهتان.
در کنسول گوگل کلود، شما باید محدودههایی را که برنامه شما نیاز دارد در پیکربندی صفحه رضایت OAuth آن اعلام کنید. اینها بالاترین سطح مجوزهایی هستند که برنامه شما میتواند درخواست کند. این به عنوان یک درخواست رسمی برای گوگل عمل میکند و محدودههای اعلام شده همان چیزی هستند که گوگل در صفحه رضایت به کاربران نمایش میدهد. این به کاربر اجازه میدهد تا دقیقاً بفهمد که برنامه شما درخواست دسترسی به چه دادهها و اقداماتی را دارد.
صفحه رضایت OAuth را پیکربندی کنید و محدودههایی را برای تعریف اطلاعات نمایش داده شده به کاربران و بررسیکنندگان برنامه انتخاب کنید و برنامه خود را ثبت کنید تا بتوانید بعداً آن را منتشر کنید.
در برنامه خود، هنگام شروع API، باید صریحاً محدودههای خاصی را که برای آن جلسه نیاز دارید درخواست کنید. در حالی که کنسول Google Cloud بالاترین سطح مجوزهایی را که برنامه شما مجاز به درخواست آن است تعریف میکند، کد مجوزهای واقعی را برای یک کاربر مشخص تعیین میکند. این امر به شما کمک میکند تا مطمئن شوید که برنامه فقط مجوزهای مورد نیاز برای یک کار خاص را درخواست میکند.
شما میتوانید همزمان یک یا چند محدوده OAuth را در کد برنامه خود به عنوان یک آرایه تعریف کنید.
نمونه کد زیر نحوه تعریف چندین دامنه OAuth را نشان میدهد:
جاوا
List<String> SCOPES = Arrays.asList(
DriveScopes.DRIVE_FILE,
DriveScopes.DRIVE_METADATA_READONLY
);
پایتون
SCOPES = [
"https://www.googleapis.com/auth/drive.file",
"https://www.googleapis.com/auth/drive.metadata.readonly",
]
نود جی اس
const SCOPES = [
'https://www.googleapis.com/auth/drive.file',
'https://www.googleapis.com/auth/drive.metadata.readonly'
];
برای مشاهدهی نحوهی اعلان و استفاده از محدودهها در یک نمونه کد کامل، به بخش شروع سریع مراجعه کنید.
دامنههای API درایو
برای تعریف سطح دسترسی اعطا شده به برنامه خود، باید حوزههای مجوز را شناسایی و اعلام کنید. حوزه مجوز، یک رشته URI از نوع OAuth 2.0 است که شامل نام برنامه Google Workspace، نوع دادههایی که به آنها دسترسی دارد و سطح دسترسی است. حوزهها، درخواستهای برنامه شما برای کار با دادههای Google Workspace، از جمله دادههای حساب Google کاربران، هستند.
وقتی برنامه شما نصب میشود، از کاربر خواسته میشود تا محدودههای مورد استفاده برنامه را اعتبارسنجی کند. به طور کلی، شما باید محدودهای را انتخاب کنید که بیشترین تمرکز را داشته باشد و از درخواست محدودههایی که برنامه شما به آنها نیاز ندارد، خودداری کنید. کاربران راحتتر به محدودههای محدود و واضح دسترسی میدهند.
هر زمان که ممکن است، از محدودههای غیرحساس استفاده کنید، زیرا آنها دسترسی به هر فایل را اعطا میکنند و دسترسی را به ویژگیهای خاص مورد نیاز یک برنامه محدود میکنند.
اسکوپهای غیر حساس
دامنههای API درایو زیر برای اکثر موارد استفاده توصیه میشوند:
| کد محدوده | توضیحات |
|---|---|
https://www.googleapis.com/auth/drive.appdata | دادههای پیکربندی خود برنامه را در گوگل درایو خود مشاهده و مدیریت کنید. |
https://www.googleapis.com/auth/drive.install | به برنامهها اجازه دهید به عنوان یک گزینه در منوی «باز کردن با» یا «جدید» ظاهر شوند. |
https://www.googleapis.com/auth/drive.file | فایلهای Drive جدیدی ایجاد کنید، یا فایلهای موجود را که با یک برنامه باز میکنید یا کاربر هنگام استفاده از API انتخابگر گوگل یا انتخابگر فایل برنامه با یک برنامه به اشتراک میگذارد، تغییر دهید. |
محدودههای حساس
| کد محدوده | توضیحات |
|---|---|
https://www.googleapis.com/auth/drive.apps.readonly | برنامههای مجاز به دسترسی به درایو خود را مشاهده کنید. |
دامنههای محدود
| کد محدوده | توضیحات |
|---|---|
https://www.googleapis.com/auth/drive | تمام فایلهای Drive خود را مشاهده و مدیریت کنید. |
https://www.googleapis.com/auth/drive.readonly | تمام فایلهای Drive خود را مشاهده و دانلود کنید. |
https://www.googleapis.com/auth/drive.activity | مشاهده و افزودن به سابقه فعالیت فایلهای موجود در درایو شما. |
https://www.googleapis.com/auth/drive.activity.readonly | سابقه فعالیت فایلهای موجود در درایو خود را مشاهده کنید. |
https://www.googleapis.com/auth/drive.meet.readonly | مشاهده فایلهای Drive ایجاد شده یا ویرایش شده توسط Google Meet. |
https://www.googleapis.com/auth/drive.metadata | مشاهده و مدیریت فرادادههای فایلهای موجود در درایو شما. |
https://www.googleapis.com/auth/drive.metadata.readonly | مشاهده فراداده فایلهای موجود در درایو شما. |
https://www.googleapis.com/auth/drive.scripts | رفتار اسکریپتهای Google Apps Script خود را تغییر دهید. |
محدودههای موجود در جداول قبلی، حساسیت آنها را طبق تعاریف زیر نشان میدهند:
غیر حساس : این حوزهها کوچکترین حوزه مجوز را ارائه میدهند و فقط به تأیید اولیه برنامه OAuth نیاز دارند. برای اطلاعات بیشتر، به الزامات تأیید مراجعه کنید.
حساس : این محدودهها دسترسی به دادههای خاص کاربر گوگل را که کاربران برای برنامه شما مجاز میدانند، فراهم میکنند. آنها به تأیید برنامه OAuth اضافی نیاز دارند. برای اطلاعات بیشتر، به الزامات محدوده حساس و محدود مراجعه کنید.
محدود : این حوزهها دسترسی گستردهای به دادههای کاربر گوگل ارائه میدهند و نیاز به تأیید برنامه OAuth با دامنه محدود دارند. برای اطلاعات بیشتر، به سیاست دادههای کاربر سرویسهای API گوگل و الزامات اضافی برای حوزههای خاص API مراجعه کنید. همچنین به شرایط خدمات گوگل درایو مراجعه کنید.
اگر دادههای با دامنه محدود را روی سرورها ذخیره میکنید (یا منتقل میکنید)، باید ارزیابی امنیتی را انجام دهید.
اگر برنامه شما نیاز به دسترسی به هر API گوگل دیگری دارد، میتوانید آن محدودهها را نیز اضافه کنید. برای اطلاعات بیشتر در مورد محدودههای API گوگل، به بخش «استفاده از OAuth 2.0 برای دسترسی به APIهای گوگل» مراجعه کنید.
برای اطلاعات بیشتر در مورد حوزههای خاص OAuth 2.0، به حوزههای OAuth 2.0 برای APIهای گوگل مراجعه کنید.
شرایط لازم برای دامنههای محدود
فقط انواع خاصی از برنامهها مجاز به استفاده از محدودههای محدود برای Google Drive هستند. برای واجد شرایط بودن، برنامه شما باید در یکی از دستههای زیر قرار گیرد:
پشتیبانگیری و همگامسازی : برنامههای تحت وب و مخصوص پلتفرم که همگامسازی محلی یا پشتیبانگیری خودکار از فایلهای درایو کاربران را فراهم میکنند.
بهرهوری و آموزش : برنامههایی با رابط کاربری اصلی که ممکن است شامل تعامل با فایلهای درایو، فرادادهها یا مجوزها باشند. این برنامهها شامل مدیریت وظایف، یادداشتبرداری، ارتباطات گروه کاری و برنامههای همکاری در کلاس درس میشوند.
گزارشدهی و امنیت : برنامههایی که به کاربر یا مشتری بینشی در مورد نحوه اشتراکگذاری یا دسترسی به فایلها ارائه میدهند.
برای ادامه استفاده از محدودههای محدود، باید برنامه خود را برای تأیید محدوده محدود آماده کنید .
انتقال یک برنامه موجود از محدودههای محدود
اگر برنامه Drive شما از محدودههای محدود استفاده میکند، توصیه میکنیم به یک محدوده API درایو غیر حساس مهاجرت کنید. استفاده از محدودههای غیر حساس، مانند drive.file ، به ازای هر فایل و به طور محدود به ویژگیهای خاص مورد نیاز یک برنامه دسترسی میدهد.
بسیاری از برنامهها میتوانند بدون هیچ تغییری به دسترسی به ازای هر فایل منتقل شوند.
اگر از انتخابگر فایل خودتان استفاده میکنید، توصیه میکنیم به API انتخابگر گوگل (Google Picker API) تغییر دهید که به طور کامل از محدودههای مختلف پشتیبانی میکند.
مزایای محدوده فایل درایو
استفاده از دامنه OAuth مربوط به drive.file در ترکیب با Google Picker API، هم تجربه کاربری و هم ایمنی برنامه شما را بهینه میکند.
دامنه OAuth مربوط به drive.file به کاربران اجازه میدهد تا فایلهایی را که میخواهند با برنامه شما به اشتراک بگذارند، انتخاب کنند. این به آنها کنترل و اطمینان بیشتری میدهد که دسترسی برنامه شما به فایلهایشان محدود و ایمنتر است. در مقابل، الزام دسترسی گسترده به همه فایلهای Drive میتواند کاربران را از تعامل با برنامه شما منصرف کند.
در زیر دلایلی وجود دارد که چرا باید از دامنه drive.file استفاده کنید:
قابلیت استفاده : دامنه
drive.fileبا تمام منابع Drive API REST کار میکند، به این معنی که میتوانید از آن به همان روشی که از دامنههای گستردهتر OAuth استفاده میکنید، استفاده کنید.ویژگیها : رابط برنامهنویسی کاربردی Google Picker رابط کاربری مشابهی با رابط کاربری Drive ارائه میدهد. این شامل چندین نما برای نمایش پیشنمایشها و تصاویر کوچک از فایلهای Drive و یک پنجره درونخطی و مدال است تا کاربران هرگز برنامه اصلی را ترک نکنند.
راحتی : برنامهها میتوانند هنگام استفاده از فیلتر روی فایلهای Google Picker، فیلترهایی را برای انواع خاصی از فایلهای Drive (مانند Google Docs، Sheets و photos) اعمال کنند.
تأیید سرراست : از آنجایی که
drive.fileغیرحساس است، امکان فرآیند تأیید سادهتری را فراهم میکند.
توکنهای بهروزرسانی را به طور ایمن ذخیره کنید
برای دسترسی به دادههای خصوصی با استفاده از Drive API، برنامه شما باید یک توکن دسترسی دریافت کند که دسترسی به آن API را اعطا میکند. یک توکن دسترسی واحد میتواند درجات مختلفی از دسترسی به چندین API را اعطا کند، که توسط محدودههایی که درخواست میکنید، کنترل میشود.
از آنجا که توکنهای دسترسی کوتاهمدت هستند، برای دسترسی بلندمدت به رابط برنامهنویسی کاربردی درایو باید از توکنهای تازهسازی استفاده کنید. توکن تازهسازی به برنامه شما اجازه میدهد تا توکنهای دسترسی جدید درخواست کند.
توکنهای بهروزرسانی را در یک فضای ذخیرهسازی امن و بلندمدت ذخیره کنید و تا زمانی که معتبر هستند، از آنها استفاده کنید.
برای اطلاعات بیشتر، به استفاده از OAuth 2.0 برای دسترسی به API های گوگل مراجعه کنید.
مباحث مرتبط
- برای مرور کلی در مورد احراز هویت و مجوز در Google Workspace، به «درباره احراز هویت و مجوز بیشتر بدانید» مراجعه کنید.
- برای مرور کلی در مورد احراز هویت و مجوز در Google Cloud، به مرور کلی احراز هویت مراجعه کنید.
- برای کسب اطلاعات بیشتر در مورد حسابهای سرویس، به حسابهای سرویس مراجعه کنید.
- برای کمک به عیبیابی، به بخش «رفع خطاها» مراجعه کنید.