הודעות שנשלחות מהאפליקציה

סקירה כללית

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

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

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

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

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

יצירת נושא

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

יצירת מינוי

פועלים לפי המדריך למנויים ב-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, האפליקציה שלכם תקבל הודעת התראה עם תיאור של השינוי.

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

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

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

מענה להתראות

צריך לאשר את כל ההתראות. אם משתמשים במסירת פוש באמצעות webhook, תשובה מוצלחת (למשל HTTP 200) תאשר את קבלת ההתראה.

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

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

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

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

מגבלות

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

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

אמינות

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

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

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