هر فایل، پوشه و درایو مشترک Google Drive دارای منابع permissions مرتبط است. هر منبع مجوز یک type خاص ( user ، group ، domain ، anyone ) و role ( owner ، organizer ، fileOrganizer ، writer ، commenter ، reader ) را مشخص میکند. برای مثال، یک فایل ممکن است مجوزی داشته باشد که به یک کاربر خاص ( type=user ) دسترسی فقط خواندنی ( role=reader ) اعطا میکند در حالی که مجوز دیگری به اعضای یک گروه خاص ( type=group ) امکان اضافه کردن نظر به یک فایل ( role=commenter ) را میدهد.
برای فهرست کامل نقشها و عملیاتهای مجاز هر کدام، به نقشها و مجوزها مراجعه کنید.
مجوزها چگونه کار می کنند
لیست های مجوز برای یک پوشه به سمت پایین منتشر می شود. همه فایلها و پوشههای فرزند مجوزها را از والدین به ارث میبرند. هر زمان که مجوزها یا سلسله مراتب تغییر می کند، انتشار به صورت بازگشتی در تمام پوشه های تودرتو انجام می شود. به عنوان مثال، اگر یک فایل در یک پوشه وجود داشته باشد و سپس آن پوشه به پوشه دیگری منتقل شود، مجوزهای موجود در پوشه جدید به فایل منتشر می شود. اگر پوشه جدید به کاربر فایل نقش جدیدی مانند "نویسنده" اعطا کند، نقش قبلی آنها را لغو می کند.
برعکس، اگر یک فایل role=writer از یک پوشه به ارث ببرد، و به پوشه دیگری منتقل شود که نقش "خواننده" را ارائه می دهد، فایل اکنون role=reader را به ارث می برد.
مجوزهای ارثی را نمی توان از یک فایل یا پوشه در درایو مشترک حذف کرد. در عوض این مجوزها باید بر روی والد مستقیم یا غیرمستقیم که از آن به ارث رسیده اند تنظیم شوند. مجوزهای موروثی را می توان از موارد زیر "My Drive" یا "Shared with me" حذف کرد.
برعکس، مجوزهای ارثی را می توان روی یک فایل یا پوشه در My Drive لغو کرد. بنابراین، اگر یک فایل role=writer از پوشه My Drive به ارث می برد، می توانید role=reader روی فایل تنظیم کنید تا سطح مجوز آن را کاهش دهید.
عملیات مجوزهای همزمان در یک فایل پشتیبانی نمی شود. فقط آخرین به روز رسانی اعمال می شود.
درک قابلیت های فایل
منبع permissions در نهایت توانایی کاربر فعلی برای انجام اقدامات روی یک فایل یا پوشه را تعیین نمی کند. در عوض، منبع files شامل مجموعهای از فیلدهای capabilities بولی است که برای نشان دادن اینکه آیا میتوان یک عمل را روی یک فایل یا پوشه انجام داد یا خیر. Google Drive API این فیلدها را بر اساس منبع permissions کاربر فعلی مرتبط با فایل یا پوشه تنظیم می کند.
به عنوان مثال، هنگامی که الکس به برنامه شما وارد می شود و سعی می کند یک فایل را به اشتراک بگذارد، نقش الکس برای مجوزهای فایل بررسی می شود. اگر نقش به آنها اجازه می دهد تا یک فایل را به اشتراک بگذارند، capabilities مربوط به فایل، مانند canShare ، نسبت به نقش تنظیم می شود. اگر الکس بخواهد فایل را به اشتراک بگذارد، برنامه شما capabilities را بررسی می کند تا مطمئن شود canShare روی true تنظیم شده است.
دریافت قابلیت های فایل
وقتی برنامه شما فایلی را باز میکند، باید قابلیتهای فایل را بررسی کند و رابط کاربری را طوری نمایش دهد که مجوزهای کاربر فعلی را منعکس کند. به عنوان مثال، اگر کاربر قابلیت canComment را روی فایل نداشته باشد، قابلیت نظر دادن باید در UI غیرفعال شود.
برای بررسی قابلیتها، متد get را روی منبع files با پارامتر مسیر fileId و پارامتر fields روی قسمت capabilities تنظیم شده است. برای اطلاعات بیشتر در مورد بازگرداندن فیلدها با استفاده از پارامتر 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 } }
سناریوهایی برای به اشتراک گذاری منابع Drive
پنج نوع مختلف سناریوهای اشتراکگذاری وجود دارد:
برای اشتراکگذاری فایل در My Drive، کاربر باید
role=writerیاrole=ownerداشته باشد.اگر مقدار بولی
writersCanShareبرای فایل رویfalseتنظیم شده باشد، کاربر بایدrole=ownerداشته باشد.اگر کاربر دارای
role=writerدسترسی موقتی داشته باشد که توسط تاریخ و زمان انقضا کنترل می شود، نمی تواند فایل را به اشتراک بگذارد. برای اطلاعات بیشتر، به تنظیم تاریخ انقضا برای محدود کردن دسترسی به فایل مراجعه کنید.
برای اشتراکگذاری یک پوشه در My Drive، کاربر باید
role=writerیاrole=ownerداشته باشد.اگر مقدار بولی
writersCanShareبرای فایل رویfalseتنظیم شده باشد، کاربر بایدrole=ownerمجاز تری داشته باشد.دسترسی موقت (با تاریخ و زمان انقضا) در پوشههای My Drive با
role=writerمجاز نیست. برای اطلاعات بیشتر، به تنظیم تاریخ انقضا برای محدود کردن دسترسی به فایل مراجعه کنید.
برای اشتراکگذاری فایل در درایو مشترک، کاربر باید
role=writer،role=fileOrganizerیاrole=organizerداشته باشد.- تنظیم
writersCanShareبرای موارد موجود در درایوهای مشترک اعمال نمی شود. طوری رفتار می شود که انگار همیشه رویtrueتنظیم شده است.
- تنظیم
برای اشتراک گذاری یک پوشه در درایو مشترک، کاربر باید
role=organizerداشته باشد.- اگر محدودیت
sharingFoldersRequiresOrganizerPermissionدر درایو مشترک رویfalseتنظیم شود، کاربران باrole=fileOrganizerمی توانند پوشه ها را در آن درایو مشترک به اشتراک بگذارند.
- اگر محدودیت
برای مدیریت عضویت درایو مشترک، کاربر باید
role=organizerداشته باشد. فقط کاربران و گروه ها می توانند عضو درایوهای مشترک باشند.
از پارامتر فیلدها استفاده کنید
اگر میخواهید فیلدهایی را برای بازگشت در پاسخ مشخص کنید، میتوانید پارامتر سیستم fields را با هر روشی از منبع permissions تنظیم کنید. اگر پارامتر fields را حذف کنید، سرور یک مجموعه پیشفرض از فیلدهای مخصوص روش را برمیگرداند. به عنوان مثال، روش list فقط فیلدهای id ، type ، kind و role را برای هر فایل برمی گرداند. برای برگرداندن فیلدهای مختلف، به بازگشت فیلدهای خاص مراجعه کنید.
یک مجوز ایجاد کنید
هنگام ایجاد مجوز، دو فیلد زیر ضروری است:
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"
}از مخاطبان هدف استفاده کنید
مخاطبان هدف گروههایی از افراد هستند - مانند بخشها یا تیمها - که میتوانید به کاربران توصیه کنید موارد خود را با آنها به اشتراک بگذارند. میتوانید کاربران را تشویق کنید که موارد را با مخاطبان خاص یا محدودتر بهجای کل سازمانتان به اشتراک بگذارند. مخاطبان هدف می توانند به شما در بهبود امنیت و حریم خصوصی داده های خود کمک کنند و اشتراک گذاری مناسب را برای کاربران آسان تر کنند. برای اطلاعات بیشتر، درباره مخاطبان هدف رجوع کنید.
برای استفاده از مخاطبان هدف:
در کنسول Google Admin، به > دایرکتوری > مخاطبان هدف بروید.
برای این کار باید با استفاده از یک حساب کاربری با امتیازات سرپرست فوق العاده وارد سیستم شوید.
در فهرست مخاطبان هدف ، روی نام مخاطب مورد نظر کلیک کنید. برای ایجاد یک مخاطب هدف، به ایجاد یک مخاطب هدف مراجعه کنید
شناسه منحصر به فرد را از URL مخاطب هدف کپی کنید:
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: حداکثر تعداد مجوز برای بازگشت در هر صفحه. اگر برای فایلهای موجود در درایو مشترک تنظیم نشود، حداکثر 100 نتیجه برگردانده میشود. اگر برای فایلهایی که در درایو مشترک نیستند تنظیم نشود، کل لیست برگردانده میشود.pageToken: یک نشانه صفحه، دریافت شده از یک تماس فهرست قبلی. این نشانه را برای بازیابی صفحه بعدی ارائه دهید.supportsAllDrives: اینکه آیا برنامه درخواست کننده هم از My Drives و هم درایوهای مشترک پشتیبانی می کند.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جدید را مشخص کنید.
شما میتوانید به فایلها یا پوشههای جداگانه در درایو مشترک مجوز بدهید، حتی اگر کاربر یا گروه قبلاً عضو آن باشد. به عنوان مثال، Alex دارای role=commenter به عنوان بخشی از عضویت خود در یک درایو مشترک است. با این حال، برنامه شما میتواند به Alex role=writer برای فایلی در درایو مشترک اعطا کند. در این حالت، چون نقش جدید مجازتر از نقشی است که از طریق عضویت آنها اعطا شده است، مجوز جدید به نقش مؤثر پرونده یا پوشه تبدیل می شود.
میتوانید بهروزرسانیها را از طریق معانی پچ اعمال کنید، به این معنی که میتوانید تغییرات جزئی در یک منبع ایجاد کنید. شما باید به صراحت فیلدهایی را که می خواهید تغییر دهید در درخواست خود تنظیم کنید. هر فیلدی که در درخواست گنجانده نشده است مقادیر موجود خود را حفظ می کند. برای اطلاعات بیشتر، کار با منابع جزئی را ببینید.
نمونه کد زیر نحوه تغییر مجوزهای یک فایل یا پوشه از 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
}
]
}چندین مجوز را با درخواست های دسته ای به روز کنید
ما قویاً توصیه می کنیم از درخواست های دسته ای برای تغییر چندین مجوز استفاده کنید.
در زیر نمونه ای از انجام اصلاح دسته ای مجوز با کتابخانه سرویس گیرنده است.
جاوا
پایتون
Node.js
PHP
دات نت
یک مجوز را حذف کنید
برای لغو دسترسی به یک فایل یا پوشه، متد delete را در منبع permissions با fileId و پارامترهای مسیر permissionId که برای حذف مجوز تنظیم شده است، فراخوانی کنید.
برای موارد موجود در «درایو من»، امکان حذف یک مجوز ارثی وجود دارد. حذف یک مجوز ارثی دسترسی به مورد و موارد فرزند را در صورت وجود لغو می کند.
برای موارد موجود در درایو مشترک، مجوزهای موروثی قابل لغو نیستند. در عوض مجوز فایل یا پوشه والد را بهروزرسانی یا حذف کنید.
روش delete همچنین برای حذف مجوزهای اعمال شده مستقیماً به فایل یا پوشه درایو مشترک استفاده می شود.
نمونه کد زیر نحوه لغو دسترسی با حذف permissionId را نشان می دهد. در صورت موفقیت آمیز بودن، بدنه پاسخ یک شی JSON خالی است. برای تأیید حذف مجوز، از روش list در منبع permissions با پارامتر مسیر fileId استفاده کنید.
درخواست کنید
DELETE https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID
برای محدود کردن دسترسی به فایل، تاریخ انقضا تعیین کنید
وقتی با افراد روی پروژهای حساس کار میکنید، ممکن است بخواهید پس از مدتی دسترسی آنها را به فایلهای خاصی در Drive محدود کنید. برای فایلهای My Drive، میتوانید تاریخ انقضا را برای محدود کردن یا حذف دسترسی به آن فایل تعیین کنید.
برای تنظیم تاریخ انقضا:
از روش
createدر منبعpermissionsاستفاده کنید و قسمتexpirationTimeرا (به همراه سایر فیلدهای مورد نیاز) تنظیم کنید. برای اطلاعات بیشتر، به ایجاد مجوز مراجعه کنید.از روش
updateدر منبعpermissionsاستفاده کنید و قسمتexpirationTimeرا (به همراه سایر فیلدهای مورد نیاز) تنظیم کنید. برای اطلاعات بیشتر، مجوزهای بهروزرسانی را ببینید.
فیلد expirationTime زمانی را نشان می دهد که مجوز با استفاده از RFC 3339 date-time منقضی می شود. زمان انقضا دارای محدودیت های زیر است:
- آنها را فقط می توان روی مجوزهای کاربر و گروه تنظیم کرد.
- زمان باید در آینده باشد.
- این زمان نمی تواند بیش از یک سال در آینده باشد.
برای اطلاعات بیشتر در مورد تاریخ انقضا، به مقالات زیر مراجعه کنید:
موضوعات مرتبط
- مدیریت پیشنهادات دسترسی معلق
- پوشه هایی با دسترسی محدود و گسترده را مدیریت کنید
- انتقال مالکیت فایل
- محافظت از محتوای فایل
- با استفاده از کلیدهای منبع به فایلهای درایو مشترک پیوند دسترسی پیدا کنید
- نقش ها و مجوزها