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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

משתתפ/ת

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

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

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

נקודת כניסה

אובייקטים של נקודת כניסה נושאים מידע על אמצעי הגישה הקיימים שיחת ועידה מסוימת, למשל בטלפון או בווידאו. המידע הזה נמצא ב אובייקט האירוע רק אם הנתונים קיימים באירוע ביומן התוסף מגדיר את addOns.calendar.currentEventAccess שלו מניפסט שדה ל 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"
  }
}