שיתוף קבצים, תיקיות ו-Drive

לכל קובץ, תיקייה ואחסון שיתופי ב-Google Drive יש משאבי permissions משויכים. כל משאב מזהה את ההרשאה עבור type ספציפי (user,‏ group,‏ domain,‏ anyone) וrole (owner,‏ organizer,‏ fileOrganizer,‏ writer,‏ commenter,‏ reader). לדוגמה, יכול להיות שלקובץ מסוים יש הרשאה שמעניקה למשתמש ספציפי (type=user) גישה לקריאה בלבד (role=reader), והרשאה אחרת שמעניקה לחברים בקבוצה ספציפית (type=group) את האפשרות להוסיף הערות לקובץ (role=commenter).

רשימה מלאה של התפקידים והפעולות שמותרות בכל אחד מהם מופיעה במאמר תפקידים והרשאות.

הערה: הרשימה של כל משאבי ההרשאות שמשויכים לקובץ, לתיקייה או לאחסון שיתופי נקראת רשימה של בקרת גישה (ACL).

איך הרשאות פועלות

רשימות ההרשאות של תיקייה מועברות כלפי מטה. כל הקבצים והתיקיות שמוכלים בתיקייה מקבלים בירושה את ההרשאות של תיקיית האב. בכל פעם שמשנים את ההרשאות או את ההיררכיה, ההעברה מתבצעת באופן רקורסיבי בכל התיקיות המקוננות. לדוגמה, אם קובץ נמצא בתיקייה והתיקייה הזו מועברת לתיקייה אחרת, ההרשאות של התיקייה החדשה מועברות לקובץ. אם התיקייה החדשה מעניקה למשתמש הקובץ תפקיד חדש, כמו 'בעל הרשאת כתיבה', התפקיד החדש יחליף את התפקיד הקודם.

לעומת זאת, אם קובץ מקבל בירושה את role=writer מתיקייה, והוא מועבר לתיקייה אחרת שבה יש תפקיד 'קריאה', הקובץ מקבל בירושה את role=reader.

אי אפשר להסיר או לצמצם הרשאות שהועברו בירושה לגבי פריט כלשהו. במקום זאת, צריך לשנות את ההרשאות האלה בתיקייה הראשית שבה הן נוצרו, או להפעיל את ההגדרה של גישה מוגבלת בתיקייה בהיררכיה.

אפשר להגדיל את ההרשאות שעברו בירושה בפריט. אם ההרשאה של הצאצא גדולה יותר, שינוי ההרשאה של ההורה לא ישפיע על ההרשאה של הצאצא, אלא אם ההרשאה החדשה של ההורה גדולה יותר מההרשאה של הצאצא.

אין תמיכה בפעולות הרשאות בו-זמניות באותו קובץ. רק העדכון האחרון יחול.

איך פועלים קישורים לקבצים ובקרת גישה

כשמשתפים קובץ או תיקייה עם משתמש או קבוצה ספציפיים, כתובת ה-URL לגישה לפריט לא משתנה, ולא נוצר קישור ייחודי לכל משתמש. במקום זאת, לפריט יש קישור קבוע יחיד שמבוסס על מאפיין fileId.

כדי לקבוע את הגישה, מערכת Drive בודקת את רשימת ה-ACL של הפריט. כשמשתמש מנסה לפתוח קישור, Drive מאמת את הזהות המאומתת שלו מול רשימת בקרת הגישה. אם הרשאה מבוטלת או מגיעה לתאריך התפוגה שלה, המשתמש מוסר מרשימת ה-ACL. אם המשתמש ינסה להיכנס שוב לקישור, הגישה ל-Drive תיחסם.

הסבר על היכולות של קבצים

המשאב 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

יש חמישה תרחישי שיתוף שונים:

1. כדי לשתף קובץ בתיקיית 'האחסון שלי', למשתמש צריכה להיות הרשאה של role=writer או role=owner.

   • אם הערך הבוליאני writersCanShare מוגדר ל-false בקובץ, למשתמש צריכה להיות הרשאה role=owner.

   • אם למשתמש עם role=writer יש גישה זמנית שמוגבלת על ידי תאריך ושעה של תפוגה, הוא לא יכול לשתף את הקובץ. מידע נוסף מופיע במאמר הגדרת תאריך תפוגה להגבלת הגישה לפריט.

2. כדי לשתף תיקייה בתיקיית 'האחסון שלי', למשתמש צריכה להיות הרשאה של role=writer או role=owner.

   • אם הערך הבוליאני writersCanShare מוגדר כ-false בקובץ, למשתמש צריכה להיות הרשאת role=owner.

   • גישה זמנית (שכפופה לתאריך ושעה של תפוגה) מותרת רק בתיקיות עם role=reader. מידע נוסף מופיע במאמר בנושא הגדרת תאריך תפוגה להגבלת הגישה לפריט.

