בדף הזה מוסבר איך אפליקציות ל-Google Chat יכולות לקבל אירועים ב-Google Chat ולהגיב להם.
אירוע ב-Google Chat מייצג פעילות או שינוי ב-Chat, כמו הודעה חדשה במרחב משותף. האפליקציה ל-Chat יכולה להשתמש באירועים כדי להבין מה קרה ולבצע פעולה או להגיב בצורה שמועילה למשתמשים.
הנה כמה דוגמאות לשימוש באירועים:
- לעקוב אחרי הודעות חדשות במרחב המשותף ולהגיב להן, למשל לבדוק אם יש בהן מילות מפתח או ביטויים מסוימים.
- לשלוח הודעת פתיחה למשתמשים כשהם מצטרפים למרחב, כדי להסביר את ההנחיות של המרחב או לשתף טיפים לשימוש יעיל באפליקציה ל-Chat.
- לעקוב אחרי הפעילות ב-Chat ולנתח אותה. לדוגמה, כדי לשלוח דוח חודשי על רק הצטרפתי או על ההודעות שקיבלו הכי הרבה תגובות באמוג'י או תשובות.
- לתקשר בפלטפורמות שונות של הודעות. לדוגמה, המשתמשים יכולים לשלוח הודעות למשתמשים בפלטפורמה אחרת להעברת הודעות ולקבל מהם הודעות בלי לצאת מ-Chat.
איך אירועים פועלים
בכל פעם שקורה משהו ב-Google Chat, משאב של Google Chat API נוצר, מתעדכן או נמחק. אפליקציית Chat משתמשת באירועים כדי להעביר מידע על סוג הפעילות שהתרחשה ועל המשאב של Chat API שהושפע.
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 ( תצוגה מקדימה למפתחים) | רק מרחבים משותפים |
| אירועים נתמכים |
רשימה של סוגי האירועים הנתמכים מופיעה במאמר סוגי אירועים ליצירת מינויים במאמרי העזרה של Google Workspace Events API. |
רשימה של סוגי האירועים הנתמכים מופיעה במשאב spaceEvents במאמרי העזרה של Chat API.
|
| פורמט האירוע | הודעה של Google Cloud Pub/Sub, בפורמט בהתאם למפרט של CloudEvent. פרטים נוספים זמינים במאמר מבנה האירועים של Google Workspace. |
משאב של Chat API
(
spaces.spaceEvent)
|
| נתוני אירוע | מחרוזת בקידוד Base64 עם או בלי נתוני משאבים. בקטע נתוני אירועים מופיעות דוגמאות למטענים ייעודיים (payloads). | מטען ייעודי (payload) של JSON שמכיל נתוני משאבים. חלק מסוגי האירועים כוללים רק שדות מסוימים של משאבים. לדוגמאות של מטען ייעודי (payload), ראו את מאמרי העזרה. |
דוגמה: שליחת שאילתה או הרשמה לאירועים שקשורים לחברויות במרחב משותף
בדוגמה הזו, אפליקציה ל-Chat רוצה לקבל מידע על שינויים במשתתפים במרחב ב-Chat. במרחב המשותף, מתרחשת פעילות החברות הבאה:
- משתמש מצטרף למרחב המשותף, מה שיוצר משאב
Membershipומפעיל אירוע של רק הצטרפתי. - משתמש הופך למנהל מרחב משותף, מה שמעדכן את המשאב
Membershipשל המשתמש ומפעיל אירוע של עדכון חבר. - משתמש עוזב את המרחב המשותף, מה שמוחק את המשאב
Membershipשל המשתמש ומפעיל אירוע של מחיקת חבר.
קבלת עדכונים על אירועים שקשורים למינויים
כדי לקבל אירועים בזמן אמת, האפליקציה ל-Chat קוראת ל-method subscriptions.create() של Google Workspace Events API כדי להירשם למרחב המשותף לכל סוגי האירועים של החברים. אחרי שיוצרים את המינוי, האפליקציה ל-Chat יכולה להתחיל לקבל אירועים שקשורים למינויים.
באיור 2, לאפליקציית Chat יש מינוי פעיל למרחב, ולכן היא מקבלת אירוע בכל פעם שחלה במרחב הזה שינוי בחברות. האפליקציה ל-Chat יכולה לעבד את הפעילויות האלה או להגיב להן בזמן אמת, למשל לפרסם הודעת פתיחה פרטית למשתמש שהצטרף למרחב.
כדי ללמוד איך יוצרים מינויים באמצעות Google Workspace Events API, קראו את מאמרי העזרה של Google Workspace Events API.
שאילתה לגבי אירועי חברות מהזמן האחרון
במקום לקבל את אירועי החברות כשהם מתרחשים, אפליקציית 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}