במסמך הזה מופיע מידע על הרשאה ואימות שספציפיים ל-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.labels |
קריאה ועריכה של תוויות האימייל. |
היקפים רגישים
| קוד היקף | תיאור |
|---|---|
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.send |
שליחת אימייל מטעמך. |
היקפים מוגבלים
| קוד היקף | תיאור |
|---|---|
https://mail.google.com/ |
קריאה, כתיבה, שליחה ומחיקה סופית של כל הודעות האימייל ב-Gmail.
הערה: צריך לבקש את ההיקף הזה רק אם האפליקציה צריכה למחוק באופן מיידי וסופי שרשורים והודעות, בלי להעביר אותם לאשפה. אפשר לבצע את כל הפעולות האחרות באמצעות היקפי הרשאות מצומצמים יותר. |
https://www.googleapis.com/auth/gmail.readonly |
לגשת להגדרות ולהודעות האימייל שלכם. |
https://www.googleapis.com/auth/gmail.compose |
ניהול טיוטות ושליחת הודעות אימייל. |
https://www.googleapis.com/auth/gmail.insert |
הוספת אימיילים לתיבת הדואר ב-Gmail. |
https://www.googleapis.com/auth/gmail.modify |
קריאה, כתיבה ושליחה של הודעות אימייל מחשבון Gmail. היקף ההרשאות הזה לא מאפשר מחיקה מיידית וסופית של שרשורים והודעות, בלי להעביר אותם לאשפה. |
https://www.googleapis.com/auth/gmail.metadata |
הצגת מטא נתונים של הודעות האימייל שלכם, כמו תוויות וכותרות, אבל לא את תוכן האימייל. |
https://www.googleapis.com/auth/gmail.settings.basic |
הצגה, עריכה, יצירה או שינוי של הגדרות ומסנני האימייל ב-Gmail. |
https://www.googleapis.com/auth/gmail.settings.sharing |
ניהול של הגדרות רגישות לדואר, כולל האנשים שיכולים לנהל את הדואר שלכם.
הערה: פעולות שמוגנות על ידי ההיקף הזה מוגבלות לשימוש אדמיניסטרטיבי בלבד. הם זמינים רק ללקוחות Google Workspace שמשתמשים בחשבון שירות עם הענקת גישה ברמת הדומיין. |
ההיקפים בטבלאות הקודמות מציינים את הרגישות שלהם, בהתאם להגדרות הבאות:
לא רגיש: היקפי ההרשאות האלה מספקים את היקף ההרשאות המינימלי ונדרש רק אימות בסיסי של אפליקציית OAuth. מידע נוסף זמין במאמר בנושא דרישות האימות.
רגישים: היקפי ההרשאות האלה מספקים גישה לנתוני משתמשים ספציפיים ב-Google שהמשתמשים מאשרים לאפליקציה שלכם. הם דורשים אימות נוסף של אפליקציית OAuth. מידע נוסף מופיע במאמר בנושא דרישות לגבי היקפים רגישים ומוגבלים.
מוגבל: היקפי ההרשאות האלה מספקים גישה רחבה לנתוני משתמשים ב-Google, ונדרש עבורם אימות של אפליקציית OAuth עם היקף הרשאות מוגבל. מידע נוסף זמין במאמרים המדיניות של Google בנושא נתוני משתמשים בשירותי API ודרישות נוספות להיקפי הרשאות ספציפיים של API.
אם אתם מאחסנים נתונים בהיקף מוגבל בשרתים (או מעבירים אותם), אתם חייבים לעבור בדיקת אבטחה.
מידע נוסף שרלוונטי לשימוש שלכם בממשקי Gmail API ולגישה שלכם אליהם כשאתם מבקשים לגשת לנתוני משתמשים זמין במדיניות של Google Workspace API בנושא נתוני משתמשים ומפתחים.
אם האפליקציה שלכם דורשת גישה לממשקי Google API אחרים, תוכלו להוסיף גם את היקפי ההרשאות האלה. מידע נוסף על היקפי Google API זמין במאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs.
מידע נוסף על היקפי הרשאות ספציפיים של OAuth 2.0 מופיע במאמר היקפי הרשאות של OAuth 2.0 ל-Google APIs.
אימות OAuth
כדי להשתמש בהיקפי OAuth מסוימים שכוללים נתונים רגישים, יכול להיות שהאפליקציה שלכם תצטרך לעבור את תהליך האימות של Google ל-OAuth. שאלות נפוצות בנושא אימות אפליקציות OAuth יכולות לעזור לכם להבין אם האימות הזה נחוץ ואיזה סוג אימות נדרש.