מעבר מ-Email Settings API

במסמך הזה מפורטים ההבדלים העיקריים בין Email Settings API לבין Gmail API. תוכלו להיעזר במדריך הזה כדי להעביר את האפליקציה שלכם ל-Gmail API.

הרשאת בקשות

בדומה ל-Email Settings API, גם Gmail API משתמש בפרוטוקול OAuth 2.0 כדי לאשר בקשות. אחד ההבדלים העיקריים הוא שהרשאות Gmail API מוגדרות למשתמש ספציפי, ולא לדומיין כולו. כלומר, הרשאה לחשבון אדמין של דומיין לא מאפשרת להעביר אימיילים של משתמשים אחרים בדומיין. במקום זאת, צריך להשתמש בחשבונות שירות רגילים עם הרשאה ברמת הדומיין שרשומים ברשימת ההיתרים במסוף Admin כדי ליצור את אסימון האימות המתאים.

ממשק ה-API של הגדרות האימייל השתמש בהיקף:

https://apps-apis.google.com/a/feeds/emailsettings/2.0/

ההיקפים המקבילים ב-Gmail API הם:

https://www.googleapis.com/auth/gmail.settings.basic
https://www.googleapis.com/auth/gmail.settings.sharing

שינויים בפרוטוקול

ב-Email Settings API נעשה שימוש בפרוטוקול GDATA מבוסס-XML. ב-Gmail API נעשה שימוש ב-JSON. מכיוון שההגדרות מורכבות בעיקר מצמדי מפתח/ערך, עומסי העבודה דומים מבחינה מושגית בין הגרסאות.

דוגמה ליצירת תווית:

Email Settings API

POST https://apps-apis.google.com/a/feeds/emailsettings/2.0/{domain name}/{username}/label
<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
  <apps:property name="label" value="status updates" />
</atom:entry>

ממשק ה-API של Gmail

POST https://www.googleapis.com/gmail/v1/users/{username}/labels
{
   "name": "status updates"
}

במקום להטמיע את הפרוטוקול ישירות, כדאי להשתמש בספריות הלקוח שסופקו.

ניהול תוויות

כדי לנהל תוויות ב-Gmail API, משתמשים במשאב Labels.

ההגדרה הישנה הגדרה חדשה הערות
labelId id [מזהה]
תווית שם
unreadCount messagesUnread
חשיפה labelListVisibility SHOW הוא עכשיו labelShow
HIDE הוא עכשיו labelHide

שינויים אחרים:

  • כשמעדכנים או מוחקים תוויות, המערכת של Gmail API מפנה לתוויות לפי מזהה במקום לפי שם.

ניהול המסננים

כדי לנהל מסננים ב-Gmail API, משתמשים במשאב Filters.

ההגדרה הישנה הגדרה חדשה הערות
החל מ- criteria.from
עד criteria.to
subject criteria.subject
hasTheWord criteria.query
doesNotHaveTheWord criteria.negatedQuery
hasAttachment criteria.hasAttachment
shouldArchive action.removeLabelIds שימוש ב-INBOX בתור מזהה התווית
shouldMarkAsRead action.removeLabelIds שימוש ב-UNREAD בתור מזהה התווית
shouldStar action.addLabelIds משתמשים ב-STARRED כמזהה התווית
תווית action.addLabelIds משתמשים במזהה התווית שרוצים להוסיף
forwardTo action.forward
shouldTrash action.addLabelIds משתמשים ב-TRASH כמזהה התווית
neverSpam action.removeLabelIds משתמשים ב-SPAM כמזהה התווית

שינויים נוספים:

  • אם מוסיפים תווית משתמש שלא קיימת, צריך ליצור אותה במפורש באמצעות השיטה labels.create.

ניהול כינויים לשליחה בתור

כדי לנהל כתובות אימייל חלופיות לצורך שליחה ב-Gmail API, משתמשים במשאב SendAs.

ההגדרה הישנה הגדרה חדשה
שם displayName
כתובת sendAsEmail
replyTo replyToAddress
makeDefault isDefault

ניהול קליפים מהאינטרנט

ההגדרות של Web Clip כבר לא זמינות דרך ה-API.

ניהול ההגדרות של העברה אוטומטית

כדי לנהל את ההעברה האוטומטית ב-Gmail API, משתמשים במשאב Settings.

