איך עובדים עם אירועים מ-Google Chat

בדף הזה מוסבר איך אפליקציות ל-Google Chat יכולות לקבל אירועים ב-Google Chat ולהגיב להם.

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

ריכזנו כאן כמה דוגמאות לשימוש באירועים:

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

איך אירועים פועלים

בכל פעם שמשהו קורה ב-Google Chat, נוצר, מתעדכן או נמחק משאב של Google Chat API. מערכת Chat משתמשת באירועים כדי לספק מידע לאפליקציית Chat על סוג הפעילות שהתרחשה ועל משאב Chat API שהושפע.

דוגמה לאופן שבו הודעה שפורסמה במרחב ב-Google Chat מפעילה אירוע.
איור 1. משתמש מפרסם הודעה במרחב ב-Chat, וכך נוצר משאב Message. ‫Chat יוצר אירוע שמכיל נתונים על ההודעה החדשה.

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

בטבלה הבאה אפשר לראות איך פעילות ב-Chat משפיעה על משאב קשור ב-Chat API, ואיזה סוג אירוע מקבלת אפליקציית Chat:

פעילות משאב Chat API סוג אירוע
משתמש מפרסם הודעה במרחב ב-Chat נוצר משאב Message. הודעה חדשה
משתמש הופך למנהל/ת של המרחב. משאב Membership עודכן. עדכון המינוי
משתמש מגיב להודעה. נוצר משאב Reaction. תגובה חדשה
משתמש עוזב מרחב. משאב Membership נמחק. המינוי נמחק

קבלת אירועים מ-Google Chat

כדי לקבל אירועים, אפליקציית Chat יכולה לבצע אחת מהפעולות הבאות:

  • כדי לקבל אירועים בזמן שהם מתרחשים, אפשר להירשם לאירועים באמצעות Google Workspace Events API.
  • שליחת שאילתה לגבי אירועים מהזמן האחרון באמצעות קריאה ל-Chat API.

בטבלה הבאה מוסבר ההבדל בין שאילתות על אירועים לבין הרשמה לאירועים, וגם הסיבות לשימוש בכל אחת מהאפשרויות:

הרשמה לעדכונים על אירועים שאילתה לגבי אירועים
תרחישים לדוגמה
  • לסיים את הטיפול באירועים או להגיב להם בזמן אמת.
  • מעקב אחרי פעילות החברות של המשתמשים וגילוי מרחבים חדשים למעקב.
  • לעבד אירועים או להגיב להם באופן תקופתי, או באמצעות טריגר.
  • אחזור אירועים שהוחמצו ממינוי (בגלל הפסקה זמנית בשירות או מינוי לא פעיל).
API Google Workspace Events API Chat API
מקור האירועים מרחבים ומשתמשים רק מרחבים
אירועים נתמכים
  • הודעות
  • מועדון החברים
  • תגובות
  • רווח

רשימה של סוגי האירועים הנתמכים מופיעה במאמר סוגי אירועים ליצירת מינויים בתיעוד של Google Workspace Events API.
  • הודעות
  • מועדון החברים
  • תגובות
  • רווח

רשימה של סוגי האירועים הנתמכים מופיעה במאמרי העזרה של Chat API בנושא spaceEvents.
פורמט האירוע הודעה של Google Cloud Pub/Sub, שעוצבה בהתאם למפרט של CloudEvent. פרטים נוספים מופיעים במאמר בנושא המבנה של אירועים ב-Google Workspace. משאב של Chat API ( spaces.spaceEvent)
נתוני אירוע מחרוזת בקידוד Base64 עם נתוני משאבים או בלי. דוגמאות למטענים ייעודיים (payload) זמינות במאמר בנושא נתוני אירועים. מטען ייעודי (payload) של JSON שמכיל נתוני משאבים. חלק מסוגי האירועים כוללים רק שדות מסוימים של משאבים. דוגמאות למטענים ייעודיים (payloads) מופיעות ב מאמרי העזרה.

דוגמה: שליחת שאילתה או הרשמה כמנוי לאירועים שקשורים למועדון חברים במרחב

בדוגמה הזו, אפליקציית Chat רוצה לקבל מידע על שינויים במשתתפים במרחב ב-Chat. במרחב, מתבצעת פעילות החברות הבאה:

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

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

כדי לקבל אירועים בזמן אמת, אפליקציית Chat קוראת לשיטה subscriptions.create() של Google Workspace Events API כדי להירשם למרחב לכל סוגי אירועי החברות. אחרי יצירת המינוי, אפליקציית Chat יכולה להתחיל לקבל אירועים שקשורים לחברות.

אפליקציית Chat שנרשמת לאירועים באמצעות Google Workspace Events API.
איור 2. אפליקציית Chat מקבלת אירועים שקשורים לחברות באמצעות מינוי ל-Google Workspace Events API.

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

מידע על יצירת מינויים באמצעות Google Workspace Events API זמין במסמכי התיעוד של Google Workspace Events API.

שליחת שאילתה לגבי אירועים שקשורים למינוי מהזמן האחרון

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

אפליקציית Chat ששולחת שאילתות לגבי אירועים באמצעות Chat API.
איור 3. אפליקציית Chat מקבלת אירועים עדכניים שקשורים לחברות במרחב על ידי שליחת שאילתה לגבי אירועים במרחב באמצעות Chat API.

באיור 3, אפליקציית Chat קוראת לשיטת Chat API spaces.spaceEvents.list() אחרי שכל פעילויות החברות התרחשו, ומסננת את השאילתה כדי למצוא אירועים חדשים, מעודכנים ומחוקים של חברות. ה-Chat API מחזיר רשימה של משאבי spaceEvent שמייצגים כל אחד מהשינויים בחברות. אחרי זה, אפליקציית Chat יכולה לעבד את הפעילות האחרונה או להגיב לה, למשל לפרסם הודעה שבועית עם סיכום של פעילות החברים במרחב ב-7 הימים האחרונים.

כדי לבצע שאילתה לגבי אירועים באמצעות Chat API, אפשר לעיין במאמר בנושא רשימת אירועים במרחב ב-Google Chat.

מגבלות
  • במינויים למשתמשים, אירועים שקשורים לחברים חדשים בצ'אטים ישירים או בצ'אטים קבוצתיים ללא שם (google.workspace.chat.membership.v1.created), מופעלים רק אחרי פרסום ההודעה הראשונה.
  • כדי לקבל אירועים שקשורים לחברות במרחב, המשתמש צריך להיות חבר ישיר במרחב. אם משתמש נוסף, מתעדכן או מוסר באופן עקיף ממרחב דרך קבוצה ב-Google, המינוי לא מקבל את אירועי החברות האלה. כדי להבין איך עובד החברות בקבוצות Google, אפשר לקרוא את המאמר בנושא צירוף קבוצות מ'קבוצות Google' למרחבים.