הגדרת התראות פוש באמצעות Gmail API

במאמר הזה מוסבר איך לנהל התראות פוש באמצעות Gmail API.

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

בנוסף, קריאה מוצלחת של 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.

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

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

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

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

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

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

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

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

מגבלות

אלה המגבלות של שימוש בהתראות Push מהשרת:

תדירות מקסימלית של התראות

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

אמינות

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

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

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