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

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

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