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

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

אירוע ב-Google 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.
  • הודעות
  • מועדון החברים
  • תגובות
  • רווח

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

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

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

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

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

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

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

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