3. כדי לשתף קובץ בתיקייה באחסון השיתופי, למשתמש צריכה להיות הרשאה של role=writer, role=fileOrganizer או role=organizer.

   • ההגדרה writersCanShare לא חלה על פריטים בתיקיות אחסון שיתופי. היא נחשבת כאילו היא תמיד מוגדרת לערך true.

4. כדי לשתף תיקייה באחסון שיתופי, למשתמש צריכה להיות הרשאה של role=organizer.

   • אם ההגבלה על האחסון השיתופי sharingFoldersRequiresOrganizerPermission מוגדרת כ-false, משתמשים עם role=fileOrganizer יכולים לשתף תיקיות באחסון השיתופי הזה.

5. כדי לנהל את החברות באחסון השיתופי, למשתמש צריכה להיות הרשאה של 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 כדי לקשר דומיין ספציפי להרשאה.

כדי ליצור הרשאה:

1. משתמשים בשיטה create במשאב permissions עם פרמטר הנתיב fileId של הקובץ או התיקייה המשויכים.
2. בגוף הבקשה, מציינים את type ואת role.
3. אם בוחרים באפשרות 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": "[e-mail]"
    }
  ]
}

תשובה

{
    "kind": "drive#permission",
    "id": "PERMISSION_ID",
    "type": "user",
    "role": "commenter"
}

שימוש בקהלים לטירגוט

קהלי יעד הם קבוצות של אנשים – כמו מחלקות או צוותים – שאפשר להמליץ למשתמשים לשתף איתם את הפריטים שלהם. אתם יכולים לעודד משתמשים לשתף פריטים עם קהל ספציפי או מוגבל יותר, במקום עם כל הארגון. קהלים לטירגוט יכולים לעזור לכם לשפר את האבטחה והפרטיות של הנתונים, ולאפשר למשתמשים לשתף אותם בצורה מתאימה. מידע נוסף זמין במאמר מידע על קהלים ממוקדים.

כדי להשתמש בקבוצות משתמשי יעד:

1. במסוף Google Admin, לוחצים על סמל התפריט > ספרייה > קהלים ממוקדים.

   מעבר אל משתמשי יעד

   כדי לבצע את המשימה הזו, אתם צריכים להיכנס לחשבון עם הרשאות סופר-אדמין.

2. ברשימת קהלי היעד, לוחצים על שם קהל היעד. כדי ליצור קהל יעד, אפשר לעיין במאמר בנושא יצירה של קהל יעד

3. מעתיקים את המזהה הייחודי מכתובת ה-URL של קהל היעד: https://admin.google.com/ac/targetaudiences/ID.

4. יוצרים הרשאה עם 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"
    }
  ]
}

עדכון ההרשאות

כדי לעדכן את ההרשאות בקובץ או בתיקייה, אפשר לשנות את התפקיד שהוקצה. מידע נוסף על איתור המקור של התפקיד זמין במאמר קביעת המקור של התפקיד.

1. קוראים לשיטה update במשאב permissions עם פרמטר הנתיב fileId שמוגדר לקובץ, לתיקייה או לאחסון השיתופי המשויכים, ופרמטר הנתיב permissionId שמוגדר להרשאה לשינוי. כדי למצוא את permissionId, משתמשים ב-method ‏list במשאב permissions עם פרמטר הנתיב fileId.

   הערה: התו permissionId מייצג את המשתמש או הקבוצה שלהם ניתנת ההרשאה, כמו [e-mail] או [e-mail]. ההרשאה permissionId נשארת זהה עבור המשתמש או הקבוצה בכל הקבצים, התיקיות ותיקיות האחסון השיתופי.

2. בבקשה, מציינים את role החדש.

אתם יכולים להעניק הרשאות לקבצים או לתיקיות ספציפיים באחסון שיתופי, גם אם המשתמש או הקבוצה כבר חברים באחסון השיתופי. לדוגמה, לאלכס יש הרשאת role=commenter כחלק מהחברות שלו באחסון השיתופי. עם זאת, האפליקציה יכולה להעניק לאלכס role=writer הרשאת גישה לקובץ באחסון השיתופי. במקרה הזה, מכיוון שהתפקיד החדש כולל יותר הרשאות מהתפקיד שניתן דרך החברות, ההרשאה החדשה הופכת לתפקיד בפועל בקובץ או בתיקייה.

