هر فایل، پوشه و درایو اشتراکی گوگل درایو دارای منابع 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را دارد. - ارزیابی مجدد در هنگام انتقال : انتقال یک آیتم به یک پوشه والد جدید، مجوزهای والد جدید را دوباره ارزیابی و برای آیتم و فرزندانش اعمال میکند.
پیوندهای فایل و کنترل دسترسی
وقتی یک فایل یا پوشه را با یک کاربر یا گروه خاص به اشتراک میگذارید، URL دسترسی به آن آیتم تغییر نمیکند و برای هر کاربر یک لینک منحصر به فرد ایجاد نمیشود. در عوض، آن آیتم یک لینک ثابت و واحد بر اساس fileId خود دارد.
درایو با ارزیابی ACL مربوط به آیتم، دسترسی را کنترل میکند. وقتی کاربری سعی در باز کردن لینکی دارد، درایو هویت احراز هویت شده او را با ACL مطابقت میدهد. اگر مجوزی لغو شود یا به تاریخ انقضای خود برسد، کاربر از ACL حذف میشود. اگر کاربر دوباره سعی در بازدید از لینک کند، درایو دسترسی را رد میکند.
درک قابلیتهای فایل
منبع permissions مشخص میکند چه کسی دسترسی دارد (ACL)، اما مستقیماً نشان نمیدهد که آیا کاربر فعلی میتواند یک عمل خاص را در رابط کاربری برنامه شما انجام دهد یا خیر.
در عوض، منبع files شامل مجموعهای از فیلدهای capabilities بولی (مانند canComment ، canShare یا canDelete ) است که API گوگل درایو به صورت پویا بر اساس نقش و تنظیمات آیتم کاربر محاسبه میکند.
دریافت قابلیتهای فایل
هنگام رندر کردن رابط کاربری برنامهتان، به جای تجزیهی مستقیم مجوزها، files.capabilities را بررسی کنید:
- متد
files.getرا باfields=capabilitiesفراخوانی کنید. برای اطلاعات بیشتر، به بخش Return specific fields مراجعه کنید. - از پرچمهای بولی برگردانده شده برای فعال یا غیرفعال کردن اقدامات مربوطه در رابط کاربری خود استفاده کنید. برای مثال، اگر
canCommentبرابر باfalseباشد، کامنتگذاری را غیرفعال کنید.
سناریوهایی برای اشتراکگذاری منابع درایو
جدول زیر نقشها و شرایط لازم برای اشتراکگذاری منابع Drive در مکانها و انواع مختلف اقلام را نشان میدهد:
| مکان | مورد | نقشهای مورد نیاز | محدودیتهای کلیدی |
|---|---|---|---|
| درایو من | فایل یا پوشه | owner یا writer | اگر writersCanShare=false به owner نیاز دارد.انقضای دسترسی به پوشهها نیاز به reader دارد (به تنظیم تاریخ انقضا مراجعه کنید). |
| درایو مشترک | فایل | organizer ، fileOrganizer یا writer | writersCanShare همیشه به عنوان true در نظر گرفته میشود. |
| درایو مشترک | پوشه | organizer | fileOrganizer همچنین میتواند در صورتی که sharingFoldersRequiresOrganizerPermission false داشته باشد، به اشتراک گذاشته شود. |
| درایو مشترک | عضویت | organizer | فقط برای user یا group (نه دامنهها) اعمال میشود. |
مدیریت مجوزها
جدول زیر خلاصهای از متدهای موجود در منبع permissions را نشان میدهد:
| روش | نقطه پایانی API | پارامترهای کلیدی | مرجع |
|---|---|---|---|
| ایجاد کردن | POST https://www.googleapis.com/drive/v3/files/{fileId}/permissions | role ، type ، emailAddress یا domain | permissions.create |
| دریافت | GET https://www.googleapis.com/drive/v3/files/{fileId}/permissions/{permissionId} | fields | permissions.get |
| فهرست | GET https://www.googleapis.com/drive/v3/files/{fileId}/permissions | pageSize ، supportsAllDrives ، pageToken | permissions.list |
| بهروزرسانی | PATCH https://www.googleapis.com/drive/v3/files/{fileId}/permissions/{permissionId} | role ، allowFileDiscovery | permissions.update |
| حذف | DELETE https://www.googleapis.com/drive/v3/files/{fileId}/permissions/{permissionId} | supportsAllDrives | permissions.delete |
ایجاد مجوز
برای اشتراکگذاری یک فایل، پوشه یا درایو مشترک، متد create را روی منبع permissions با fileId فراخوانی کنید. ایجاد یک مجوز، یک ورودی ACL جدید به آیتم اضافه میکند و یک permissionId اختصاص داده شده را برمیگرداند.
در بدنه درخواست، فیلدهای زیر را ارائه دهید:
-
role: سطح دسترسی برای اعطا (به عنوان مثال،reader،commenterیاwriter). برای مشاهده لیست کامل، به نقشها و مجوزها مراجعه کنید. -
type: محدودهی اعطاکننده (user،group،domainیاanyone). - شناسه گیرنده (الزامی بر اساس
type):-
emailAddress: وقتیtypeuserیاgroupباشد، الزامی است. -
domain: وقتیtypedomainباشد، الزامی است.
-
نمونه کد زیر نحوه ایجاد یک مجوز را نشان میدهد. پاسخ، نمونهای از یک منبع permissions ، شامل permissionId اختصاص داده شده را برمیگرداند.
درخواست
POST https://www.googleapis.com/drive/v3/files/FILE_ID/permissions{ "role": "commenter", "type": "user", "emailAddress": "alex@altostrat.com" }
پاسخ
{
"kind": "drive#permission",
"id": "PERMISSION_ID",
"type": "user",
"role": "commenter"
}اشتراک گذاری با مخاطبان هدف
مخاطبان هدف، گروههایی از افراد - مانند بخشها یا تیمها - هستند که میتوانید به کاربران توصیه کنید تا موارد خود را با آنها به اشتراک بگذارند. میتوانید کاربران را تشویق کنید تا موارد را با مخاطبان خاصتر یا محدودتری به جای کل سازمان خود به اشتراک بگذارند. مخاطبان هدف میتوانند به شما در بهبود امنیت و حریم خصوصی دادههایتان کمک کنند و اشتراکگذاری مناسب را برای کاربران آسانتر کنند.
برای اشتراکگذاری با مخاطب هدف، type=domain تنظیم کنید و domain روی <TARGET_AUDIENCE_ID>.audience.googledomains.com تنظیم کنید. برای جزئیات بیشتر در مورد مکانیابی یا ایجاد مخاطبان هدف در کنسول مدیریت گوگل، به «درباره مخاطبان هدف» مراجعه کنید.
برای مشاهده نحوه تعامل کاربران با مخاطبان هدف، به بخش تجربه کاربری برای اشتراکگذاری لینک مراجعه کنید.
مجوز بگیرید
برای دریافت مجوز، متد get را روی منبع permissions با پارامترهای مسیر fileId و permissionId فراخوانی کنید. اگر شناسه مجوز را نمیدانید، ابتدا همه مجوزها را فهرست کنید .
فهرست مجوزها
برای فهرست کردن مجوزهای یک فایل، پوشه یا درایو مشترک، متد list را روی منبع permissions با پارامتر مسیر fileId مورد نیاز فراخوانی کنید.
شما میتوانید هر یک از پارامترهای اختیاری کوئری زیر را برای صفحهبندی یا فیلتر کردن پاسخ وارد کنید:
pageSize(اختیاری): حداکثر تعداد مجوزهایی که برای هر صفحه برگردانده میشود. اگر برای فایلهای موجود در درایو مشترک تنظیم نشود، حداکثر ۱۰۰ نتیجه برگردانده میشود. اگر برای فایلهایی که در درایو مشترک نیستند تنظیم نشود، کل لیست برگردانده میشود.pageToken(اختیاری): یک توکن صفحه از فراخوانی لیست قبلی برای بازیابی صفحه بعدی.supportsAllDrives(اختیاری): اینکه آیا برنامه درخواستکننده از هر دو درایو My Drive و shared drive پشتیبانی میکند یا خیر.useDomainAdminAccess(اختیاری): برای صدور درخواست به عنوان مدیر دامنه، رویtrueتنظیم کنید. اگر پارامترfileIdبه یک درایو مشترک اشاره کند و درخواستکننده مدیر دامنهای باشد که درایو مشترک به آن تعلق دارد، به درخواستکننده دسترسی داده میشود. برای اطلاعات بیشتر، به مدیریت درایوهای مشترک به عنوان مدیران دامنه مراجعه کنید.includePermissionsForView(اختیاری): مجوزهای نمای اضافی برای گنجاندن در پاسخ. فقطpublishedپشتیبانی میشود.fields(اختیاری): فیلدهای خاصی که باید در پاسخ برگردانده شوند. به طور پیشفرض،listفقطid،type،kindوroleبرمیگرداند. برای برگرداندن فیلدهای اضافی (مانندpermissionDetails)، آنها را با استفاده از این پارامتر مشخص کنید. برای اطلاعات بیشتر، به بخش Return specific fields مراجعه کنید.
منبع نقش را تعیین کنید
برای تغییر نقش روی یک فایل یا پوشه، باید منبع نقش را بدانید. برای درایوهای اشتراکی، منبع یک نقش میتواند بر اساس عضویت در درایو اشتراکی، نقش روی یک پوشه یا نقش روی یک فایل باشد.
برای تعیین منبع نقش برای یک درایو مشترک یا موارد درون آن درایو، متد 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
}
]
}بهروزرسانی یک مجوز
برای بهروزرسانی مجوزها در یک فایل یا پوشه، میتوانید نقش اختصاص داده شده را تغییر دهید. برای اطلاعات بیشتر در مورد یافتن منبع نقش، به بخش «تعیین منبع نقش» مراجعه کنید.
متد
updateروی منبعpermissionsبا پارامتر مسیرfileIdکه روی فایل، پوشه یا درایو مشترک مرتبط تنظیم شده و پارامتر مسیرpermissionIdکه روی مجوز تغییر تنظیم شده است، فراخوانی کنید. برای یافتنpermissionId، از متدlistروی منبعpermissionsبا پارامتر مسیرfileIdاستفاده کنید.در درخواست،
roleجدید را مشخص کنید.
شما میتوانید به فایلها یا پوشههای تکی در یک درایو مشترک، حتی اگر کاربر یا گروه از قبل عضو باشند، مجوز بدهید. برای مثال، الکس به عنوان بخشی از عضویت خود در یک درایو مشترک role=commenter دارد. با این حال، برنامه شما میتواند برای یک فایل در یک درایو مشترک role=writer را به الکس اعطا کند. در این حالت، از آنجایی که نقش جدید نسبت به نقشی که از طریق عضویت به او اعطا شده، مجازتر است، مجوز جدید به نقش مؤثر برای آن فایل یا پوشه تبدیل میشود.
شما میتوانید بهروزرسانیها را از طریق patch semantics اعمال کنید، به این معنی که میتوانید تغییرات جزئی در یک منبع ایجاد کنید. شما باید فیلدهایی را که قصد تغییر آنها را دارید، به طور صریح در درخواست خود تنظیم کنید. هر فیلدی که در درخواست گنجانده نشده باشد، مقادیر موجود خود را حفظ میکند. برای اطلاعات بیشتر، به کار با منابع جزئی مراجعه کنید.
علاوه بر تغییر نقشها، میتوانید قابلیت کشف یک مورد را نیز تغییر دهید، زمانی که type مجوز domain یا anyone باشد. برای اینکه یک فایل مشترک قابل جستجو یا از فهرست خارج شود، فیلد بولی allowFileDiscovery را در درخواست وصله خود وارد کنید. تنظیم این مقدار روی true به مورد اجازه میدهد تا در نتایج جستجو برای مخاطبان مشخص شده ظاهر شود، حتی اگر لینک مستقیم به آنها داده نشده باشد. برای تغییر این تنظیم، نیازی به حذف و ایجاد مجدد مجوز ندارید.
نمونه کد زیر نحوه تغییر سطح دسترسی یک فایل یا پوشه از commenter به writer را نشان میدهد. پاسخ، نمونهای از یک منبع permissions را برمیگرداند.
درخواست
PATCH https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID
{
"role": "writer"
}پاسخ
{
"kind": "drive#permission",
"id": "PERMISSION_ID",
"type": "user",
"role": "writer"
}بهروزرسانی مجوزهای چندگانه با درخواستهای دستهای
تغییرات همزمان مجوزها در یک فایل، پوشه یا درایو مشترک پشتیبانی نمیشوند. این محدودیت برای همه عملیات تغییر مجوز (مانند بهروزرسانی یا حذف) اعمال میشود، صرف نظر از اینکه آیا مجوزها را برای یک گیرنده یا گیرندههای مختلف تغییر میدهید، و اینکه آیا درخواستها از یک برنامه واحد یا چندین کاربر سرچشمه میگیرند.
درایو مجوزهای یک آیتم را به عنوان یک ACL واحد ارزیابی و بهروزرسانی میکند. عملیات همزمان باعث ایجاد شرایط رقابتی میشوند که در آن "آخرین نوشتن برنده میشود" که میتواند به طور خاموش تغییرات مجوز را بازنویسی کند یا خطاهای sharingRateLimitExceeded را ایجاد کند.
برای جلوگیری از تداخل، تغییرات مجوزها را روی یک آیتم به صورت متوالی اجرا کنید، یا از درخواستهای دستهای برای تغییر چندین مجوز در یک درخواست واحد استفاده کنید.
در ادامه مثالی از انجام تغییر دستهای مجوزها با یک کتابخانه کلاینت آمده است.
جاوا
پایتون
نود جی اس
پی اچ پی
دات نت
حذف یک مجوز
برای لغو دسترسی به یک فایل یا پوشه، متد delete را روی منبع permissions با پارامترهای مسیر fileId و permissionId فراخوانی کنید.
مجوزهای ارثی را نمیتوان مستقیماً روی موارد فرزند لغو کرد. در عوض، مجوز پوشه والد را بهروزرسانی یا حذف کنید (یا از تنظیم دسترسی محدود استفاده کنید).
توجه داشته باشید که حذف دسترسی کاربر از یک آیتم والد، فقط مجوزهای به ارث رسیده از آن والد را لغو میکند. اگر به کاربر مجوزهای مستقیم روی یک آیتم فرزند نیز اعطا شده باشد، آن دسترسی مستقیم همچنان پابرجاست. برای تأیید حذف یک مجوز، list با fileId فراخوانی کنید.
تاریخ انقضا را تعیین کنید
برای اعطای دسترسی موقت به یک فایل یا پوشه، هنگام فراخوانی متدهای create یا update ، فیلد expirationTime ( RFC 3339 date-time ) را تنظیم کنید.
زمانهای انقضا محدودیتهای زیر را دارند:
- فقط میتوان مجوزهای
userوgroupرا تنظیم کرد (نهdomainیاanyone). - زمان باید مربوط به آینده باشد، حداکثر تا یک سال.
- برای پوشهها، دسترسی موقت فقط با نقش
readerپشتیبانی میشود.
مباحث مرتبط
- مدیریت پیشنهادهای دسترسی در انتظار
- مدیریت پوشهها با دسترسی محدود و گسترده
- انتقال مالکیت فایل
- محافظت از محتوای فایل
- دسترسی به فایلهای درایو اشتراکگذاریشده با لینک با استفاده از کلیدهای منبع
- نقشها و مجوزها