هر فایل، پوشه و درایو مشترک Google Drive دارای منابع مجوزهای مرتبط است. هر منبع مجوز یک type
خاص (کاربر، گروه، دامنه، هر کسی) و role
، مانند "نظردهنده" یا "خواننده" را مشخص می کند. به عنوان مثال، یک فایل ممکن است مجوزی داشته باشد که به یک کاربر خاص ( type=user
) دسترسی فقط خواندنی ( role=reader
) می دهد در حالی که مجوز دیگری به اعضای یک گروه خاص ( type=group
) امکان اضافه کردن نظر به یک فایل را می دهد. role=commenter
).
برای فهرست کامل نقشها و عملیاتهای مجاز هر کدام، به نقشها و مجوزها مراجعه کنید.
سناریوهایی برای به اشتراک گذاری منابع Drive
پنج نوع مختلف سناریوهای اشتراکگذاری وجود دارد:
برای اشتراکگذاری فایل در My Drive، کاربر باید
role=writer
یاrole=owner
داشته باشد.اگر مقدار بولی
writersCanShare
برای فایل رویFalse
تنظیم شده باشد، کاربر بایدrole=owner
داشته باشد.اگر کاربر دارای
role=writer
دسترسی موقتی داشته باشد که توسط تاریخ و زمان انقضا کنترل می شود، نمی تواند فایل را به اشتراک بگذارد. برای اطلاعات بیشتر، به تنظیم تاریخ انقضا برای محدود کردن دسترسی به فایل مراجعه کنید.
برای اشتراکگذاری یک پوشه در My Drive، کاربر باید
role=writer
یاrole=owner
داشته باشد.اگر مقدار boolean
writersCanShare
برای فایل رویFalse
تنظیم شده باشد، کاربر بایدrole=owner
مجاز تری داشته باشد.دسترسی موقت (با تاریخ و زمان انقضا) در پوشههای My Drive با
role=writer
مجاز نیست. برای اطلاعات بیشتر، به تنظیم تاریخ انقضا برای محدود کردن دسترسی به فایل مراجعه کنید.
برای اشتراکگذاری فایل در درایو مشترک، کاربر باید
role=writer
،role=fileOrganizer
یاrole=organizer
داشته باشد.- تنظیم
writersCanShare
برای موارد موجود در درایوهای مشترک اعمال نمی شود. طوری رفتار می شود که انگار همیشه رویTrue
تنظیم شده است.
- تنظیم
برای اشتراک گذاری یک پوشه در درایو مشترک، کاربر باید
role=organizer
داشته باشد.- اگر محدودیت
sharingFoldersRequiresOrganizerPermission
در درایو مشترک رویFalse
تنظیم شده باشد، کاربران دارایrole=fileOrganizer
می توانند پوشه ها را در آن درایو مشترک به اشتراک بگذارند.
- اگر محدودیت
برای مدیریت عضویت درایو مشترک، کاربر باید
role=organizer
داشته باشد. فقط کاربران و گروه ها می توانند عضو درایوهای مشترک باشند.
برای محدود کردن دسترسی به فایل، تاریخ انقضا تعیین کنید
وقتی با افراد روی پروژهای حساس کار میکنید، ممکن است بخواهید پس از مدتی دسترسی آنها را به فایلهای خاصی در Drive محدود کنید. برای فایلهای My Drive، میتوانید تاریخ انقضا را برای محدود کردن یا حذف دسترسی به آن فایل تعیین کنید.
برای تنظیم تاریخ انقضا:
- از روش
permissions.create
استفاده کنید و فیلدpermissions.expirationTime
(به همراه سایر فیلدهای مورد نیاز) را تنظیم کنید. برای اطلاعات بیشتر، به ایجاد مجوز مراجعه کنید. - از روش
permissions.update
استفاده کنید و فیلدpermissions.expirationTime
(به همراه سایر فیلدهای مورد نیاز) را تنظیم کنید. برای اطلاعات بیشتر، به تغییر مجوزها مراجعه کنید.
فیلد expirationTime
زمانی را نشان می دهد که مجوز با استفاده از RFC 3339 date-time منقضی می شود. زمان انقضا دارای محدودیت های زیر است:
- آنها را فقط می توان روی مجوزهای کاربر و گروه تنظیم کرد.
- زمان باید در آینده باشد.
- زمان در آینده نمی تواند بیش از یک سال باشد.
برای اطلاعات بیشتر در مورد تاریخ انقضا، به مقالات زیر مراجعه کنید:
انتشار مجوز
لیست های مجوز برای یک پوشه به سمت پایین منتشر می شود و همه فایل ها و پوشه های فرزند مجوزها را از والدین به ارث می برند. هر زمان که مجوزها یا سلسله مراتب تغییر می کند، انتشار به صورت بازگشتی در تمام پوشه های تودرتو انجام می شود. به عنوان مثال، اگر یک فایل در یک پوشه وجود داشته باشد و سپس آن پوشه به پوشه دیگری منتقل شود، مجوزهای موجود در پوشه جدید به فایل منتشر می شود. اگر پوشه جدید به کاربر فایل نقش جدیدی مانند "نویسنده" بدهد، نقش قبلی آنها را لغو می کند.
برعکس، اگر یک فایل role=writer
از یک پوشه به ارث ببرد، و به پوشه دیگری منتقل شود که نقش "خواننده" را ارائه می دهد، فایل اکنون role=reader
را به ارث می برد.
مجوزهای ارثی را نمی توان از یک فایل یا پوشه در درایو مشترک حذف کرد. در عوض این مجوزها باید بر روی والد مستقیم یا غیرمستقیم که از آن به ارث رسیده اند تنظیم شوند. مجوزهای موروثی را می توان از موارد زیر "My Drive" یا "Shared with me" حذف کرد.
برعکس، مجوزهای ارثی را می توان روی یک فایل یا پوشه در My Drive لغو کرد. بنابراین، اگر یک فایل role=writer
از پوشه My Drive به ارث می برد، می توانید role=reader
روی فایل تنظیم کنید تا سطح مجوز آن را کاهش دهید.
قابلیت ها
منبع مجوزها در نهایت توانایی کاربر فعلی برای انجام اقدامات روی یک فایل یا پوشه را تعیین نمی کند. در عوض، یک منبع Files شامل مجموعهای از فیلدهای capabilities
بولی است که برای نشان دادن اینکه آیا میتوان یک عمل را روی یک فایل یا پوشه انجام داد یا خیر. Google Drive API این فیلدها را بر اساس منبع مجوزهای کاربر فعلی مرتبط با فایل یا پوشه تنظیم می کند.
به عنوان مثال، هنگامی که الکس به برنامه شما وارد می شود و سعی می کند یک فایل را به اشتراک بگذارد، نقش الکس برای مجوزهای فایل بررسی می شود. اگر نقش به آنها اجازه می دهد تا یک فایل را به اشتراک بگذارند، capabilities
مربوط به فایل، مانند canShare
، نسبت به نقش پر می شود. اگر الکس بخواهد فایل را به اشتراک بگذارد، برنامه شما capabilities
را بررسی می کند تا مطمئن شود canShare
روی true
تنظیم شده است.
برای مثالی از capabilities
بازیابی فایل، به تأیید مجوزهای کاربر مراجعه کنید.
یک مجوز ایجاد کنید
هنگام ایجاد مجوز، دو فیلد زیر ضروری است:
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
نیز برای مرتبط کردن یک دامنه خاص به مجوز ارائه دهید.
برای ایجاد مجوز:
- از روش
permissions.create
باfileId
برای فایل یا پوشه مرتبط استفاده کنید. - در بدنه درخواست،
type
وrole
مشخص کنید. - اگر
type=user
یاtype=group
، یکemailAddress
ارائه دهید. اگرtype=domain
، یکdomain
ارائه کنید.
یک مثال نشان دهید
نمونه کد زیر نحوه ایجاد مجوز را نشان می دهد. پاسخ نمونه ای از یک منبع Permission
، از جمله 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
تنظیم کنید.
برای مشاهده نحوه تعامل کاربران با مخاطبان هدف، به تجربه کاربری برای اشتراکگذاری پیوند مراجعه کنید.
تمام مجوزهای یک فایل، پوشه یا درایو مشترک را بازیابی کنید
از روش permissions.list
برای بازیابی همه مجوزها برای یک فایل، پوشه یا درایو مشترک استفاده کنید.
یک مثال نشان دهید
نمونه کد زیر نحوه دریافت همه مجوزها را نشان می دهد. پاسخ لیستی از مجوزها را برمی گرداند.
درخواست کنید
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"
}
]
}
مجوزهای کاربر را تأیید کنید
وقتی برنامه شما فایلی را باز میکند، باید قابلیتهای فایل را بررسی کند و رابط کاربری را طوری نمایش دهد که مجوزهای کاربر فعلی را منعکس کند. به عنوان مثال، اگر کاربر قابلیت canComment
روی فایل نداشته باشد، قابلیت نظر دادن باید در UI غیرفعال شود.
برای اطلاعات بیشتر در مورد capabilities
، به بخش قابلیتها در بالا مراجعه کنید.
برای بررسی قابلیتها، با fileId
و پارامتر fields
روی فیلد capabilities
با files.get
تماس بگیرید. برای اطلاعات بیشتر در مورد بازگرداندن فیلدها با استفاده از پارامتر fields
، به بازگشت فیلدهای خاص برای یک فایل مراجعه کنید.
یک مثال نشان دهید
نمونه کد زیر نحوه تأیید مجوزهای کاربر را نشان می دهد. پاسخ لیستی از قابلیت هایی را که کاربر روی فایل دارد برمی گرداند. هر قابلیت مربوط به یک اقدام دقیق است که کاربر می تواند انجام دهد. برخی از فیلدها فقط برای موارد موجود در درایوهای مشترک پر شده اند.
درخواست کنید
GET https://www.googleapis.com/drive/v3/files/FILE_ID
?fields=capabilities
پاسخ
{ "capabilities": { "canAcceptOwnership": false, "canAddChildren": false, "canAddMyDriveParent": false, "canChangeCopyRequiresWriterPermission": true, "canChangeSecurityUpdateEnabled": false, "canComment": true, "canCopy": true, "canDelete": true, "canDownload": true, "canEdit": true, "canListChildren": false, "canModifyContent": true, "canModifyContentRestriction": true, "canModifyLabels": true, "canMoveChildrenWithinDrive": false, "canMoveItemOutOfDrive": true, "canMoveItemWithinDrive": true, "canReadLabels": true, "canReadRevisions": true, "canRemoveChildren": false, "canRemoveMyDriveParent": true, "canRename": true, "canShare": true, "canTrash": true, "canUntrash": true } }
منبع نقش فایلها و پوشههای درایو مشترک را تعیین کنید
برای تغییر نقش در یک فایل یا پوشه، باید منبع نقش را بدانید. برای درایوهای مشترک، منبع یک نقش می تواند بر اساس عضویت در درایو مشترک، نقش روی یک پوشه یا نقش روی یک فایل باشد.
برای تعیین منبع نقش برای یک درایو مشترک، یا موارد درون آن درایو، با fileId
، permissionId
و پارامتر fields
که در قسمت permissionDetails
تنظیم شده است، permissions.get
را فراخوانی کنید. برای پیدا کردن permissionId
، از permissions.list
با fileId
استفاده کنید. برای واکشی فیلد permissionDetails
در درخواست permissions.list
، پارامتر fields
را روی permissions/permissionDetails
تنظیم کنید.
این فیلد تمام مجوزهای فایل ارثی و مستقیم برای کاربر، گروه یا دامنه را برمیشمارد.
یک مثال نشان دهید
نمونه کد زیر نحوه تعیین منبع نقش را نشان می دهد. پاسخ، permissionDetails
یک منبع Permission
را برمیگرداند. فیلد 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
}
]
}
تغییر مجوزها
برای تغییر مجوزهای یک فایل یا پوشه، می توانید نقش اختصاص داده شده را تغییر دهید:
با
permissionId
مجوز برای تغییر وfileId
برای فایل، پوشه یا درایو مشترک مرتبط باpermissions.update
تماس بگیرید. برای پیدا کردنpermissionId
، ازpermissions.list
باfileId
استفاده کنید.در درخواست،
role
جدید را مشخص کنید.
شما میتوانید به فایلها یا پوشههای جداگانه در درایو مشترک مجوز بدهید، حتی اگر کاربر یا گروه قبلاً عضو آن باشد. به عنوان مثال، Alex دارای role=commenter
به عنوان بخشی از عضویت خود در یک درایو مشترک است. با این حال، برنامه شما میتواند به Alex role=writer
برای فایلی در درایو مشترک اعطا کند. در این حالت، چون نقش جدید مجازتر از نقشی است که از طریق عضویت آنها اعطا شده است، مجوز جدید به نقش مؤثر پرونده یا پوشه تبدیل می شود.
یک مثال نشان دهید
نمونه کد زیر نحوه تغییر مجوزهای یک فایل یا پوشه از نظر دهنده به نویسنده را نشان می دهد. پاسخ نمونه ای از یک منبع Permission
را برمی گرداند.
درخواست کنید
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"
}
دسترسی به یک فایل یا پوشه را لغو کنید
برای لغو دسترسی به یک فایل یا پوشه، delete
با fileId
و permissionId
برای حذف مجوز فراخوانی کنید.
برای موارد موجود در «درایو من»، امکان حذف یک مجوز ارثی وجود دارد. حذف یک مجوز ارثی دسترسی به مورد و موارد فرزند را در صورت وجود لغو می کند.
برای موارد موجود در درایو مشترک، مجوزهای موروثی قابل لغو نیستند. در عوض مجوز فایل یا پوشه والد را بهروزرسانی یا لغو کنید.
عملیات delete
همچنین برای حذف مجوزهای اعمال شده مستقیماً به فایل یا پوشه درایو مشترک استفاده می شود.
یک مثال نشان دهید
نمونه کد زیر نحوه لغو دسترسی با حذف permissionId
را نشان می دهد. در صورت موفقیت آمیز بودن، بدنه پاسخ خالی است. برای تأیید حذف مجوز، از permissions.list
با fileId
استفاده کنید.
درخواست کنید
DELETE https://www.googleapis.com/drive/v3/files/FILE_ID
/permissions/PERMISSION_ID
مالکیت فایل را به حساب Google Workspace دیگری در همان سازمان منتقل کنید
مالکیت فایلهای موجود در «My Drive» را میتوان از یک حساب Google Workspace به حساب دیگری در همان سازمان منتقل کرد. سازمانی که دارای یک درایو مشترک است، مالک فایلهای درون آن است. بنابراین، انتقال مالکیت برای فایلها و پوشهها در درایوهای مشترک پشتیبانی نمیشود. سازماندهندگان یک درایو مشترک میتوانند موارد را از آن درایو مشترک به «درایو من» خود منتقل کنند که مالکیت را به آنها منتقل میکند.
برای انتقال مالکیت یک فایل در My Drive، یکی از موارد زیر را انجام دهید:
یک مجوز فایل ایجاد کنید که به یک کاربر خاص (
type=user
) دسترسی مالک (role=owner
) را بدهد.مجوز یک فایل موجود را با
role=owner
به روز کنید و مالکیت را به کاربر مشخص شده منتقل کنید (transferOwnership=true
).
انتقال مالکیت فایل از یک حساب مصرف کننده به حساب دیگر
مالکیت فایل ها را می توان بین یک حساب مصرف کننده به حساب دیگر منتقل کرد. با این حال، Drive مالکیت یک فایل را بین دو حساب مصرفکننده منتقل نمیکند تا زمانی که مالک جدید بالقوه صریحاً با این انتقال موافقت کند. برای انتقال مالکیت فایل از یک حساب مصرف کننده به حساب دیگر:
مالک فعلی با ایجاد یا بهروزرسانی مجوز فایل مالک جدید، انتقال مالکیت را آغاز میکند. مجوز باید شامل این تنظیمات باشد:
role=writer
،type=user
وpendingOwner=true
. اگر مالک جدید در حال ایجاد مجوز برای مالک احتمالی باشد، یک اعلان ایمیلی به مالک جدید احتمالی ارسال میشود که نشان میدهد از آنها خواسته میشود مالکیت فایل را به عهده بگیرند.مالک جدید با ایجاد یا بهروزرسانی مجوز فایل خود، درخواست انتقال مالکیت را میپذیرد. مجوز باید شامل این تنظیمات باشد:
role=owner
وtransferOwnership=true
. اگر مالک جدید در حال ایجاد مجوز جدید باشد، یک اعلان ایمیلی به مالک قبلی ارسال میشود که نشان میدهد مالکیت منتقل شده است.
هنگامی که یک فایل منتقل می شود، نقش مالک قبلی به writer
کاهش می یابد.
چندین مجوز را با درخواست های دسته ای تغییر دهید
ما قویاً توصیه می کنیم از درخواست های دسته ای برای تغییر چندین مجوز استفاده کنید.
در زیر نمونه ای از انجام اصلاح دسته ای مجوز با کتابخانه سرویس گیرنده است.