בחירת היקפים של Google Drive API

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

הגדרת OAuth 2.0 למתן הרשאות

כדי לתת הרשאה לאפליקציה, צריך להגדיר היקפי OAuth ב-Google Drive API בשני מקומות: במסוף Google Cloud ובאפליקציה.

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

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

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

אפשר להצהיר על היקף הרשאות אחד או יותר ל-OAuth בכל פעם בקוד של האפליקציה כמערך.

בדוגמת הקוד הבאה אפשר לראות איך להצהיר על כמה היקפי הרשאה של OAuth:

Java

List<String> SCOPES = Arrays.asList(
  DriveScopes.DRIVE_FILE,
  DriveScopes.DRIVE_METADATA_READONLY
);

Python

SCOPES = [
  "https://www.googleapis.com/auth/drive.file",
  "https://www.googleapis.com/auth/drive.metadata.readonly",
]

Node.js

const SCOPES = [
  'https://www.googleapis.com/auth/drive.file',
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

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

היקפי ההרשאות של Drive API

כדי להגדיר את רמת הגישה שניתנת לאפליקציה, צריך לזהות ולהצהיר על היקפי הרשאות. היקף הרשאות הוא מחרוזת URI של OAuth 2.0 שמכילה את שם אפליקציית Google Workspace, את סוג הנתונים שהאפליקציה ניגשת אליהם ואת רמת הגישה. ההיקפים הם הבקשות של האפליקציה לעבוד עם נתוני Google Workspace, כולל נתוני חשבון Google של המשתמשים.

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

כדאי להשתמש בהיקפי הרשאות לא רגישים ככל האפשר, כי הם מאפשרים גישה לכל קובץ בנפרד ומצמצמים את הגישה לתכונות ספציפיות שנדרשות לאפליקציה.

היקפי הרשאות לא רגישים

ההיקפים הבאים של Drive API מומלצים לרוב תרחישי השימוש:

קוד היקף תיאור
https://www.googleapis.com/auth/drive.appdata
https://www.googleapis.com/auth/drive.appfolder		 הצגה וניהול של נתוני התצורה של האפליקציה ב-Google Drive.
https://www.googleapis.com/auth/drive.install לאפשר לאפליקציות להופיע כאפשרות בתפריט 'פתיחה באמצעות' או בתפריט 'חדש'.
https://www.googleapis.com/auth/drive.file יצירת קבצים חדשים ב-Drive או שינוי קבצים קיימים שפותחים באמצעות אפליקציה או שהמשתמש משתף עם אפליקציה בזמן השימוש ב-Google Picker API או בכלי לבחירת קבצים של האפליקציה.

היקפי הרשאות רגישים

קוד היקף תיאור
https://www.googleapis.com/auth/drive.apps.readonly הצגת האפליקציות שמורשות לגשת ל-Drive.

היקפים מוגבלים

קוד היקף תיאור
https://www.googleapis.com/auth/drive לצפות בכל הקבצים ב-Drive ולנהל אותם.
https://www.googleapis.com/auth/drive.readonly הצגה והורדה של כל הקבצים ב-Drive.
https://www.googleapis.com/auth/drive.activity הצגת רשומות הפעילות של הקבצים ב-Drive והוספת פעילויות.
https://www.googleapis.com/auth/drive.activity.readonly הצגת רשומות הפעילות של הקבצים ב-Drive.
https://www.googleapis.com/auth/drive.meet.readonly צפייה בקבצים ב-Drive שנוצרו או נערכו ב-Google Meet.
https://www.googleapis.com/auth/drive.metadata הצגה וניהול של מטא נתונים של קבצים ב-Drive.
https://www.googleapis.com/auth/drive.metadata.readonly הצגת מטא נתונים של קבצים ב-Drive.
https://www.googleapis.com/auth/drive.scripts שינוי ההתנהגות של הסקריפטים של Google Apps Script.

ההיקפים בטבלאות הקודמות מציינים את הרגישות שלהם, בהתאם להגדרות הבאות:

אם האפליקציה שלכם דורשת גישה לממשקי Google API אחרים, תוכלו להוסיף גם את היקפי ההרשאות האלה. מידע נוסף על היקפי Google API זמין במאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs.

מידע נוסף על היקפי הרשאות ספציפיים של OAuth 2.0 מופיע במאמר היקפי הרשאות של OAuth 2.0 ל-Google APIs.

הסמכות להיקפי גישה מוגבלים

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

  1. גיבוי וסנכרון: אפליקציות ספציפיות לפלטפורמה ואפליקציות אינטרנט שמספקות סנכרון מקומי או גיבוי אוטומטי של קבצים ב-Drive של המשתמשים.

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

  3. דיווח ואבטחה: אפליקציות שמספקות למשתמשים או ללקוחות תובנות לגבי אופן השיתוף או הגישה לקבצים.

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

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

אם אפליקציית Drive שלכם משתמשת בהיקפי הרשאות מוגבלים, מומלץ לבצע מיגרציה להיקף הרשאות לא רגיש של Drive API. שימוש בהיקפי הרשאות לא רגישים, כמו drive.file, מעניק גישה מצומצמת לכל קובץ בנפרד לתכונות ספציפיות שנדרשות לאפליקציה.

הרבה אפליקציות יכולות לעבור לגישה לכל קובץ בנפרד בלי שום שינוי.

אם אתם משתמשים בכלי לבחירת קבצים משלכם, מומלץ לעבור ל- Google Picker API, שתומך באופן מלא בהיקפי הרשאות שונים.

היתרונות של היקף ההרשאה לקובץ ב-Drive

השימוש בהיקף ההרשאות של drive.file OAuth בשילוב עם Google Picker API משפר את חוויית המשתמש ומגביר את הבטיחות באפליקציה.

drive.file היקף ההרשאות של OAuth מאפשר למשתמשים לבחור אילו קבצים הם רוצים לשתף עם האפליקציה. כך הם מקבלים יותר שליטה וביטחון שהגישה של האפליקציה לקבצים שלהם מוגבלת ומאובטחת יותר. לעומת זאת, אם תדרשו גישה רחבה לכל הקבצים ב-Drive, יכול להיות שהמשתמשים לא ירצו להשתמש באפליקציה שלכם.

ריכזנו כאן כמה סיבות לשימוש בהיקף drive.file:

  • נוחות השימוש: היקף ההרשאות drive.file פועל עם כל משאבי ה-REST של Drive API, כך שאפשר להשתמש בו באותו אופן שבו משתמשים בהיקפי הרשאות רחבים יותר של OAuth.

  • תכונות: ממשק Google Picker API דומה לממשק המשתמש של Drive. האפליקציה כוללת כמה תצוגות שבהן מוצגות תצוגות מקדימות ותמונות ממוזערות של קבצים ב-Drive, וחלון מודאלי מוטבע כדי שהמשתמשים לא יצטרכו לצאת מהאפליקציה הראשית.

  • נוחות: אפליקציות יכולות להחיל מסננים על סוגים מסוימים של קבצים ב-Drive (כמו Google Docs,‏ Sheets ותמונות) כשמשתמשים במסנן בקבצים של Google Picker.

  • אימות פשוט: מכיוון ש-drive.file לא רגיש, תהליך האימות פשוט יותר.

אחסון מאובטח של אסימוני רענון

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

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

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

למידע נוסף, תוכלו לקרוא את המאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs.