במסמך הזה מפורט מידע על הרשאות ואימות שספציפיים ל-Google Drive API. לפני שקוראים את המסמך הזה, חשוב לקרוא את המידע הכללי על אימות והרשאה ב-Google Workspace במאמר מידע על אימות והרשאה.
הגדרת OAuth 2.0 למתן הרשאות
מגדירים את מסך ההסכמה של OAuth ובוחרים היקפי הרשאה כדי להגדיר איזה מידע יוצג למשתמשים ולבודקי האפליקציה, ורושמים את האפליקציה כדי שתוכלו לפרסם אותה בהמשך.
היקפי ההרשאות של Drive API
כדי להגדיר את רמת הגישה שניתנת לאפליקציה, צריך לזהות ולהצהיר על היקפי הרשאות. היקף הרשאות הוא מחרוזת URI של OAuth 2.0 שמכילה את שם אפליקציית Google Workspace, את סוג הנתונים שהיא ניגשת אליהם ואת רמת הגישה. ההיקפים הם הבקשות של האפליקציה לעבוד עם נתוני Google Workspace, כולל נתוני חשבון Google של המשתמשים.
כשמתקינים את האפליקציה, המשתמש מתבקש לאמת את היקפי ההרשאות שבהם נעשה שימוש באפליקציה. בדרך כלל, מומלץ לבחור את היקף ההרשאות המצומצם ביותר שאפשר, ולהימנע מבקשת הרשאות שהאפליקציה לא צריכה. המשתמשים נוטים יותר להעניק גישה להיקפים מוגבלים שמתוארים בצורה ברורה.
כשאפשר, מומלץ להשתמש בהיקפי גישה לא רגישים, כי הם מאפשרים גישה לכל קובץ ומצמצמים את הגישה לתכונות ספציפיות שנדרשות לאפליקציה.
Drive API תומך בהיקפי הגישה הבאים:
| קוד היקף | תיאור | שימוש |
|---|---|---|
https://www.googleapis.com/auth/drive.appdata |
הצגה וניהול של נתוני התצורה של האפליקציה ב-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 שהמשתמש אישר לאפליקציה שלכם. כדי להשתמש בהם, צריך לעבור אימות נוסף של האפליקציה. מידע על הדרישה הזו זמין במאמר דרישות לגבי היקפים רגישים ומוגבלים.
מוגבל: היקפי ההרשאות האלה מספקים גישה רחבה לנתוני משתמשים ב-Google, ולכן צריך לעבור תהליך אימות של היקף הרשאה מוגבל. מידע על הדרישה הזו זמין במאמרים המדיניות של Google בנושא נתוני משתמשים בשירותי API ודרישות נוספות להיקפי הרשאות ספציפיים של API. אם אתם מאחסנים נתונים בהיקף מוגבל בשרתים (או מעבירים אותם), אתם צריכים לעבור בדיקת אבטחה.
אם האפליקציה שלכם דורשת גישה לממשקי Google API אחרים, תוכלו להוסיף גם את היקפי ההרשאות האלה. מידע נוסף על היקפי הרשאות של Google API זמין במאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs.
מידע נוסף על היקפי הרשאות ספציפיים של OAuth 2.0 מופיע במאמר היקפי הרשאות של OAuth 2.0 ל-Google APIs.
איפה מצהירים על היקפי הרשאות
כדי להשתמש ב-Drive API, צריך להגדיר היקפי הרשאה גם במסוף Google Cloud וגם כשמפעילים את ה-API בקוד.
ב-Google Cloud Console, צריך להצהיר על היקפי הגישה שהאפליקציה צריכה בהגדרות של מסך ההסכמה ל-OAuth. זו רמת ההרשאות הגבוהה ביותר שהאפליקציה שלכם יכולה לבקש. ההצהרה הזו משמשת כבקשה רשמית ל-Google, וההיקפים המוצהרים הם מה ש-Google מציגה למשתמשים במסך ההסכמה. כך המשתמש יכול להבין בדיוק לאילו נתונים ופעולות האפליקציה מבקשת גישה. למידע נוסף, אפשר לעיין במאמר בנושא הגדרת מסך הסכמה ל-OAuth ובחירת היקפי הרשאות.
בקוד, כשמפעילים את ה-API, צריך לבקש במפורש את ההיקפים הספציפיים שנדרשים לסשן. במסוף Google Cloud מוגדרת רמת ההרשאות הגבוהה ביותר שהאפליקציה יכולה לבקש, אבל הקוד קובע את ההרשאות בפועל למשתמש מסוים. כך אפשר לוודא שהאפליקציה תבקש רק את ההרשאות שנדרשות למשימה ספציפית.
צריך לבדוק את כל היקפי ההרשאות של Drive API ולבקש רק את היקפי ההרשאות הספציפיים ביותר שנדרשים לתכונות של האפליקציה. יש סיכוי גבוה יותר שהמשתמשים יאשרו גישה להיקפים מוגבלים שמתוארים בצורה ברורה.
איך מגדירים היקפים בקוד
אפשר להצהיר על היקף הרשאות אחד או יותר ל-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'
];
אימות OAuth
שימוש בהיקפי OAuth מסוימים עשוי לחייב את האפליקציה לעבור את התהליך שמתואר במרכז העזרה לאימות אפליקציות ב-OAuth. כדאי לקרוא את השאלות הנפוצות בנושא אפליקציות OAuth כדי להבין מתי האפליקציה שלכם צריכה לעבור אימות ואיזה סוג אימות נדרש. מידע נוסף זמין בתנאים ובהגבלות של Google Drive.
מתי כדאי להשתמש בהיקף מוגבל
ב-Drive, רק לסוגי האפליקציות הבאים יש גישה להיקפי הרשאות מוגבלים:
- אפליקציות אינטרנט ספציפיות לפלטפורמה שמספקות סנכרון מקומי או גיבוי אוטומטי של קבצים ב-Drive של המשתמשים.
- אפליקציות פרודוקטיביות ואפליקציות חינוכיות שהממשק שלהן עשוי לכלול אינטראקציה עם קבצים ב-Drive (או עם המטא-נתונים או ההרשאות שלהם). אפליקציות לפרודוקטיביות כוללות אפליקציות לניהול משימות, לסיכום פגישות, לתקשורת בין קבוצות עבודה ולשיתוף פעולה בכיתה.
- אפליקציות דיווח ואבטחה שמספקות למשתמשים או ללקוחות תובנות לגבי האופן שבו קבצים משותפים או מתבצעת אליהם גישה.
כדי להמשיך להשתמש בהיקפי הרשאות מוגבלים, צריך להכין את האפליקציה לאימות של היקפי הרשאות מוגבלים.
העברת אפליקציה קיימת מהיקפי הרשאות מוגבלים
אם פיתחתם אפליקציית Drive באמצעות אחת מההרשאות המוגבלות, מומלץ להעביר את האפליקציה לשימוש בהרשאה לא רגישה, כי היא מעניקה הרשאת גישה לכל קובץ ומצמצמת את הגישה לתכונות ספציפיות שנדרשות לאפליקציה. הרבה אפליקציות פועלות עם הרשאת גישה לכל קובץ ללא שינויים. אם אתם משתמשים בכלי לבחירת קבצים משלכם, מומלץ לעבור ל-Google Picker API, שתומך באופן מלא בהיקפים שונים.
היתרונות של היקף ההרשאות של OAuth לקבצים ב-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 לא רגיש, תהליך האימות פשוט יותר.
שמירת אסימוני רענון
שומרים את אסימוני הרענון באחסון מאובטח לטווח ארוך וממשיכים להשתמש בהם כל עוד הם תקפים.