אפשר להחיל עדכונים באמצעות סמנטיקה של תיקון, כלומר אפשר לבצע שינויים חלקיים במשאב. צריך להגדיר במפורש בבקשה את השדות שרוצים לשנות. כל השדות שלא נכללים בבקשה שומרים על הערכים הקיימים שלהם. מידע נוסף מופיע במאמר עבודה עם משאבים חלקיים.

בדוגמת הקוד הבאה אפשר לראות איך משנים את ההרשאות בקובץ או בתיקייה מ-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"
}

קביעת מקור התפקיד

כדי לשנות את התפקיד בקובץ או בתיקייה, צריך לדעת מה המקור של התפקיד. בתיקיות אחסון שיתופי, המקור של התפקיד יכול להיות חברות באחסון השיתופי, התפקיד בתיקייה או התפקיד בקובץ.

כדי לקבוע את מקור התפקיד בתיקיית אחסון שיתופי או בפריטים בתיקייה הזו, צריך להפעיל את השיטה 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
    }
  ]
}

עדכון של כמה הרשאות באמצעות בקשות אצווה

מומלץ מאוד להשתמש בבקשות אצווה כדי לשנות כמה הרשאות.

בדוגמה הבאה מוצגת פעולה של שינוי הרשאות באצווה באמצעות ספריית לקוח.

הערה: אם אתם משתמשים בגרסה ישנה יותר של Drive API‏ (v2), תוכלו למצוא דוגמאות לקוד ב-GitHub. כך עוברים ל-Drive API v3.

Java

drive/snippets/drive_v3/src/main/java/ShareFile.java

הצגת הקוד ב-GitHub

import com.google.api.client.googleapis.batch.BatchRequest;
import com.google.api.client.googleapis.batch.json.JsonBatchCallback;
import com.google.api.client.googleapis.json.GoogleJsonError;
import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.http.HttpHeaders;
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.drive.Drive;
import com.google.api.services.drive.DriveScopes;
import com.google.api.services.drive.model.Permission;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

/* Class to demonstrate use-case of modify permissions. */
public class ShareFile {

  /**
   * Batch permission modification.
   * realFileId file Id.
   * realUser User Id.
   * realDomain Domain of the user ID.
   *
   * @return list of modified permissions if successful, {@code null} otherwise.
   * @throws IOException if service account credentials file not found.
   */
  public static List<String> shareFile(String realFileId, String realUser, String realDomain)
      throws IOException {
        /* Load pre-authorized user credentials from the environment.
         TODO(developer) - See https://developers.google.com/identity for
         guides on implementing OAuth2 for your application.application*/
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList(DriveScopes.DRIVE_FILE));
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(
        credentials);

    // Build a new authorized API client service.
    Drive service = new Drive.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Drive samples")
        .build();

    final List<String> ids = new ArrayList<String>();


    JsonBatchCallback<Permission> callback = new JsonBatchCallback<Permission>() {
      @Override
      public void onFailure(GoogleJsonError e,
                            HttpHeaders responseHeaders)
          throws IOException {
        // Handle error
        System.err.println(e.getMessage());
      }

      @Override
      public void onSuccess(Permission permission,
                            HttpHeaders responseHeaders)
          throws IOException {
        System.out.println("Permission ID: " + permission.getId());

        ids.add(permission.getId());

      }
    };
    BatchRequest batch = service.batch();
    Permission userPermission = new Permission()
        .setType("user")
        .setRole("writer");

    userPermission.setEmailAddress(realUser);
    try {
      service.permissions().create(realFileId, userPermission)
          .setFields("id")
          .queue(batch, callback);

      Permission domainPermission = new Permission()
          .setType("domain")
          .setRole("reader");

      domainPermission.setDomain(realDomain);

      service.permissions().create(realFileId, domainPermission)
          .setFields("id")
          .queue(batch, callback);

      batch.execute();

      return ids;
    } catch (GoogleJsonResponseException e) {
      // TODO(developer) - handle error appropriately
      System.err.println("Unable to modify permission: " + e.getDetails());
      throw e;
    }
  }
}

Python

drive/snippets/drive-v3/file_snippet/share_file.py

