הגדרת התראות בדחיפה ב-Gmail API

במאמר הזה מוסבר איך לנהל התראות בדחיפה ב-Gmail API.

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

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

‫Gmail API משתמש ב-Cloud Pub/Sub API כדי לשלוח התראות בדחיפה. כך אפשר לקבל התראות בשיטות שונות, כולל webhooks ו-polling בנקודת קצה אחת של מינוי.

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

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

יצירת נושא

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

יצירת מינוי

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

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

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

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

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

קבלת עדכונים לגבי תיבת הדואר ב-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, תוכלו לעיין במאמר סנכרון לקוחות עם Gmail API.

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

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

חידוש של מעקב אחרי תיבת דואר

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

קבלת התראות

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

אם הגדרתם מינוי דחיפה, ההתראה על תגובה לפעולה מאתר אחר (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"
}

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

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

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

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

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

תגובה להודעות

צריך לאשר את כל ההתראות. אם משתמשים במסירת push של webhook, תגובה מוצלחת (לדוגמה, HTTP 200) מאשרת את ההתראה.

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

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

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

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

מגבלות

אלה המגבלות של עבודה עם התראות Push מהשרת:

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

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

אמינות

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

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

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