המסמך הזה מכיל מידע ספציפי לגבי הרשאה ואימות ב-Gmail API. לפני קריאת המסמך הזה, חשוב לקרוא את המידע הכללי על אימות והרשאה ב-Google Workspace במאמר מידע על אימות והרשאה.
הגדרת OAuth 2.0 להרשאה
מגדירים את מסך ההסכמה של OAuth ובוחרים היקפי הרשאה כדי לקבוע איזה מידע יוצג למשתמשים ולבודקים של האפליקציה, ומרשמים את האפליקציה כדי שתוכלו לפרסם אותה בהמשך.
היקפי הרשאה של Gmail API
כדי להגדיר את רמת הגישה שמוענקת לאפליקציה, צריך לזהות ולדווח על היקפי הרשאה. היקף הרשאה הוא מחרוזת URI של OAuth 2.0 שמכילה את שם האפליקציה ב-Google Workspace, את סוג הנתונים שהיא ניגשת אליהם ואת רמת הגישה. היקפים הם הבקשות של האפליקציה לעבוד עם נתוני Google Workspace, כולל נתונים מחשבון Google של המשתמשים.
כשהאפליקציה מותקנת, המשתמש מתבקש לאמת את ההיקפים שבהם האפליקציה משתמשת. באופן כללי, כדאי לבחור את ההיקף המצומצם ביותר האפשרי ולהימנע מבקשות להיקפים שלא נדרשים לאפליקציה. משתמשים נותנים גישה בקלות רבה יותר להיקפים מוגבלים ומתוארים בבירור.
ה-API של Gmail תומך בהיקפים הבאים:
| קוד ההיקף | תיאור | שימוש |
|---|---|---|
https://www.googleapis.com/auth/gmail.addons.current.action.compose |
ניהול טיוטות ושליחת הודעות אימייל בעת אינטראקציה עם התוסף. | לא רגיש |
https://www.googleapis.com/auth/gmail.addons.current.message.action |
הצגת הודעות האימייל שלכם בכל אינטראקציה עם התוסף. | לא רגיש |
https://www.googleapis.com/auth/gmail.addons.current.message.metadata |
הצגת המטא-נתונים של הודעות האימייל כשהתוסף פועל. | רגישות |
https://www.googleapis.com/auth/gmail.addons.current.message.readonly |
הצגת הודעות האימייל כשהתוסף פועל. | רגישות |
https://www.googleapis.com/auth/gmail.labels |
יצירה, קריאה, עדכון ומחיקה של תוויות בלבד. | לא רגיש |
https://www.googleapis.com/auth/gmail.send |
לשלוח הודעות בלבד. אין הרשאות קריאה או שינוי בתיבת הדואר. | רגישות |
https://www.googleapis.com/auth/gmail.readonly |
קריאה של כל המשאבים והמטא-נתונים שלהם – ללא פעולות כתיבה. | מוצר שהצפייה בו הוגבלה |
https://www.googleapis.com/auth/gmail.compose |
יצירה, קריאה, עדכון ומחיקה של טיוטות. לשלוח הודעות וטיוטות. | מוצר שהצפייה בו הוגבלה |
https://www.googleapis.com/auth/gmail.insert |
הוספה וייבוא של הודעות בלבד. | מוצר שהצפייה בו הוגבלה |
https://www.googleapis.com/auth/gmail.modify |
כל פעולות הקריאה/הכתיבה, מלבד מחיקה מיידית וקבועה של שרשור הודעות, בלי לעבור דרך 'אשפה'. | מוצר שהצפייה בו הוגבלה |
https://www.googleapis.com/auth/gmail.metadata |
קריאת המטא-נתונים של המשאבים, כולל תוויות, רשומות היסטוריה וכותרות של הודעות אימייל, אבל לא גוף ההודעה או קבצים מצורפים. | מוצר שהצפייה בו הוגבלה |
https://www.googleapis.com/auth/gmail.settings.basic |
ניהול ההגדרות הבסיסיות של הדואר. | מוצר שהצפייה בו הוגבלה |
https://www.googleapis.com/auth/gmail.settings.sharing |
ניהול ההגדרות של דואר רגיש, כולל כללי העברה וכינויים.
הערה: הפעולות שמוגנות בהיקף הזה מוגבלות לשימוש אדמיניסטיבי בלבד. הם זמינים רק ללקוחות Google Workspace שמשתמשים בחשבון שירות עם הענקת גישה ברמת הדומיין. |
מוצר שהצפייה בו הוגבלה |
https://mail.google.com/ |
גישה מלאה לתיבת הדואר של החשבון, כולל מחיקה סופית של שרשור הודעות. צריך לבקש את ההיקף הזה רק אם האפליקציה צריכה למחוק באופן מיידי ולתמיד שרשור הודעות, בלי לעבור דרך 'אשפה'. אפשר לבצע את כל הפעולות האחרות עם היקפי גישה פחות רחבים. | מוצר שהצפייה בו הוגבלה |
העמודה 'שימוש' בטבלה שלמעלה מציינת את רמת הרגישות של כל היקף, בהתאם להגדרות הבאות:
לא רגיש – ההיקפים האלה מספקים את ההיקף הקטן ביותר של גישה להרשאה, ודורשים רק אימות בסיסי של האפליקציה. מידע נוסף על הדרישה הזו זמין במאמר שלבים להכנה לאימות.
רגיש – היקפי ההרשאות האלה מאפשרים גישה לנתוני משתמשים ב-Google, ונדרש תהליך אימות של היקף ההרשאות הרגיש. מידע נוסף על הדרישה הזו זמין במאמר Google API Services: User Data Policy. לא נדרשת בדיקת אבטחה להיקפי הגישה האלה.
מוגבל – היקפי הגישה האלה מספקים גישה רחבה לנתוני המשתמשים ב-Google, וצריך לעבור תהליך אימות להיקף גישה מוגבל. מידע נוסף על הדרישה הזו זמין במאמרים Google API Services: User Data Policy וAdditional Requirements for Specific API Scopes. אם אתם מאחסנים נתונים בהיקף מוגבל בשרתים (או מעבירים אותם), עליכם לעבור הערכת אבטחה.
מידע נוסף בנושא השימוש והגישה שלכם לממשקי Gmail API כשאתם מבקשים גישה לנתוני משתמשים זמין במדיניות בנושא נתוני משתמשים ומדיניות למפתחים של שירותי Gmail API.
אם האפליקציה שלכם זקוקה לגישה לממשקי Google API אחרים, תוכלו להוסיף גם את ההיקפים האלה. למידע נוסף על היקפי ההרשאות של Google API, תוכלו לקרוא את המאמר שימוש ב-OAuth 2.0 כדי לגשת ל-Google APIs.
אימות OAuth
כדי להשתמש בהיקפי OAuth מסוימים שכוללים מידע רגיש, יכול להיות שהאפליקציה תצטרך לעבור את תהליך האימות של Google ב-OAuth. כדאי לקרוא את השאלות הנפוצות בנושא אימות OAuth כדי להבין מתי צריך לבצע אימות של האפליקציה ואיזה סוג אימות נדרש. מומלץ לעיין גם במדיניות בנושא נתוני משתמשים בשירותי Google API.