אובייקטים של אירוע

בדף הזה מוסבר על המבנה של אובייקטי אירועים בתוספים ל-Google Workspace.

אובייקטים של אירועים הם מבני JSON שנוצרים באופן אוטומטי ומועברים כפרמטרים כדי להפעיל פונקציות או פונקציות קריאה חוזרת (callbacks) כשמשתמש יוצר אינטראקציה עם תוסף. אובייקטים של אירועים מעבירים מידע מצד הלקוח על אפליקציית המארח וההקשר הנוכחי לפונקציית הקריאה החוזרת (callback) של התוסף בצד השרת.

תוספים של Google Workspace משתמשים באובייקטים של אירועים במקומות הבאים:

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

  אובייקטי האירועים שנוצרים כשהאירוע מופעל בדף הבית לא מכילים את כל השדות שכלולים בשני המקרים האחרים. השדות שקשורים לווידג'טים ולמידע לפי הקשר לא נכללים.

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

  • ב-Gmail יש טריגר הקשרי שמופעל כשמשתמש פותח הודעה וטריגר אחר שמופעל כשמשתמש כותב הודעה.
  • יומן Google מספק טריגר לפי הקשר כשמשתמש פותח אירוע.
  • Google Drive מספק טריגר לפי הקשר כשמשתמש בוחר קבצים ב-Drive.

  כשמתרחש טריגר לפי הקשר, אפליקציית המארח קוראת ל-runFunction התואם שמופיע במניפסט של התוסף, ומעבירה לו אובייקט אירוע כפרמטר. אובייקטי האירועים שנוצרים כשטריגרים לפי הקשר מופעלים מכילים את כל השדות שכלולים באובייקטי האירועים של טריגרים לדף הבית, וגם שדות שמכילים מידע לפי הקשר.

• פעולות של ווידג'טים. אובייקטים של אירועים משמשים גם כדי לספק אינטראקטיביות לווידג'ט, באמצעות אותו מודל פעולה שבו משתמשים התוספים של Gmail. התוספים ל-Google Workspace משתמשים באותן פונקציות של רכיבי ווידג'ט, באותם אובייקטים ובאותן תגובות לפעולות של Action. עם זאת, בתוספים של Google Workspace, אובייקטים של אירועי פעולה כוללים מידע נוסף שפונקציית ה-callback יכולה לפעול לפיו.

  אובייקטי האירועים שנוצרים כתוצאה מפעולות של ווידג'טים מכילים את כל השדות שכלולים באובייקטי אירועי הטריגר לפי הקשר, וגם שדות שמכילים מידע על הווידג'ט.

• טריגרים של תצוגה מקדימה של קישורים. ב-Google Docs, ב-Sheets וב-Slides, אפשר להגדיר תצוגות מקדימות של קישורים לשירותי צד שלישי על סמך דפוסי כתובות URL ספציפיים. כשמשתמשים יוצרים אינטראקציה עם קישור שתואם לדפוס, הטריגר linkPreviewTriggers מופעל ואובייקט אירוע שמכיל את הקישור מועבר לפונקציית ה-callback של הטריגר. התוסף יכול להשתמש באובייקט האירוע הזה כדי ליצור צ'יפ וחכמה שמציגים מידע על הקישור באפליקציית המארח. אפשר גם ליצור פעולות של ווידג'טים כדי לאפשר למשתמשים ליצור אינטראקציה עם כרטיס התצוגה המקדימה ועם התוכן שלו.

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

המבנה של אובייקט אירוע

בטבלה הבאה מתוארים המבנה ברמת העליונה של אובייקטי האירועים של התוספים ל-Google Workspace. המבנה של אובייקט האירוע כולל שדה ברמה העליונה commonEventObject למידע שלא תלוי במארח. לכל אובייקט אירוע יכול להיות גם אחד מהשדות הבאים ברמת העליונה שספציפיים למארח, בהתאם לאפליקציית המארח הפעילה: gmailEventObject,‏ calendarEventObject או driveEventObject.

כדי לשמור על תאימות לאחור, אובייקטי האירועים של התוספים של Google Workspace כוללים גם את כל השדות המקוריים שבהם נעשה שימוש באובייקטי אירועי הפעולה של התוספים של Gmail. השדות האלה מפורטים בטבלה שלמטה בקטע 'שדות התוסף המקוריים של Gmail'. המידע בשדות האלה מופיע במבנה האובייקט החדש.

אובייקט אירוע נפוץ

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

