לכל קובץ, תיקייה ואחסון שיתופי ב-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.
אי אפשר להסיר הרשאות שהועברו בירושה מקובץ או מתיקייה באחסון שיתופי. במקום זאת, צריך לשנות את ההרשאות האלה ביחידה העסקית הראשית הישירה או העקיפה שממנה הן הועברו בירושה. אפשר להסיר הרשאות שעברו בירושה מפריטים בתיקיות 'האחסון שלי' או 'קבצים ששותפו איתי'.
לעומת זאת, אפשר לבטל את ההרשאות שהתקבלו בירושה בקובץ או בתיקייה בתיקיית 'האחסון שלי'. לכן, אם קובץ מקבל role=writer מתיקייה ב'האחסון שלי', אפשר להגדיר role=reader בקובץ כדי להוריד את רמת ההרשאה שלו.
אין תמיכה בפעולות הרשאות בו-זמניות באותו קובץ. רק העדכון האחרון יחול.
הסבר על היכולות של קבצים
המשאב permissions לא קובע בסופו של דבר את היכולת של המשתמש הנוכחי לבצע פעולות בקובץ או בתיקייה.
במקום זאת, במשאב files יש אוסף של שדות בוליאניים capabilities שמשמשים לציון האם אפשר לבצע פעולה בקובץ או בתיקייה.
Google Drive API מגדיר את השדות האלה על סמך permissionsהמשאב שמשויך לקובץ או לתיקייה של המשתמש הנוכחי.
לדוגמה, כשאלכס מתחבר לאפליקציה ומנסה לשתף קובץ, המערכת בודקת את התפקיד של אלכס כדי לראות אם יש לו הרשאות לקובץ. אם התפקיד מאפשר להם לשתף קובץ, ההרשאות capabilities שקשורות לקובץ, כמו canShare, מוגדרות ביחס לתפקיד. אם אלכס רוצה לשתף את הקובץ, האפליקציה בודקת את capabilities כדי לוודא ש-canShare מוגדר ל-true.
קבלת יכולות של קבצים
כשהאפליקציה פותחת קובץ, היא צריכה לבדוק את היכולות של הקובץ ולהציג את ממשק המשתמש בהתאם להרשאות של המשתמש הנוכחי. לדוגמה, אם למשתמש אין את היכולת canComment בקובץ, האפשרות להוסיף תגובה צריכה להיות מושבתת בממשק המשתמש.
כדי לבדוק את היכולות, קוראים ל-method 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
יש חמישה תרחישי שיתוף שונים:
כדי לשתף קובץ בתיקיית 'האחסון שלי', למשתמש צריכה להיות הרשאה של
role=writerאוrole=owner.אם הערך הבוליאני
writersCanShareמוגדר ל-falseבקובץ, למשתמש צריכה להיות הרשאהrole=owner.אם למשתמש עם
role=writerיש גישה זמנית שמוגבלת על ידי תאריך ושעה של תפוגה, הוא לא יכול לשתף את הקובץ. מידע נוסף זמין במאמר הגדרת תאריך תפוגה להגבלת הגישה לפריטים.
כדי לשתף תיקייה ב'אחסון שלי', למשתמש צריכה להיות הרשאה של
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
אם רוצים לציין את השדות שיוחזרו בתגובה, אפשר להגדיר את fields פרמטר המערכת permissions בכל שיטה של המשאב. אם משמיטים את הפרמטר fields, השרת מחזיר קבוצת ברירת מחדל של שדות שספציפיים לשיטה.
לדוגמה, ה-method 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.
כדי לראות איך המשתמשים מקיימים אינטראקציה עם קהלים מטורגטים, אפשר לעיין במאמר חוויית המשתמש בשיתוף קישורים.
קבלת הרשאה
כדי לקבל הרשאה, משתמשים ב-method get במשאב permissions עם פרמטרי הנתיב fileId ו-permissionId. אם אתם לא יודעים את מזהה ההרשאה, אתם יכולים לרשום את כל ההרשאות באמצעות שיטת list.
בדוגמת הקוד הבאה אפשר לראות איך מקבלים הרשאה לפי מזהה. התגובה מחזירה מופע של מקור מידע מסוג 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"
}
]
}הצגת רשימה של כל ההרשאות
כדי לראות רשימה של ההרשאות לקובץ, לתיקייה או לאחסון שיתופי, משתמשים ב-method list במשאב permissions עם פרמטר הנתיב fileId.
כדי להתאים אישית את המספור של ההרשאות או לסנן אותן, צריך להעביר את פרמטרי השאילתה הבאים:
pageSize: מספר ההרשאות המקסימלי שיוחזר בכל דף. אם לא מוגדרים קבצים באחסון שיתופי, מוחזרות לכל היותר 100 תוצאות. אם לא מוגדרים קבצים שלא נמצאים באחסון שיתופי, כל הרשימה מוחזרת.
pageToken: טוקן של דף שהתקבל מקריאה קודמת של רשימה. צריך להזין את הטוקן הזה כדי לאחזר את הדף הבא.
supportsAllDrives: האם האפליקציה ששולחת את הבקשה תומכת גם בתיקיות 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, משתמשים ב-method listבמשאבpermissionsעם פרמטר הנתיבfileId.בבקשה, מציינים את
roleהחדש.
אתם יכולים להעניק הרשאות לקבצים או לתיקיות ספציפיים באחסון השיתופי, גם אם המשתמש או הקבוצה כבר חברים באחסון השיתופי. לדוגמה, לאלכס יש הרשאת role=commenter
כחלק מהחברות שלו באחסון השיתופי. עם זאת, האפליקציה יכולה להעניק לאלכס
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, משתמשים ב-method 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
}
]
}עדכון של כמה הרשאות באמצעות בקשות אצווה
מומלץ מאוד להשתמש בבקשות אצווה כדי לשנות כמה הרשאות.
בדוגמה הבאה מוצגת פעולה של שינוי הרשאות באצווה באמצעות ספריית לקוח.
Java
Python
Node.js
PHP
.NET
מחיקת הרשאה
כדי לבטל את הגישה לקובץ או לתיקייה, צריך להפעיל את ה-method delete במשאב permissions עם פרמטרי הנתיב fileId ו-permissionId שמוגדרים למחיקת ההרשאה.
בפריטים בתיקייה 'האחסון שלי', אפשר למחוק הרשאה שעברה בירושה. מחיקה של הרשאה שעברה בירושה מבטלת את הגישה לפריט ולפריטי צאצא, אם יש כאלה.
אי אפשר לבטל הרשאות שהועברו בירושה לגבי פריטים באחסון שיתופי. במקום זאת, צריך לעדכן או למחוק את ההרשאה בקובץ או בתיקייה ברמה שמעל.
השיטה delete משמשת גם למחיקת הרשאות שחלות ישירות על קובץ או תיקייה באחסון שיתופי.
בדוגמת הקוד הבאה אפשר לראות איך מבטלים את הגישה על ידי מחיקת permissionId. אם הפעולה בוצעה ללא שגיאות, גוף התגובה הוא אובייקט JSON ריק. כדי לוודא שההרשאה הוסרה, משתמשים ב-method list במשאב permissions עם פרמטר הנתיב fileId.
בקשה
DELETE https://www.googleapis.com/drive/v3/files/FILE_ID/permissions/PERMISSION_ID
הגדרת תאריך תפוגה כדי להגביל את הגישה לפריט
כשעובדים עם אנשים על פרויקט רגיש, לפעמים רוצים להגביל את הגישה שלהם לפריטים מסוימים ב-Drive אחרי תקופה מסוימת. לקבצים ולתיקיות אפשר להגדיר תאריך תפוגה כדי להגביל את הגישה לפריט או להסיר אותה.
כדי להגדיר את תאריך התפוגה:
משתמשים בשיטה
createבמשאבpermissionsומגדירים את השדהexpirationTime(יחד עם שאר השדות הנדרשים). מידע נוסף זמין במאמר יצירת הרשאה.משתמשים בשיטה
updateבמשאבpermissionsומגדירים את השדהexpirationTime(יחד עם שדות החובה האחרים). מידע נוסף זמין במאמר בנושא עדכון הרשאות.
השדה expirationTime מציין מתי תוקף ההרשאה יפוג, בפורמט RFC 3339 של תאריך ושעה. יש הגבלות על תוקף של קבצים:
- אפשר להגדיר אותם רק להרשאות של משתמשים וקבוצות.
- השעה חייבת להיות בעתיד.
- התאריך לא יכול להיות יותר משנה קדימה.
- רק לתפקיד
readerיש אפשרות להגדיר גישה לתיקייה שתפוג.
למידע נוסף על תאריך התפוגה, אפשר לעיין במאמרים הבאים:
נושאים קשורים
- ניהול הצעות לגישה בהמתנה
- ניהול תיקיות עם גישה מוגבלת וגישה רחבה
- העברת בעלות על קובץ
- הגנה על תוכן הקובץ
- גישה לקבצים ב-Drive ששותפו באמצעות קישור באמצעות מפתחות משאבים
- תפקידים והרשאות