הצגת הקוד ב-GitHub

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def share_file(real_file_id, real_user, real_domain):
  """Batch permission modification.
  Args:
      real_file_id: file Id
      real_user: User ID
      real_domain: Domain of the user ID
  Prints modified permissions

  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()

  try:
    # create drive api client
    service = build("drive", "v3", credentials=creds)
    ids = []
    file_id = real_file_id

    def callback(request_id, response, exception):
      if exception:
        # Handle error
        print(exception)
      else:
        print(f"Request_Id: {request_id}")
        print(f'Permission Id: {response.get("id")}')
        ids.append(response.get("id"))

    # pylint: disable=maybe-no-member
    batch = service.new_batch_http_request(callback=callback)
    user_permission = {
        "type": "user",
        "role": "writer",
        "emailAddress": "[e-mail]",
    }
    batch.add(
        service.permissions().create(
            fileId=file_id,
            body=user_permission,
            fields="id",
        )
    )
    domain_permission = {
        "type": "domain",
        "role": "reader",
        "domain": "example.com",
    }
    domain_permission["domain"] = real_domain
    batch.add(
        service.permissions().create(
            fileId=file_id,
            body=domain_permission,
            fields="id",
        )
    )
    batch.execute()

  except HttpError as error:
    print(f"An error occurred: {error}")
    ids = None

  return ids


if __name__ == "__main__":
  share_file(
      real_file_id="1dUiRSoAQKkM3a4nTPeNQWgiuau1KdQ_l",
      real_user="[e-mail]",
      real_domain="workspacesamples.dev",
  )

Node.js

drive/snippets/drive_v3/file_snippets/share_file.js

הצגת הקוד ב-GitHub

import {GoogleAuth} from 'google-auth-library';
import {google} from 'googleapis';

/**
 * Shares a file with a user and a domain.
 * @param {string} fileId The ID of the file to share.
 * @param {string} targetUserEmail The email address of the user to share with.
 * @param {string} targetDomainName The domain to share with.
 * @return {Promise<Array<string>>} A promise that resolves to an array of permission IDs.
 */
async function shareFile(fileId, targetUserEmail, targetDomainName) {
  // Authenticate with Google and get an authorized client.
  // TODO (developer): Use an appropriate auth mechanism for your app.
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive',
  });

  // Create a new Drive API client (v3).
  const service = google.drive({version: 'v3', auth});

  /** @type {Array<string>} */
  const permissionIds = [];

  // The permissions to create.
  const permissions = [
    {
      type: 'user',
      role: 'writer',
      emailAddress: targetUserEmail, // e.g., '[e-mail]'
    },
    {
      type: 'domain',
      role: 'writer',
      domain: targetDomainName, // e.g., 'example.com'
    },
  ];

  // Iterate through the permissions and create them one by one.
  for (const permission of permissions) {
    const result = await service.permissions.create({
      requestBody: permission,
      fileId,
      fields: 'id',
    });

    if (result.data.id) {
      permissionIds.push(result.data.id);
      console.log(`Inserted permission id: ${result.data.id}`);
    } else {
      throw new Error('Failed to create permission');
    }
  }
  return permissionIds;
}

PHP

drive/snippets/drive_v3/src/DriveShareFile.php

הצגת הקוד ב-GitHub

<?php
use Google\Client;
use Google\Service\Drive;
function shareFile()
{
    try {
        $client = new Client();
        $client->useApplicationDefaultCredentials();
        $client->addScope(Drive::DRIVE);
        $driveService = new Drive($client);
        $realFileId = readline("Enter File Id: ");
        $realUser = readline("Enter user email address: ");
        $realDomain = readline("Enter domain name: ");
        $ids = array();
            $fileId = '1sTWaJ_j7PkjzaBWtNc3IzovK5hQf21FbOw9yLeeLPNQ';
            $fileId = $realFileId;
            $driveService->getClient()->setUseBatch(true);
            try {
                $batch = $driveService->createBatch();

                $userPermission = new Drive\Permission(array(
                    'type' => 'user',
                    'role' => 'writer',
                    'emailAddress' => '[e-mail]'
                ));
                $userPermission['emailAddress'] = $realUser;
                $request = $driveService->permissions->create(
                    $fileId, $userPermission, array('fields' => 'id'));
                $batch->add($request, 'user');
                $domainPermission = new Drive\Permission(array(
                    'type' => 'domain',
                    'role' => 'reader',
                    'domain' => 'example.com'
                ));
                $userPermission['domain'] = $realDomain;
                $request = $driveService->permissions->create(
                    $fileId, $domainPermission, array('fields' => 'id'));
                $batch->add($request, 'domain');
                $results = $batch->execute();

                foreach ($results as $result) {
                    if ($result instanceof Google_Service_Exception) {
                        // Handle error
                        printf($result);
                    } else {
                        printf("Permission ID: %s\n", $result->id);
                        array_push($ids, $result->id);
                    }
                }
            } finally {
                $driveService->getClient()->setUseBatch(false);
            }
            return $ids;
    } catch(Exception $e) {
        echo "Error Message: ".$e;
    }

}

‎.NET

drive/snippets/drive_v3/DriveV3Snippets/ShareFile.cs

הצגת הקוד ב-GitHub

using Google.Apis.Auth.OAuth2;
using Google.Apis.Drive.v3;
using Google.Apis.Drive.v3.Data;
using Google.Apis.Requests;
using Google.Apis.Services;

namespace DriveV3Snippets
{
    // Class to demonstrate use-case of Drive modify permissions.
    public class ShareFile
    {
        /// <summary>
        /// Batch permission modification.
        /// </summary>
        /// <param name="realFileId">File id.</param>
        /// <param name="realUser">User id.</param>
        /// <param name="realDomain">Domain id.</param>
        /// <returns>list of modified permissions, null otherwise.</returns>
        public static IList<String> DriveShareFile(string realFileId, string realUser, string realDomain)
        {
            try
            {
                /* Load pre-authorized user credentials from the environment.
                 TODO(developer) - See https://developers.google.com/identity for
                 guides on implementing OAuth2 for your application. */
                GoogleCredential credential = GoogleCredential.GetApplicationDefault()
                    .CreateScoped(DriveService.Scope.Drive);

                // Create Drive API service.
                var service = new DriveService(new BaseClientService.Initializer
                {
                    HttpClientInitializer = credential,
                    ApplicationName = "Drive API Snippets"
                });

                var ids = new List<String>();
                var batch = new BatchRequest(service);
                BatchRequest.OnResponse<Permission> callback = delegate(
                    Permission permission,
                    RequestError error,
                    int index,
                    HttpResponseMessage message)
                {
                    if (error != null)
                    {
                        // Handle error
                        Console.WriteLine(error.Message);
                    }
                    else
                    {
                        Console.WriteLine("Permission ID: " + permission.Id);
                    }
                };
                Permission userPermission = new Permission()
                {
                    Type = "user",
                    Role = "writer",
                    EmailAddress = realUser
                };

                var request = service.Permissions.Create(userPermission, realFileId);
                request.Fields = "id";
                batch.Queue(request, callback);

                Permission domainPermission = new Permission()
                {
                    Type = "domain",
                    Role = "reader",
                    Domain = realDomain
                };
                request = service.Permissions.Create(domainPermission, realFileId);
                request.Fields = "id";
                batch.Queue(request, callback);
                var task = batch.ExecuteAsync();
                task.Wait();
                return ids;
            }
            catch (Exception e)
            {
                // TODO(developer) - handle error appropriately
                if (e is AggregateException)
                {
                    Console.WriteLine("Credential Not found");
                }
                else
                {
                    throw;
                }
            }
            return null;
        }
    }
}

מחיקת הרשאה

כדי לבטל את הגישה לקובץ או לתיקייה, צריך להפעיל את ה-method ‏delete במשאב permissions עם פרמטרי הנתיב fileId ו-permissionId שמוגדרים למחיקת ההרשאה.

אי אפשר לבטל הרשאות שעברו בירושה. במקום זאת, צריך לעדכן או למחוק את ההרשאה בתיקייה ברמה העליונה. מחיקה של הרשאה בתיקייה מבטלת גם את הגישה המקבילה לפריטי צאצא.

כדי לצמצם את ההרשאות בהשוואה להרשאות של התיקייה הראשית, צריך להשתמש בהגדרה של גישה מוגבלת.

חשוב לדעת: אם מסירים את הגישה של משתמש מפריט הורה, ההרשאות שבוטלו הן רק אלה שעברו בירושה מההורה. אם למשתמש הוקצו הרשאות ישירות לקובץ או לתיקיית צאצא, הגישה שלו נשארת. כדי לוודא שכל פריטי הצאצא תואמים להרשאות של פריט האב, צריך לזהות ולהסיר את כל ההרשאות הישירות שניתנו למשתמש על פריטי הצאצא האלה.

בדוגמת הקוד הבאה אפשר לראות איך מבטלים את הגישה על ידי מחיקת 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 API‏ (גרסה 2), צריך להשתמש בשדה expirationDate. כך מעבירים ל-Drive API v3.

למידע נוסף על תאריך התפוגה, אפשר לעיין במאמרים הבאים:

• איך פועלים קישורים לקבצים ובקרת גישה
• הגדרת תאריך תפוגה לגישה לקובץ
• הוספת תאריך תפוגה

נושאים קשורים

• ניהול הצעות לגישה בהמתנה
• ניהול תיקיות עם גישה מוגבלת וגישה רחבה
• העברת בעלות על קובץ
• הגנה על תוכן הקובץ
• גישה לקבצים ב-Drive ששותפו באמצעות קישור באמצעות מפתחות משאבים
• תפקידים והרשאות