هر فایل، پوشه و درایو اشتراکی گوگل درایو دارای منابع permissions مرتبطی است. هر منبع، مجوز مربوط به یک type خاص ( user ، group ، domain ، anyone ) و role ( owner ، organizer ، fileOrganizer ، writer ، commenter ، reader ) را مشخص میکند. برای مثال، یک فایل ممکن است مجوزی داشته باشد که به یک کاربر خاص ( type=user ) دسترسی فقط خواندنی ( role=reader ) اعطا کند، در حالی که مجوز دیگری به اعضای یک گروه خاص ( type=group ) امکان اضافه کردن نظر به یک فایل ( role=commenter ) را بدهد.
برای فهرست کاملی از نقشها و عملیات مجاز توسط هر یک، به نقشها و مجوزها مراجعه کنید.
نحوه عملکرد مجوزها
فهرستهای مجوز برای یک پوشه به سمت پایین منتشر میشوند. همه فایلها و پوشههای فرزند، مجوزها را از والد به ارث میبرند. هر زمان که مجوزها یا سلسله مراتب تغییر کند، این انتشار به صورت بازگشتی در تمام پوشههای تو در تو رخ میدهد. به عنوان مثال، اگر فایلی در یک پوشه وجود داشته باشد و آن پوشه سپس به پوشه دیگری منتقل شود، مجوزهای پوشه جدید به فایل منتشر میشوند. اگر پوشه جدید به کاربر فایل نقش جدیدی مانند "نویسنده" اعطا کند، نقش قدیمی او را لغو میکند.
برعکس، اگر یک فایل، role=writer از یک پوشه به ارث ببرد و به پوشه دیگری که نقش "reader" را ارائه میدهد منتقل شود، اکنون فایل role=reader را به ارث میبرد.
مجوزهای ارثی را نمیتوان از یک فایل یا پوشه در یک درایو مشترک حذف کرد. در عوض، این مجوزها باید بر اساس والد مستقیم یا غیرمستقیمی که از آن به ارث رسیدهاند تنظیم شوند. مجوزهای ارثی را میتوان از موارد زیر «درایو من» یا «با من به اشتراک گذاشته شده» حذف کرد.
برعکس، مجوزهای ارثی میتوانند روی یک فایل یا پوشه در My Drive لغو شوند. بنابراین، اگر یک فایل role=writer از یک پوشه My Drive به ارث ببرد، میتوانید role=reader روی فایل تنظیم کنید تا سطح مجوز آن کاهش یابد.
عملیات مجوز همزمان روی یک فایل پشتیبانی نمیشود. فقط آخرین بهروزرسانی اعمال میشود.
درک قابلیتهای فایل
منبع permissions در نهایت توانایی کاربر فعلی برای انجام اقدامات روی یک فایل یا پوشه را تعیین نمیکند. در عوض، منبع files شامل مجموعهای از فیلدهای capabilities بولی است که برای نشان دادن اینکه آیا میتوان یک اقدام را روی یک فایل یا پوشه انجام داد یا خیر، استفاده میشود. API گوگل درایو این فیلدها را بر اساس منبع permissions کاربر فعلی مرتبط با فایل یا پوشه تنظیم میکند.
برای مثال، وقتی الکس وارد برنامه شما میشود و سعی میکند فایلی را به اشتراک بگذارد، نقش الکس برای مجوزهای مربوط به فایل بررسی میشود. اگر این نقش به او اجازه اشتراکگذاری فایل را بدهد، capabilities مربوط به فایل، مانند canShare ، نسبت به نقش تنظیم میشوند. اگر الکس بخواهد فایل را به اشتراک بگذارد، برنامه شما capabilities بررسی میکند تا مطمئن شود canShare روی true تنظیم شده است.
دریافت قابلیتهای فایل
وقتی برنامه شما فایلی را باز میکند، باید قابلیتهای فایل را بررسی کند و رابط کاربری را طوری رندر کند که مجوزهای کاربر فعلی را منعکس کند. برای مثال، اگر کاربر قابلیت canComment را روی فایل ندارد، قابلیت نظر دادن باید در رابط کاربری غیرفعال شود.
برای بررسی قابلیتها، متد get را روی منبع files با پارامتر مسیر fileId و پارامتر fields که روی فیلد capabilities تنظیم شده است، فراخوانی کنید. برای اطلاعات بیشتر در مورد برگرداندن فیلدها با استفاده از پارامتر fields ، به بخش Return specific fields مراجعه کنید.
نمونه کد زیر نحوه تأیید مجوزهای کاربر را نشان میدهد. پاسخ، فهرستی از قابلیتهای کاربر در فایل را برمیگرداند. هر قابلیت مربوط به یک اقدام جزئی است که کاربر میتواند انجام دهد. برخی از فیلدها فقط برای مواردی که در درایوهای مشترک هستند، پر میشوند.
درخواست
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=capabilitiesپاسخ
{ "capabilities": { "canAcceptOwnership": false, "canAddChildren": false, "canAddMyDriveParent": false, "canChangeCopyRequiresWriterPermission": true, "canChangeItemDownloadRestriction": true, "canChangeSecurityUpdateEnabled": false, "canChangeViewersCanCopyContent": true, "canComment": true, "canCopy": true, "canDelete": true, "canDisableInheritedPermissions": false, "canDownload": true, "canEdit": true, "canEnableInheritedPermissions": true, "canListChildren": false, "canModifyContent": true, "canModifyContentRestriction": true, "canModifyEditorContentRestriction": true, "canModifyOwnerContentRestriction": true, "canModifyLabels": true, "canMoveChildrenWithinDrive": false, "canMoveItemIntoTeamDrive": true, "canMoveItemOutOfDrive": true, "canMoveItemWithinDrive": true, "canReadLabels": true, "canReadRevisions": true, "canRemoveChildren": false, "canRemoveContentRestriction": false, "canRemoveMyDriveParent": true, "canRename": true, "canShare": true, "canTrash": true, "canUntrash": true } }
سناریوهایی برای اشتراکگذاری منابع درایو
پنج نوع سناریوی اشتراکگذاری مختلف وجود دارد:
برای اشتراکگذاری فایل در My Drive، کاربر باید
role=writerیاrole=ownerداشته باشد.اگر مقدار بولی
writersCanShareبرای فایل رویfalseتنظیم شده باشد، کاربر بایدrole=ownerداشته باشد.اگر کاربری با
role=writerدسترسی موقت داشته باشد که تابع تاریخ و زمان انقضا است، نمیتواند فایل را به اشتراک بگذارد. برای اطلاعات بیشتر، به بخش «تنظیم تاریخ انقضا برای محدود کردن دسترسی به آیتم» مراجعه کنید.
برای اشتراکگذاری یک پوشه در My Drive، کاربر باید
role=writerیاrole=ownerداشته باشد.اگر مقدار بولی
writersCanShareبرای فایل رویfalseتنظیم شده باشد، کاربر بایدrole=ownerبا مجوز بیشتر داشته باشد.دسترسی موقت (که توسط تاریخ و زمان انقضا کنترل میشود) فقط در پوشههایی با
role=readerمجاز است. برای اطلاعات بیشتر، به بخش «تنظیم تاریخ انقضا برای محدود کردن دسترسی به آیتم» مراجعه کنید.
برای به اشتراک گذاشتن یک فایل در یک درایو مشترک، کاربر باید
role=writer،role=fileOrganizerیاrole=organizerداشته باشد.- تنظیم
writersCanShareروی موارد موجود در درایوهای اشتراکی اعمال نمیشود. طوری رفتار میشود که انگار همیشه رویtrueتنظیم شده است.
- تنظیم
برای اشتراکگذاری یک پوشه در یک درایو مشترک، کاربر باید
role=organizerداشته باشد.- اگر محدودیت
sharingFoldersRequiresOrganizerPermissionدر یک درایو مشترک رویfalseتنظیم شده باشد، کاربرانی کهrole=fileOrganizerدارند میتوانند پوشهها را در آن درایو مشترک به اشتراک بگذارند.
- اگر محدودیت
برای مدیریت عضویت در درایو اشتراکی، کاربر باید
role=organizerداشته باشد. فقط کاربران و گروهها میتوانند عضو درایوهای اشتراکی باشند.
استفاده از پارامتر فیلدها
اگر میخواهید فیلدهایی را که باید در پاسخ برگردانده شوند، مشخص کنید، میتوانید پارامتر سیستمی fields را با هر متدی از منبع permissions تنظیم کنید. اگر پارامتر fields را حذف کنید، سرور مجموعهای پیشفرض از فیلدهای خاص برای متد را برمیگرداند. برای مثال، متد list فقط فیلدهای id ، type ، kind و role را برای هر فایل برمیگرداند. برای برگرداندن فیلدهای مختلف، به بخش Return specific fields مراجعه کنید.
ایجاد مجوز
دو فیلد زیر هنگام ایجاد مجوز ضروری هستند:
type:typeمحدوده مجوز (user،group،domainیاanyone) را مشخص میکند. مجوزی باtype=userبرای یک کاربر خاص اعمال میشود در حالی که مجوزی باtype=domainبرای همه افراد در یک دامنه خاص اعمال میشود.role: فیلدrole، عملیاتی را کهtypeمیتواند انجام دهد، مشخص میکند. برای مثال، مجوزی باtype=userوrole=readerبه یک کاربر خاص دسترسی فقط خواندنی به فایل یا پوشه میدهد. یا، مجوزی باtype=domainوrole=commenterبه همه افراد در دامنه اجازه میدهد تا به یک فایل نظر اضافه کنند. برای لیست کاملی از نقشها و عملیات مجاز توسط هر یک، به نقشها و مجوزها مراجعه کنید.
وقتی مجوزی ایجاد میکنید که در آن type=user یا type=group ، باید یک emailAddress نیز ارائه دهید تا کاربر یا گروه خاص را به مجوز مربوطه مرتبط کنید.
وقتی مجوزی ایجاد میکنید که در آن type=domain قرار دارد، باید یک domain نیز ارائه دهید تا یک دامنه خاص را به مجوز مرتبط کنید.
برای ایجاد مجوز:
- از متد
createروی منبعpermissionsبه همراه پارامتر مسیرfileIdبرای فایل یا پوشهی مرتبط استفاده کنید. - در بدنه درخواست،
typeوroleمشخص کنید. - اگر
type=userیاtype=group، یکemailAddressوارد کنید. اگرtype=domain، یکdomainوارد کنید.
نمونه کد زیر نحوه ایجاد یک مجوز را نشان میدهد. پاسخ، نمونهای از یک منبع permissions ، شامل permissionId اختصاص داده شده را برمیگرداند.
درخواست
POST https://www.googleapis.com/drive/v3/files/FILE_ID/permissions{ "requests": [ { "type": "user", "role": "commenter", "emailAddress": "alex@altostrat.com" } ] }
پاسخ
{
"kind": "drive#permission",
"id": "PERMISSION_ID",
"type": "user",
"role": "commenter"
}از مخاطبان هدف استفاده کنید
مخاطبان هدف، گروههایی از افراد - مانند بخشها یا تیمها - هستند که میتوانید به کاربران توصیه کنید تا موارد خود را با آنها به اشتراک بگذارند. میتوانید کاربران را تشویق کنید تا موارد را با مخاطبان خاصتر یا محدودتری به جای کل سازمان خود به اشتراک بگذارند. مخاطبان هدف میتوانند به شما در بهبود امنیت و حریم خصوصی دادههایتان کمک کنند و اشتراکگذاری مناسب را برای کاربران آسانتر کنند. برای اطلاعات بیشتر، به «درباره مخاطبان هدف» مراجعه کنید.
برای استفاده از مخاطبان هدف:
در کنسول مدیریت گوگل، به Menu > Directory > Target audience بروید.
برای این کار باید با استفاده از یک حساب کاربری با امتیازات فوق مدیر وارد سیستم شوید.
در فهرست مخاطبان هدف ، روی نام مخاطب هدف کلیک کنید. برای ایجاد مخاطب هدف، به بخش ایجاد مخاطب هدف مراجعه کنید.
شناسه منحصر به فرد را از آدرس اینترنتی مخاطب هدف کپی کنید:
https://admin.google.com/ac/targetaudiences/ ID.یک مجوز با
type=domainایجاد کنید و فیلدdomainرا رویID .audience.googledomains.comتنظیم کنید.
برای مشاهده نحوه تعامل کاربران با مخاطبان هدف، به بخش تجربه کاربری برای اشتراکگذاری لینک مراجعه کنید.
مجوز بگیرید
برای دریافت مجوز، از متد get روی منبع permissions به همراه پارامترهای مسیر fileId و permissionId استفاده کنید. اگر شناسه مجوز را نمیدانید، میتوانید با استفاده از متد list تمام مجوزها را فهرست کنید .
نمونه کد زیر نحوه دریافت مجوز بر اساس شناسه (ID) را نشان میدهد. پاسخ، نمونهای از یک منبع permissions را برمیگرداند.
درخواست
GET https://www.googleapis.com/drive/v3/files/FILE_ID/permissionsPERMISSION_ID
پاسخ
{
"kind": "drive#permissionList",
"permissions": [
{
"kind": "drive#permission",
"id": "PERMISSION_ID",
"type": "user",
"role": "commenter"
}
]
}فهرست کردن تمام مجوزها
برای فهرست کردن مجوزهای یک فایل، پوشه یا درایو مشترک، از متد list روی منبع permissions به همراه پارامتر مسیر fileId استفاده کنید.
پارامترهای پرس و جوی زیر را برای سفارشیسازی صفحهبندی یا فیلتر کردن مجوزها ارسال کنید:
pageSize: حداکثر تعداد مجوزهایی که برای هر صفحه برگردانده میشود. اگر برای فایلهای موجود در درایو مشترک تنظیم نشده باشد، حداکثر ۱۰۰ نتیجه برگردانده میشود. اگر برای فایلهایی که در درایو مشترک نیستند تنظیم نشده باشد، کل لیست برگردانده میشود.pageToken: یک توکن صفحه که از فراخوانی لیست قبلی دریافت شده است. این توکن را برای بازیابی صفحه بعدی ارائه دهید.supportsAllDrives: مشخص میکند که آیا برنامهی درخواستکننده از هر دو گزینهی My Drives و shared drive پشتیبانی میکند یا خیر.useDomainAdminAccess: برای صدور درخواست به عنوان مدیر دامنه، رویtrueتنظیم کنید. اگر پارامترfileIdبه یک درایو مشترک اشاره داشته باشد و درخواستکننده مدیر دامنهای باشد که درایو مشترک به آن تعلق دارد. برای اطلاعات بیشتر، به مدیریت درایوهای مشترک به عنوان مدیران دامنه مراجعه کنید.includePermissionsForView: مجوزهای نمای اضافی برای گنجاندن در پاسخ. فقطpublishedپشتیبانی میشود.
نمونه کد زیر نحوه دریافت همه مجوزها را نشان میدهد. پاسخ، فهرستی از مجوزهای یک فایل، پوشه یا درایو مشترک را برمیگرداند.
درخواست
GET https://www.googleapis.com/drive/v3/files/FILE_ID/permissionsپاسخ
{
"kind": "drive#permissionList",
"permissions": [
{
"id": "PERMISSION_ID",
"type": "user",
"kind": "drive#permission",
"role": "commenter"
}
]
}بهروزرسانی مجوزها
برای بهروزرسانی مجوزها در یک فایل یا پوشه، میتوانید نقش اختصاص داده شده را تغییر دهید. برای اطلاعات بیشتر در مورد یافتن منبع نقش، به بخش «تعیین منبع نقش» مراجعه کنید.
متد
updateرا روی منبعpermissionsبا پارامتر مسیرfileIdکه روی فایل، پوشه یا درایو مشترک مرتبط تنظیم شده و پارامتر مسیرpermissionIdکه روی مجوز تغییر تنظیم شده است، فراخوانی کنید. برای یافتنpermissionId، از متدlistروی منبعpermissionsبا پارامتر مسیرfileIdاستفاده کنید.در درخواست،
roleجدید را مشخص کنید.
شما میتوانید به فایلها یا پوشههای تکی در یک درایو مشترک، حتی اگر کاربر یا گروه از قبل عضو باشند، مجوز بدهید. برای مثال، الکس به عنوان بخشی از عضویت خود در یک درایو مشترک role=commenter دارد. با این حال، برنامه شما میتواند برای یک فایل در یک درایو مشترک role=writer را به الکس اعطا کند. در این حالت، از آنجایی که نقش جدید نسبت به نقشی که از طریق عضویت به او اعطا شده، مجازتر است، مجوز جدید به نقش مؤثر برای آن فایل یا پوشه تبدیل میشود.
شما میتوانید بهروزرسانیها را از طریق patch semantics اعمال کنید، به این معنی که میتوانید تغییرات جزئی در یک منبع ایجاد کنید. شما باید فیلدهایی را که قصد تغییر آنها را دارید، به طور صریح در درخواست خود تنظیم کنید. هر فیلدی که در درخواست گنجانده نشده باشد، مقادیر موجود خود را حفظ میکند. برای اطلاعات بیشتر، به کار با منابع جزئی مراجعه کنید.
نمونه کد زیر نحوه تغییر سطح دسترسی یک فایل یا پوشه از commenter به writer را نشان میدهد. پاسخ، نمونهای از یک منبع permissions را برمیگرداند.
درخواست
PATCH https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID
{
"requests": [
{
"role": "writer"
}
]
}پاسخ
{
"kind": "drive#permission",
"id": "PERMISSION_ID",
"type": "user",
"role": "writer"
}منبع نقش را تعیین کنید
برای تغییر نقش روی یک فایل یا پوشه، باید منبع نقش را بدانید. برای درایوهای اشتراکی، منبع یک نقش میتواند بر اساس عضویت در درایو اشتراکی، نقش روی یک پوشه یا نقش روی یک فایل باشد.
برای تعیین منبع نقش برای یک درایو مشترک یا موارد درون آن درایو، متد get را روی منبع permissions با پارامترهای مسیر fileId و permissionId فراخوانی کنید و پارامتر fields را روی فیلد permissionDetails تنظیم کنید.
برای یافتن permissionId ، از متد list روی منبع permissions به همراه پارامتر مسیر fileId استفاده کنید. برای دریافت فیلد permissionDetails در درخواست list ، پارامتر fields را روی permissions/permissionDetails تنظیم کنید.
این فیلد تمام مجوزهای فایل ارثی و مستقیم را برای کاربر، گروه یا دامنه فهرست میکند.
نمونه کد زیر نحوه تعیین منبع نقش را نشان میدهد. پاسخ، permissionDetails مربوط به یک منبع permissions را برمیگرداند. فیلد inheritedFrom شناسه آیتمی را که مجوز از آن به ارث رسیده است، ارائه میدهد.
درخواست
GET https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID?fields=permissionDetails&supportsAllDrives=true
پاسخ
{
"permissionDetails": [
{
"permissionType": "member",
"role": "commenter",
"inheritedFrom": "INHERITED_FROM_ID",
"inherited": true
},
{
"permissionType": "file",
"role": "writer",
"inherited": false
}
]
}بهروزرسانی مجوزهای چندگانه با درخواستهای دستهای
ما اکیداً توصیه میکنیم برای تغییر چندین مجوز از درخواستهای دستهای استفاده کنید.
در ادامه مثالی از انجام تغییر دستهای مجوزها با یک کتابخانه کلاینت آمده است.
جاوا
پایتون
نود جی اس
پی اچ پی
دات نت
حذف یک مجوز
برای لغو دسترسی به یک فایل یا پوشه، متد delete را روی منبع permissions با پارامترهای fileId و permissionId path که برای حذف مجوز تنظیم شدهاند، فراخوانی کنید.
برای موارد موجود در «My Drive»، میتوان مجوز ارثی را حذف کرد. حذف مجوز ارثی، دسترسی به آن مورد و موارد فرزند (در صورت وجود) را لغو میکند.
برای مواردی که در یک درایو مشترک قرار دارند، مجوزهای ارثی قابل لغو نیستند. در عوض، مجوز فایل یا پوشه والد را بهروزرسانی یا حذف کنید.
متد delete همچنین برای حذف مجوزهایی که مستقیماً به یک فایل یا پوشه درایو مشترک اعمال شدهاند، استفاده میشود.
نمونه کد زیر نحوه لغو دسترسی با حذف یک permissionId را نشان میدهد. در صورت موفقیت، بدنه پاسخ یک شیء JSON خالی است. برای تأیید حذف مجوز، از متد list روی منبع permissions با پارامتر مسیر fileId استفاده کنید.
درخواست
DELETE https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID
برای محدود کردن دسترسی به آیتمها، تاریخ انقضا تعیین کنید
وقتی با افرادی روی یک پروژه حساس کار میکنید، ممکن است بخواهید دسترسی آنها را به موارد خاصی در درایو پس از یک دوره زمانی محدود کنید. برای فایلها و پوشهها، میتوانید یک تاریخ انقضا تعیین کنید تا دسترسی به آن مورد را محدود یا حذف کنید.
برای تنظیم تاریخ انقضا:
از متد
createروی منبعpermissionsاستفاده کنید و فیلدexpirationTime(همراه با سایر فیلدهای مورد نیاز) را تنظیم کنید. برای اطلاعات بیشتر، به Create a permission مراجعه کنید.از متد
updateروی منبعpermissionsاستفاده کنید و فیلدexpirationTime(همراه با سایر فیلدهای مورد نیاز) را تنظیم کنید. برای اطلاعات بیشتر، به Update permissions مراجعه کنید.
فیلد expirationTime با استفاده از تاریخ و زمان RFC 3339، زمان انقضای مجوز را نشان میدهد. زمانهای انقضا دارای محدودیتهای زیر هستند:
- آنها فقط میتوانند بر اساس مجوزهای کاربر و گروه تنظیم شوند.
- زمان باید در آینده باشد.
- این زمان نمیتواند بیش از یک سال در آینده باشد.
- فقط نقش
readerواجد شرایط انقضای دسترسی به یک پوشه است.
برای اطلاعات بیشتر در مورد تاریخ انقضا، به مقالات زیر مراجعه کنید:
مباحث مرتبط
- مدیریت پیشنهادهای دسترسی در انتظار
- مدیریت پوشهها با دسترسی محدود و گسترده
- انتقال مالکیت فایل
- محافظت از محتوای فایل
- دسترسی به فایلهای درایو اشتراکگذاریشده با لینک با استفاده از کلیدهای منبع
- نقشها و مجوزها