איך עובדים עם אירועים מ-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 Event API מאפשרת לכם לקבל אירועים בזמן שהם מתרחשים.
  • הרצת שאילתות על האירועים האחרונים באמצעות קריאה ל-Chat API.

בטבלה הבאה מוסבר מה ההבדל ומה הסיבות לשליחת שאילתות על אירועים או להרשמה אליהם:

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

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

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

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

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

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

הרשמה לאירועים של מועדון החברים

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

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

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

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

שאילתה לגבי אירועי חברות שהתרחשו לאחרונה

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

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

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

למידע על שליחת שאילתות על אירועים באמצעות Chat API, קראו את המאמר הצגת אירועים ממרחב משותף ב-Google Chat.

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