این سند حاوی اطلاعات مجوز و احراز هویت مخصوص Google Drive API است. قبل از خواندن این سند، حتماً اطلاعات عمومی احراز هویت و مجوز Google Workspace را در اطلاعات مربوط به احراز هویت و مجوز مطالعه کنید.
OAuth 2.0 را برای مجوز پیکربندی کنید
صفحه رضایت OAuth را پیکربندی کنید و دامنه ها را انتخاب کنید تا مشخص کنید چه اطلاعاتی برای کاربران و بازبینان برنامه نمایش داده می شود و برنامه خود را ثبت کنید تا بتوانید بعداً آن را منتشر کنید.
درایو دامنه های API
برای تعریف سطح دسترسی اعطا شده به برنامه خود، باید محدوده های مجوز را شناسایی و اعلام کنید. محدوده مجوز یک رشته URI OAuth 2.0 است که حاوی نام برنامه Google Workspace، نوع داده‌هایی است که به آن دسترسی دارد و سطح دسترسی. Scopes درخواست‌های برنامه شما برای کار با داده‌های Google Workspace، از جمله داده‌های حساب Google کاربران است.
هنگامی که برنامه شما نصب می شود، از کاربر خواسته می شود تا محدوده های مورد استفاده برنامه را تأیید کند. به طور کلی، شما باید محدودترین محدوده ممکن را انتخاب کنید و از درخواست دامنه هایی که برنامه شما به آن نیاز ندارد اجتناب کنید. کاربران با سهولت بیشتری به محدوده‌های محدود و به وضوح توضیح داده شده دسترسی می‌دهند.
در صورت امکان، استفاده از دامنه‌های غیر حساس را توصیه می‌کنیم زیرا دامنه دسترسی به هر فایل را می‌دهد و دسترسی به ویژگی‌های خاص مورد نیاز یک برنامه را محدود می‌کند.
Drive API از حوزه های زیر پشتیبانی می کند:
| کد محدوده | توضیحات | استفاده |
|---|---|---|
https://www.googleapis.com/auth/drive.appdata | داده‌های پیکربندی برنامه را در Google Drive خود مشاهده و مدیریت کنید. | توصیه می شود غیر حساس |
https://www.googleapis.com/auth/drive.install | به برنامه‌ها اجازه دهید به‌عنوان یک گزینه در منوی «باز کردن با» یا «جدید» ظاهر شوند. | توصیه می شود غیر حساس |
https://www.googleapis.com/auth/drive.file | هنگام استفاده از Google Picker API یا انتخابگر فایل برنامه، فایل‌های Drive جدید ایجاد کنید یا فایل‌های موجود را که با یک برنامه باز می‌کنید یا کاربر با یک برنامه به اشتراک می‌گذارد، تغییر دهید. | توصیه می شود غیر حساس |
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 Apps Script خود را تغییر دهید. | محدود شده است |
ستون Usage در جدول بالا حساسیت هر محدوده را با توجه به تعاریف زیر نشان می دهد:
توصیه شده / غیر حساس : این محدوده ها کوچکترین دامنه دسترسی مجوز را ارائه می دهند و فقط به تأیید اولیه برنامه نیاز دارند. برای کسب اطلاعات در مورد این الزام، به الزامات تأیید مراجعه کنید.
توصیه شده / حساس : این حوزه‌ها دسترسی به داده‌های کاربر Google خاص را که توسط کاربر برای برنامه شما مجاز است، فراهم می‌کنند. از شما می‌خواهد تا از تأیید برنامه اضافی عبور کنید. برای اطلاعات در مورد این نیاز، به الزامات محدوده حساس و محدود مراجعه کنید.
محدود شده : این حوزه‌ها دسترسی گسترده‌ای به داده‌های کاربر Google را فراهم می‌کنند و از شما می‌خواهند که یک فرآیند تأیید دامنه محدود را طی کنید. برای کسب اطلاعات در مورد این الزام، به خط‌مشی داده‌های کاربر سرویس‌های Google API و الزامات اضافی برای محدوده‌های API خاص مراجعه کنید. اگر داده‌های محدوده محدود را روی سرورها ذخیره می‌کنید (یا ارسال می‌کنید)، پس باید ارزیابی امنیتی را انجام دهید.
اگر برنامه شما نیاز به دسترسی به سایر APIهای Google دارد، می‌توانید آن محدوده‌ها را نیز اضافه کنید. برای اطلاعات بیشتر در مورد دامنه های Google API، به استفاده از OAuth 2.0 برای دسترسی به Google API مراجعه کنید.
برای اطلاعات بیشتر درباره حوزه‌های خاص OAuth 2.0، به OAuth 2.0 Scopes برای Google API مراجعه کنید.
تأیید OAuth
استفاده از محدوده‌های خاص OAuth ممکن است مستلزم این باشد که برنامه شما از طریق مرکز راهنمایی تأیید برنامه OAuth ادامه یابد. سؤالات متداول برنامه OAuth را بخوانید تا مشخص کنید برنامه شما چه زمانی باید تأیید شود و چه نوع تأییدیه لازم است. همچنین به شرایط خدمات Google Drive مراجعه کنید.
چه زمانی باید از یک محدوده محدود استفاده کرد
برای Drive، فقط انواع برنامه های زیر می توانند به محدوده های محدود دسترسی داشته باشند:
- برنامه‌های مخصوص پلتفرم و وب که همگام‌سازی محلی یا پشتیبان‌گیری خودکار فایل‌های Drive کاربران را ارائه می‌کنند.
- بهره وری و برنامه های آموزشی که رابط کاربری آنها ممکن است شامل تعامل با فایل های Drive (یا فراداده یا مجوزهای آنها) باشد. برنامه های بهره وری شامل مدیریت کار، یادداشت برداری، ارتباطات گروه کاری و برنامه های همکاری کلاس درس است.
- برنامه‌های گزارش‌دهی و امنیتی که بینش کاربر یا مشتری را در مورد نحوه اشتراک‌گذاری یا دسترسی به فایل‌ها فراهم می‌کنند.
برای ادامه استفاده از محدوده‌های محدود، باید برنامه خود را برای تأیید دامنه محدود آماده کنید .
یک برنامه موجود را از محدوده های محدود منتقل کنید
اگر برنامه Drive را با استفاده از هر یک از محدوده‌های محدود توسعه داده‌اید، توصیه می‌کنیم برنامه خود را برای استفاده از یک محدوده غیر حساس منتقل کنید، زیرا دامنه دسترسی به هر فایل را می‌دهد و دسترسی به ویژگی‌های خاص مورد نیاز یک برنامه را محدود می‌کند. بسیاری از برنامه ها با دسترسی هر فایل بدون هیچ تغییری کار می کنند. اگر از انتخابگر فایل خود استفاده می کنید، توصیه می کنیم به Google Picker API بروید که به طور کامل از حوزه های مختلف پشتیبانی می کند.
مزایای حوزه drive.file OAuth
استفاده از محدوده drive.file OAuth و Google Picker API هم تجربه کاربر و هم ایمنی را برای برنامه شما بهینه می کند.
محدوده drive.file OAuth به کاربران امکان می دهد فایل هایی را که می خواهند با برنامه شما به اشتراک بگذارند انتخاب کنند. این به آنها کنترل و اطمینان بیشتری می دهد که دسترسی برنامه شما به فایل هایشان محدود و ایمن تر است. در مقابل، نیاز به دسترسی گسترده به همه فایل‌های Drive می‌تواند کاربران را از تعامل با برنامه شما منصرف کند. در زیر دلایلی وجود دارد که چرا باید از drive.file scope استفاده کنید:
قابلیت استفاده : محدوده
drive.fileبا تمام منابع Drive API REST کار می کند، به این معنی که می توانید از آن به همان روشی که از دامنه های گسترده OAuth استفاده می کنید استفاده کنید.ویژگی‌ها : Google Picker API یک رابط کاربری مشابه با رابط کاربری Drive ارائه می‌کند. این شامل چندین نما است که پیش‌نمایش‌ها و ریز عکس‌های فایل‌های Drive را نشان می‌دهد و یک پنجره درون خطی و مدال تا کاربران هرگز برنامه اصلی را ترک نکنند.
راحتی : هنگام استفاده از فیلتر در فایل‌های Google Picker، برنامه‌ها می‌توانند فیلترهایی را برای انواع فایل‌های Drive خاص (مانند Google Docs، Sheets و عکس‌ها) اعمال کنند.
همچنین، از آنجایی که drive.file غیر حساس است، فرآیند راستی‌آزمایی ساده‌تری را امکان‌پذیر می‌کند.
توکن‌های تازه‌سازی را ذخیره کنید
توکن‌های تازه‌سازی را در فضای ذخیره‌سازی امن و طولانی‌مدت ذخیره کنید و تا زمانی که معتبر هستند به استفاده از آنها ادامه دهید.