במסמך הזה מפורט מידע על הרשאה ואימות שספציפיים ל-Gmail API. לפני שקוראים את המסמך הזה, חשוב לקרוא את המידע הכללי על אימות והרשאה ב-Google Workspace במאמר מידע על אימות והרשאה.
הגדרת OAuth 2.0 למתן הרשאות
מגדירים את מסך ההסכמה של OAuth ובוחרים היקפי הרשאה כדי להגדיר איזה מידע יוצג למשתמשים ולבודקי האפליקציה, ורושמים את האפליקציה כדי שתוכלו לפרסם אותה בהמשך.
היקפי הרשאות של Gmail API
כדי להגדיר את רמת הגישה שניתנת לאפליקציה, צריך לזהות ולהצהיר על היקפי הרשאות. היקף הרשאות הוא מחרוזת URI של OAuth 2.0 שמכילה את שם אפליקציית Google Workspace, את סוג הנתונים שהיא ניגשת אליהם ואת רמת הגישה. ההיקפים הם הבקשות של האפליקציה לעבוד עם נתוני Google Workspace, כולל נתוני חשבון Google של המשתמשים.
כשמתקינים את האפליקציה, המשתמש מתבקש לאמת את היקפי ההרשאות שבהם נעשה שימוש באפליקציה. בדרך כלל, כדאי לבחור את היקף ההרשאות הממוקד ביותר שאפשר, ולהימנע מבקשת היקפי הרשאות שהאפליקציה לא צריכה. המשתמשים נוטים יותר להעניק גישה להיקפים מוגבלים שמתוארים בצורה ברורה.
Gmail API תומך בהיקפי ההרשאות הבאים:
| קוד היקף | תיאור | שימוש |
|---|---|---|
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: מדיניות בנושא נתוני משתמשים. ההיקפים האלה לא דורשים הערכת אבטחה.
מוגבל – היקפי הגישה האלה מספקים גישה רחבה לנתוני משתמשים ב-Google, ולכן נדרש תהליך אימות של היקף גישה מוגבל. מידע על הדרישה הזו זמין במאמרים שירותי Google API: מדיניות בנושא נתוני משתמשים ודרישות נוספות להיקפי API ספציפיים. אם אתם מאחסנים נתונים בהיקף מוגבל בשרתים (או מעבירים אותם), אתם צריכים לעבור בדיקת אבטחה.
מידע נוסף שרלוונטי לשימוש שלכם בממשקי Gmail API ולגישה שלכם לנתוני משתמשים זמין במדיניות של Gmail API בנושא נתוני משתמשים ומפתחים.
אם האפליקציה שלכם דורשת גישה ל-Google APIs אחרים, אתם יכולים להוסיף גם את היקפי ההרשאות האלה. למידע נוסף על היקפי Google API, אפשר לעיין במאמר שימוש ב-OAuth 2.0 כדי לגשת אל Google APIs.
אימות OAuth
יכול להיות ששימוש בהיקפי OAuth רגישים מסוימים יחייב את האפליקציה שלכם לעבור את תהליך האימות של Google ל-OAuth. כדאי לקרוא את השאלות הנפוצות בנושא אימות OAuth כדי להבין מתי האפליקציה צריכה לעבור אימות ואיזה סוג אימות נדרש. מומלץ לעיין גם במדיניות של Google בנושא נתוני משתמשים בשירותי API.