בנוסף לטריגרים של דף הבית ושל הקשר, התוספים יוצרים אובייקטים של אירועים ומעבירים אותם לפונקציות קריאה חוזרת (callback) של פעולות כשהמשתמש מבצע אינטראקציה עם ווידג'טים. פונקציית ה-callback של התוסף יכולה לשלוח שאילתה לאובייקט האירוע המשותף כדי לקבוע את התוכן של ווידג'טים פתוחים בלקוח של המשתמש. לדוגמה, התוסף יכול לאתר את הטקסט שהמשתמש הזין בווידג'ט TextInput באובייקט eventObject.commentEventObject.formInputs.

קלט של טופס לבחירת תאריך ושעה

פונקציות קריאה חוזרת של פעולות יכולות לקבל את הערכים הנוכחיים של הווידג'ט בשדה commonEventObject.formInputs. הנתונים האלה כוללים את ערכי התאריך או השעה שבחר המשתמש בווידג'טים של בוררי תאריך או שעה. עם זאת, המבנה של המידע משתנה בהתאם להגדרה של הווידג'ט כחלונית לבחירת תאריך ושעה, כחלונית לבחירת תאריך בלבד או כחלונית לבחירת שעה בלבד. ההבדלים המבניים מתוארים בטבלה הבאה:

אובייקט של אירוע ביומן

אובייקט האירוע ביומן הוא החלק באובייקט האירוע הכולל שנושא מידע על היומן של המשתמש ועל האירועים ביומן. הוא מופיע באובייקט אירוע רק אם אפליקציית המארח היא יומן Google.

בטבלה הבאה מפורטים השדות שקיימים בשדה calendarEventObject של אובייקט אירוע. שדות שמסומנים בתווית נתונים שנוצרו על ידי משתמשים נמצאים באובייקט האירוע רק אם הנתונים נמצאים באירוע ביומן Google, והתוסף מגדיר את השדה addOns.calendar.currentEventAccess manifest לערך READ או READ_WRITE.

משתתף/ת

אובייקטים של משתתפים מכילים מידע על משתתפים ספציפיים באירועים ביומן Google. המידע הזה מופיע באובייקט האירוע רק אם הנתונים נמצאים באירוע ביומן והתוסף מגדיר את השדה addOns.calendar.currentEventAccess manifest לערך READ או READ_WRITE.

נתוני שיחת ועידה

אובייקטים של נתוני ועידה מכילים מידע על כנסים שמצורפים לאירועים ביומן Google. אלה יכולים להיות פתרונות של Google לשיחות ועידה, כמו Google Meet, או פתרונות של צד שלישי. המידע הזה מופיע באובייקט האירוע רק אם הנתונים מופיעים באירוע ביומן, והתוסף מגדיר את השדה addOns.calendar.currentEventAccess manifest לערך READ או READ_WRITE.

נקודת כניסה

אובייקטים של נקודות כניסה מכילים מידע על אמצעי הגישה המוגדרים לועידה מסוימת, למשל בטלפון או בווידאו. המידע הזה מופיע באובייקט האירוע רק אם הנתונים מופיעים באירוע ביומן, והתוסף מגדיר את השדה addOns.calendar.currentEventAccess manifest לערך READ או READ_WRITE.

אובייקט אירוע ב-Drive

אובייקט האירוע ב-Drive הוא החלק באובייקט האירוע הכולל שמכיל מידע על Google Drive של המשתמש ועל התוכן שלו. הוא מופיע באובייקט אירוע רק אם אפליקציית המארח היא Google Drive.

פריט ב-Drive

אובייקטים של פריטים ב-Drive מכילים מידע על פריטים ספציפיים ב-Drive, כמו קבצים או תיקיות.

אובייקט אירוע ב-Gmail

אובייקט האירוע ב-Gmail הוא החלק באובייקט האירוע הכולל שנושא מידע על הודעות Gmail של משתמש. הוא מופיע באובייקט אירוע רק אם אפליקציית המארח היא Gmail.

אובייקט אירוע ב-Docs

אובייקט האירוע ב-Docs הוא החלק באובייקט האירוע הכולל שמכיל מידע על המסמך של המשתמש ועל התוכן שלו. הוא מופיע באובייקט אירוע רק אם אפליקציית המארח היא Google Docs.

"docs" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

אובייקט אירוע ב-Sheets

אובייקט האירוע ב-Sheets הוא החלק באובייקט האירוע הכולל שנושא מידע על המסמך של המשתמש ועל התוכן שלו. הוא מופיע באובייקט אירוע רק אם אפליקציית המארח היא Google Sheets.

"sheets" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

אובייקט אירוע ב-Slides

אובייקט האירוע ב-Slides הוא החלק באובייקט האירוע הכולל שנושא מידע על המסמך של המשתמש ועל התוכן שלו. הוא מופיע באובייקט אירוע רק אם אפליקציית המארח היא Google Slides.

"slides" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}