מעבר מ-Email Settings API

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

הרשאת בקשות

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

ה-Email Settings API השתמש בהיקף:

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

היקפי ההרשאות המקבילים ב-API של Gmail הן:

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

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

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

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

ממשק 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
label name
unreadCount messagesUnread
חשיפה labelListVisibility SHOW נקראת עכשיו labelShow
HIDE נקראת עכשיו labelHide

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

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

ניהול מסננים

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

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

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

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

ניהול כתובות אימייל חלופיות

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

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

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

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

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

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

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

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

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

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

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

הגדרה ישנה הגדרה חדשה הערות
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, השתמשו במשאב הגדרות.

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

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

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

הגדרה ישנה הגדרה חדשה
contactsOnly restrictToContacts
domainOnly restrictToDomain
enable enableAutoReply
endDate endTime
הודעה תגובהBodyHtml
תגובהBodyPlainText
startDate startTime
נושא responseSubject

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

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

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

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

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

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

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

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

למידע נוסף, קראו את המדריך לניהול הגדרות השפה.

ניהול ההגדרות של הענקת הגישה

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

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

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

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

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

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