איך עובדים עם אירועים מ-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 ( תצוגה מקדימה למפתחים) רק מרחבים
אירועים נתמכים
  • הודעות
  • מועדון החברים
  • תגובות
  • רווח

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

רשימה של סוגי האירועים הנתמכים מופיעה במאמרי העזרה של Chat API בנושא spaceEvents.
פורמט האירוע הודעה של Google Cloud Pub/Sub, שעברה עיצוב בהתאם למפרט של CloudEvent. פרטים נוספים מופיעים במאמר בנושא המבנה של אירועים ב-Google Workspace. ‫Chat API resource ( 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 זמין במאמרי העזרה של ה-API של Google Workspace Events.

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

במקום לקבל את אירועי ההצטרפות בזמן שהם מתרחשים, אפליקציית 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.

הגבלות והתנהגויות של הצגת מודעות

מגבלות כלליות

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

מינויים של משתמשים

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

מינויים של לקוחות ( תצוגה מקדימה למפתחים)

במינויים של לקוחות, חלות המגבלות הבאות:

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

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

  • אירועים במרחבים: נשלחים רק אם האירוע מתקיים במרחב שמנוהל על ידי הארגון שלכם ב-Google Workspace.
  • אירועים של משתמשים: מועברים רק אם האירוע מתרחש אצל משתמש ששייך לארגון Google Workspace שלכם.

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

מרחבים שמנוהלים על ידי הארגון שלכם ב-Google Workspace

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

הפורמט של שם המשאב של אירוע במרחב הוא:

spaces/{spaceId}/spaceEvents/{spaceEventId}

מרחבים שמנוהלים על ידי ארגונים חיצוניים

אם חלים שינויים בחברות של משתמש שמנוהל על ידי הארגון שלכם ב-Google Workspace במרחב שמנוהל על ידי ארגון חיצוני (לדוגמה, מרחב חיצוני עם שם או צ'אט ישיר שנוצר על ידי משתמש חיצוני), המינוי שלכם מקבל את האירוע הזה כאירוע משתמש.

הפורמט של שם המשאב של אירוע משתמש הוא:

users/{userId}/userEvents/{userEventId}