בחירת היקפים של 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 scopes

כדי להגדיר את רמת הגישה שניתנת לאפליקציה, צריך לזהות ולהצהיר על היקפי הרשאות. היקף הרשאות הוא מחרוזת 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.

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

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

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

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

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

הגדרות של היקפי גישה מוגבלים

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

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

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

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

אם אפליקציית 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.

במאמר הזה מוסבר על אימות והרשאה ב-Google Workspace.
בסקירה הכללית על אימות תוכלו לקרוא על אימות והרשאה ב-Google Cloud.
מידע נוסף על חשבונות שירות זמין במאמר חשבונות שירות.
לקבלת עזרה בפתרון בעיות, אפשר לעיין במאמר פתרון שגיאות.

בחירת היקפים של Google Drive API קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.