איך עובדים עם אירועים מ-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, ומהו סוג האירוע שאפליקציית 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. משאב API של Chat ( spaces.spaceEvent)
נתוני אירוע מחרוזת בקידוד Base64 עם או בלי נתוני משאבים. לדוגמה, מטענים ייעודיים (payloads) מופיעים בקטע נתוני אירועים. מטען ייעודי (payload) של JSON שמכיל נתוני משאבים. חלק מסוגי האירועים כוללים רק שדות משאבים מסוימים. לדוגמה, מטענים ייעודיים (payloads) זמינים ב מאמרי העזרה.

לדוגמה: שליחת שאילתות לגבי אירועים של מועדון החברים של הערוץ או הרשמה לאירועים במרחב משותף

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

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

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

כדי לקבל אירועים בזמן אמת, אפליקציית Chat מפעילה את השיטה Google Workspace Event API subscriptions.create() כדי להירשם למרחב לכל סוגי האירועים במינוי. אחרי יצירת המינוי, אפליקציית 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 מפעילה את שיטת Chat API spaces.spaceEvents.list() אחרי שכל פעילויות החברות התרחשו, ומסננת את השאילתה כדי לזהות אירועים חדשים, מעודכנים ונמחקו. ה-Chat API מחזיר רשימה של spaceEvent משאבים שמייצגים כל אחד מהשינויים שמתבצעים במינוי. לאחר מכן אפליקציית Chat יכולה לעבד או להשיב על סמך הפעילות האחרונה, כמו פרסום הודעה שבועית עם סיכום פעילות החברות במרחב ב-7 הימים האחרונים.

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

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