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

סקירה כללית

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

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

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

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

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

יצירת נושא

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

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

יצירת מינוי

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

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

ב-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, ומטען התעבורה בפועל של ההתראה ב-Gmail נמצא בשדה message.data. השדה message.data הוא מחרוזת בקידוד base64url שמפוענחת לאובייקט JSON שמכיל את כתובת האימייל ואת מזהה ההיסטוריה החדש של תיבת הדואר של המשתמש:

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

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

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

מענה להתראות

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

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

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

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

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

מגבלות

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

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

אמינות

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

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

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