ההגדרה הישנה הגדרה חדשה הערות
enable פעיל
forwardTo emailAddress
פעולה טיפול KEEP הוא עכשיו leaveInInbox
ARCHIVE הוא עכשיו archive
DELETE הוא עכשיו trash
MARK_READ הוא עכשיו markRead

שינויים נוספים:

  • צריך ליצור כתובות להעברה ולאמת אותן לפני השימוש
  • אפשר לנהל את כתובות ההעברה באמצעות המשאב ForwardingAddresses.

ניהול הגדרות POP

כדי לנהל את הגישה ל-POP ב-Gmail API, משתמשים במשאב Settings.

ההגדרה הישנה הגדרה חדשה הערות
enable accessWindow האפשרות מושבתת כשהיא מוגדרת כ-disabled
enableFor accessWindow ALL_MAIL הוא עכשיו allMail
MAIL_FROM_NOW_ON הוא עכשיו fromNowOn
פעולה טיפול KEEP הוא עכשיו leaveInInbox
ARCHIVE הוא עכשיו archive
DELETE הוא עכשיו trash
MARK_READ הוא עכשיו markRead

ניהול ההגדרות של IMAP

כדי לנהל את הגישה ל-IMAP ב-Gmail API, משתמשים במשאב Settings.

ההגדרה הישנה הגדרה חדשה
enable פעיל

ניהול ההגדרות של התשובה האוטומטית לחופשה

כדי לנהל את המענה האוטומטי להודעות חופשה ב-Gmail API, משתמשים במשאב Settings.

ההגדרה הישנה הגדרה חדשה
contactsOnly restrictToContacts
domainOnly restrictToDomain
enable enableAutoReply
endDate endTime
הודעה responseBodyHtml
responseBodyPlainText
startDate startTime
subject responseSubject

ניהול הגדרות החתימה

כדי לנהל חתימות באימייל ב-Gmail API, משתמשים במשאב SendAs.

ההגדרה הישנה הגדרה חדשה
signature signature

שינויים נוספים:

  • עכשיו אפשר לנהל חתימות לכל כתובת אימייל חלופית.

ניהול הגדרות השפה

כדי לנהל את הגדרות השפה ב-Gmail API, משתמשים במשאב Settings.

ההגדרה הישנה הגדרה חדשה
language displayLanguage

מידע נוסף זמין במדריך לניהול הגדרות השפה.

ניהול הגדרות ההאצלה

כדי לנהל את הענקת הגישה ב-Gmail API, משתמשים במשאב Delegates.

ההגדרה הישנה הגדרה חדשה
כתובת delegateEmail
status verificationStatus

שינויים נוספים:

  • כללי
    • כדי להשתמש באחת משיטות הענקת הגישה (כולל delegates.create), משתמש מעניק הגישה צריך להיות מופעל ב-Gmail. כלומר, לדוגמה, לא ניתן להשעות את המשתמש שהעניק את הגישה ב-Google Workspace.
    • אי אפשר להשתמש בכתובת אימייל חלופית כקלט של כתובת האימייל של הנציג באף אחת מהשיטות החדשות. צריך לציין את כתובת האימייל הראשית של המשתמש שרוצים להעניק לו הרשאה.
  • delegates.create
    • מעכשיו אפשר להשתמש בשיטה הזו כדי ליצור יחסי הענקת גישה בכמה דומיינים ששייכים לאותה Google Workspace ארגון.
    • עכשיו אפשר להשתמש בשיטה הזו למשתמשים שצריכים לשנות את הסיסמה בכניסה הבאה.
    • אם הפעולה בוצעה ללא שגיאות, ה-method מחזיר משאב Users.settings.delegates בגוף התגובה, במקום גוף תגובה ריק.
    • אם אחד מהמשתמשים שהעניק או קיבל את הגישה מושבת (למשל, הושעה ב- Google Workspace), השיטה תיכשל עם שגיאת HTTP 4XX במקום שגיאת HTTP 500.
  • delegates.delete
    • עכשיו אפשר להשתמש בשיטה הזו כדי למחוק חשבונות משתמשים עם כל ערך של verificationStatus, ולא רק חשבונות משתמשים עם הערכים accepted או expired.
  • delegates.get
    • זוהי שיטה חדשה, שעשויה להיות עדיפה על השיטה delegates.list, בהתאם לצורך.

ניהול ההגדרות הכלליות

ההגדרות הכלליות לא זמינות יותר דרך ה-API.