התראות בדחיפה

סקירה

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

הגדרה ראשונית של Cloud Pub/Sub

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

דרישות מוקדמות

כדי להשלים את שאר ההגדרות, עליכם לעמוד בדרישות המוקדמות של Cloud Pub/Sub ולאחר מכן להגדיר לקוח Cloud Pub/Sub.

יצירת נושא

באמצעות הלקוח של Cloud Pub/Sub, יוצרים את הנושא שאליו ממשק ה-API של Gmail ישלח התראות. שם הנושא יכול להיות כל שם שתבחרו לפרויקט (כלומר, שם תואם ל-projects/myproject/topics/*, כאשר myproject הוא מזהה הפרויקט שמופיע ב-Google Developers Console).

אנחנו ממליצים להשתמש בנושא אחד לכל ההתראות של Gmail API באפליקציה שלכם, עקב המגבלות של Cloud Pub/Sub לגבי מספר הנושאים.

יצירת מינוי

פועלים לפי ההוראות במדריך למנויים של Cloud Pub/Sub כדי להגדיר מינוי לנושא שיצרתם. מגדירים את סוג המינוי כדחיפה (webhook) (כלומר HTTP POST) או משיכה (כלומר, ביוזמת האפליקציה). כך האפליקציה שלכם תקבל התראות על עדכונים.

הענקת הרשאות פרסום בנושא שלך

כדי שתוכלו לפרסם התראות בנושא שלכם, תצטרכו להעניק ל-Cloud Pub/Sub הרשאות של Gmail.

לשם כך, צריך להעניק הרשאות publish ל-gmail-api-push@system.gserviceaccount.com. אפשר לעשות זאת באמצעות ממשק ההרשאות של Cloud Pub/Sub Developer Console לפי ההוראות לבקרת גישה ברמת המשאב.

קבלת עדכונים לתיבת הדואר הנכנס של Gmail

אחרי שתסיימו את ההגדרה הראשונית של Cloud Pub/Sub, תוכלו להגדיר חשבונות Gmail לשליחת התראות על עדכונים בתיבת הדואר.

בקשה לצפייה

כדי להגדיר שחשבונות Gmail יישלחו התראות לנושא Cloud Pub/Sub, צריך פשוט להשתמש בלקוח Gmail API כדי לבצע קריאה אל watch בתיבת הדואר של המשתמש ב-Gmail בדומה לכל קריאה אחרת ב-Gmail API. כדי לעשות את זה, צריך לציין את שם הנושא שנוצר למעלה ואת כל האפשרויות האחרות לבקשת watch, כמו labels לסינון. לדוגמה, כדי לקבל התראה בכל פעם שמתבצע שינוי בתיבת הדואר הנכנס:

פרוטוקול

POST "https://www.googleapis.com/gmail/v1/users/me/watch"
Content-type: application/json

{
  topicName: "projects/myproject/topics/mytopic",
  labelIds: ["INBOX"],
  labelFilterBehavior: "INCLUDE",
}

Python

request = {
  'labelIds': ['INBOX'],
  'topicName': 'projects/myproject/topics/mytopic',
  'labelFilterBehavior': 'INCLUDE'
}
gmail.users().watch(userId='me', body=request).execute()

צפייה בתשובה

אם הבקשה של watch תאושר, תקבלו תשובה כמו:

{
  historyId: 1234567890
  expiration: 1431990098200
}

עם תיבת הדואר הנוכחית historyId של המשתמש. כל השינויים שיבוצעו לאחר מכן historyId יקבלו הודעה על כך ללקוח. במדריך הסנכרון מוסבר איך לבצע שינויים לפני historyId.

בנוסף, קריאה תקינה ל-watch אמורה לגרום לשליחת התראה באופן מיידי לנושא Cloud Pub/Sub.

אם קיבלתם הודעת שגיאה מהשיחה של watch, עליכם להסביר בפרטים את מקור הבעיה, בדרך כלל במהלך ההגדרה של הנושא והמינוי ב-Cloud Pub/Sub. כדאי לעיין במסמכי התיעוד של Cloud Pub/Sub כדי לוודא שההגדרה נכונה ולקבל עזרה בניפוי באגים בבעיות שקשורות לנושאים ולמינויים.

חידוש השעון של תיבת הדואר

צריך לבצע קריאה מחדש ל-watch כל 7 ימים לפחות, אחרת לא יתקבלו יותר עדכונים של המשתמש. מומלץ להתקשר אל watch פעם ביום. התגובה watch כוללת גם שדה תפוגה עם חותמת הזמן של התפוגה של watch.

קבלת התראות

בכל פעם שיתבצע עדכון בתיבת הדואר שתואם ל-watch שלכם, האפליקציה שלכם תקבל התראה שמתארת את השינוי.

אם הגדרתם מינוי Push, התראת webhook לשרת שלכם תציית לPubsubMessage:

POST https://yourserver.example.com/yourUrl
Content-type: application/json

{
  message:
  {
    // This is the actual notification data, as base64url-encoded JSON.
    data: "eyJlbWFpbEFkZHJlc3MiOiAidXNlckBleGFtcGxlLmNvbSIsICJoaXN0b3J5SWQiOiAiMTIzNDU2Nzg5MCJ9",

    // This is a Cloud Pub/Sub message id, unrelated to Gmail messages.
    "messageId": "2070443601311540",

    // This is the publish time of the message.
    "publishTime": "2021-02-26T19:13:55.749Z",
  }

  subscription: "projects/myproject/subscriptions/mysubscription"
}

גוף ה-HTTP POST הוא JSON והמטען הייעודי (payload) בפועל של ההתראות ב-Gmail נמצא בשדה message.data. השדה message.data הוא מחרוזת בקידוד base64url שמפענחת לאובייקט JSON שמכיל את כתובת האימייל ואת מזהה ההיסטוריה החדש של תיבת הדואר של המשתמש:

{"emailAddress": "user@example.com", "historyId": "9876543210"}

לאחר מכן תוכלו להשתמש ב-history.list כדי לקבל את פרטי השינוי של המשתמש מאז מזהה ההיסטוריה של התאריך האחרון, בהתאם למדריך הסנכרון.

אם במקום זאת הגדרתם מינוי למשיכת הודעות, תוכלו להיעזר בדוגמאות הקוד שבמדריך משיכת מנויים ב-Cloud Pub/Sub לפרטים נוספים על קבלת הודעות.

תגובה להתראות

צריך לאשר את כל ההתראות. אם משתמשים ב-webhook העברת Push, התגובה בהצלחה (למשל HTTP 200) תאשר את ההתראה.

אם משתמשים במסירה בשליפת משיכה (REST Pull, RPC Pull או RPC StreamingPull), אתם צריכים לשלוח בקשה לאישור קריאה (REST או RPC). לפרטים נוספים על אישור הודעות באופן אסינכרוני או באופן סינכרוני, באמצעות ספריות הלקוח הרשמיות שמבוססות על RPC, אפשר לעיין בדוגמאות הקוד במדריך שליפת הודעות למנויי Cloud Pub/Sub.

אם ההתראות לא אושרו (למשל, אם הקריאה החוזרת (callback) ב-webhook מחזירה שגיאה או שתם הזמן הקצוב לתפוגה, מערכת Cloud Pub/Sub תנסה לשלוח את ההתראה שוב במועד מאוחר יותר.

המערכת מפסיקה את העדכונים של תיבת הדואר

כדי להפסיק לקבל עדכונים על תיבת דואר, צריך להתקשר ל-stop וכל ההתראות החדשות אמורות להיפסק תוך כמה דקות.

מגבלות

קצב התראות מקסימלי

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

אמינות

בדרך כלל כל ההתראות אמורות להישלח בצורה מהימנה תוך מספר שניות, אבל במצבים קיצוניים מסוימים ייתכן שהן יידחו או יוסרו. הקפידו לטפל באפשרות הזו בחינניות, כדי שהאפליקציה תמשיך להסתנכרן גם אם לא יתקבלו הודעות דחיפה. לדוגמה, תוכלו לחזור לשיחות history.list מדי פעם אחרי פרק זמן מסוים בלי התראות למשתמש.

הגבלות של Cloud Pub/Sub

גם ל-Cloud Pub/Sub API יש מגבלות משלו, המפורטות במסמכי התיעוד בנושא pricing וquotas.