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

בדף הזה מוסבר על המבנה של אובייקטי אירועים בתוספים ל-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'. המידע בשדות האלה מופיע במבנה האובייקט החדש.

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

אובייקט אירוע
eventObject.commonEventObject	Common fields object אובייקט שמכיל מידע שכל אובייקטי האירועים מכילים, ללא קשר לאפליקציית המארח.
eventObject.calendar	Calendar event object השדה הזה מופיע רק אם המארח של השיחה הוא יומן Google. אובייקט שמכיל מידע על יומן ואירועים.
eventObject.chat	Chat event object גרסת Developer Preview: זמינה כחלק מתוכנית Developer Preview של Google Workspace, שמעניקה גישה מוקדמת לתכונות מסוימות. האפשרות הזו מוצגת רק אם המארח של השיחה הוא Google Chat. אובייקט שמכיל מידע על Chat.
eventObject.drive	Drive event object השדה הזה מופיע רק אם המארח הקורא הוא Google Drive. אובייקט שמכיל מידע על Drive.
eventObject.gmail	Gmail event object השדה הזה מופיע רק אם המארח של השיחה הוא Gmail. אובייקט שמכיל מידע מ-Gmail.
eventObject.docs	Docs event object השדה הזה מופיע רק אם המארח הקורא הוא Google Docs. אובייקט שמכיל מידע על Docs.
eventObject.sheets	Sheets event object השדה הזה מופיע רק אם המארח הקורא הוא Google Sheets. אובייקט שמכיל מידע מ-Sheets.
eventObject.slides	Slides event object השדה הזה מופיע רק אם המארח הקורא הוא Google Slides. אובייקט שמכיל מידע על Slides.
השדות המקוריים של התוסף ל-Gmail
eventObject.messageMetadata.accessToken	string התכונה הוצאה משימוש. טוקן גישה. אפשר להשתמש בזה כדי להפעיל גישה לנתוני משתמשים באמצעות היקפי גישה זמניים של תוספים ל-Gmail. בתוספים ל-Google Workspace, המידע הזה מופיע בשדה eventObject.gmail.accessToken.
eventObject.messageMetadata.messageId	string התכונה הוצאה משימוש. מזהה ההודעה של השרשור שנפתח בממשק המשתמש של Gmail. בתוספים ל-Google Workspace, המידע הזה מופיע בשדה eventObject.gmail.messageId.
eventObject.clientPlatform	string התכונה הוצאה משימוש. מציין את המקור של האירוע (אתר, iOS או Android). בתוספים ל-Google Workspace, המידע הזה מופיע בשדה eventObject.commonEventObject.platform.
eventObject.formInput	object התכונה הוצאה משימוש. מפה של הערכים הנוכחיים של כל הווידג'טים של הטפסים בכרטיס, מוגבלת לערך אחד לכל ווידג'ט. המפתחות הם מזהי המחרוזות שמשויכים לווידג'טים, והערכים הם מחרוזות. אובייקט האירוע מספק את formInput כנוחות כשצריך לקרוא נתונים מכמה ווידג'טים עם ערכים בודדים צפויים, כמו מפתחות ומקלדות טקסט. בווידג'טים עם ערכים מרובים, כמו תיבות סימון, אפשר לקרוא כל ערך מ-formInputs במקום זאת. הערה: לא ניתן לקרוא מהשדה הזה ערכים של ווידג'טים לבחירת תאריך ושעה. במקום זאת, צריך לקבל את הערכים של הבורר מ-commonEventObject.formInputs. בתוספים ל-Google Workspace, המידע הזה מופיע בשדה eventObject.commonEventObject.formInputs. ווידג'טים עם ערכים בודדים מיוצגים כמערכי רכיב יחיד.
eventObject.formInputs	object התכונה הוצאה משימוש. מפה של הערכים הנוכחיים של הווידג'טים בכרטיס, שמוצגים כרשימות של מחרוזות. המפתחות הם מזהי המחרוזות שמשויכים לווידג'ט. בווידג'טים עם ערך יחיד, הערך מוצג במערך עם רכיב יחיד. בווידג'טים עם ערכים מרובים, כמו קבוצות של תיבות סימון, כל הערכים מוצגים ברשימה. הערה: לא ניתן לקרוא מהשדה הזה ערכים של ווידג'טים לבחירת תאריך ושעה. במקום זאת, צריך לקבל את הערכים של הבורר מ-commonEventObject.formInputs. בתוספים ל-Google Workspace, המידע הזה מופיע בשדה eventObject.commonEventObject.formInputs.
eventObject.parameters	object התכונה הוצאה משימוש. מפה של כל הפרמטרים הנוספים שמספקים ל- Action באמצעות Action.setParameters(). המפתחות והערכים במפה הם מחרוזות. בתוספים ל-Google Workspace, המידע הזה מופיע בשדה eventObject.commonEventObject.parameters.
eventObject.userCountry	string האפשרות הזו הוצאה משימוש ומושבתת כברירת מחדל. הקוד בן שתי האותיות שמציין את המדינה או האזור של המשתמש. הוא יכול להיות גם קוד מדינה מספרי לפי UN M49. בתוספים ל-Google Workspace, המידע הזה מופיע בשדה eventObject.commonEventObject.userLocale.
eventObject.userLocale	string האפשרות הזו הוצאה משימוש ומושבתת כברירת מחדל. קוד ISO 639 בן שתי אותיות שמציין את השפה של המשתמש. פרטים נוספים זמינים במאמר גישה לאזור ולשעון המקומיים של המשתמש. בתוספים ל-Google Workspace, המידע הזה מופיע בשדה eventObject.commonEventObject.userLocale.
eventObject.userTimezone.id	string האפשרות הזו הוצאה משימוש ומושבתת כברירת מחדל. מזהה אזור הזמן של אזור הזמן של המשתמש. לדוגמה: America/New_York, Europe/Vienna ו- Asia/Seoul. לפרטים נוספים, ראו גישה לאזור הזמן ולשפה של המשתמש. בתוספים ל-Google Workspace, המידע הזה מופיע בשדה eventObject.commonEventObject.timeZone.id.
eventObject.userTimezone.offset	string האפשרות הזו הוצאה משימוש ומושבתת כברירת מחדל. הסטייה של אזור הזמן של המשתמש מזמן אוניברסלי מתואם (UTC), שנמדדת במיליוניות השנייה. לפרטים נוספים, ראו גישה לאזור הזמן ולשפה של המשתמש. בתוספים ל-Google Workspace, המידע הזה מופיע בשדה eventObject.commonEventObject.timeZone.offset.

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

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

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

שדות נפוצים באובייקט אירוע
commonEventObject.platform	string המקום שממנו הגיע האירוע ('אתר', 'iOS' או 'Android').
commonEventObject.formInputs	object מפה שמכילה את הערכים הנוכחיים של הווידג'טים בכרטיס המוצג. מפתחות המפה הם מזהי המחרוזות שהוקצו לכל ווידג'ט. המבנה של אובייקט ערך המפה תלוי בסוג הווידג'ט: הדוגמאות הבאות מותאמות לסביבת זמן הריצה V8 של Apps Script. אם משתמשים בסביבת זמן הריצה של Rhino, צריך להוסיף את הערך [""] אחרי הערך. לדוגמה, במקום e.commonEventObject.formInputs.employeeName.stringInputs.value[0], צריך לעצב את אובייקט האירוע בתור e.commonEventObject.formInputs.employeeName[""].stringInputs.value[0]. מידע נוסף על סביבות זמן ריצה ב-Apps Script זמין במאמר סקירה כללית על זמן הריצה של V8. ווידג'טים עם ערך יחיד (למשל, תיבת טקסט): רשימת מחרוזות (רק אלמנט אחד). דוגמה: כדי לגשת לערך הקלט של ווידג'ט של קלט טקסט שמזהה שלו הוא employeeName, צריך להשתמש בקוד: e.commonEventObject.formInputs.employeeName.stringInputs.value[0] ווידג'טים עם ערכים מרובים (לדוגמה, קבוצות של תיבות סימון): רשימה של מחרוזות. דוגמה: בווידג'ט עם מספר ערכים שמזהה שלו הוא participants, ניגשים למערך הערכים באמצעות: e.commonEventObject.formInputs.participants.stringInputs.value. A date-time picker: DateTimeInput object. דוגמה: כדי לגשת לאובייקט DateTimeInput של בורר עם המזהה myDTPicker, משתמשים ב-e.commonEventObject.formInputs.myDTPicker.dateTimeInput. A date-only picker: DateInput object. דוגמה: כדי לגשת לאובייקט DateInput של בורר עם המזהה myDatePicker, משתמשים ב-e.commonEventObject.formInputs.myDatePicker.dateInput. A time-only picker: TimeInput object. דוגמה: כדי לגשת לאובייקט TimeInput של בורר עם המזהה myTimePicker, משתמשים ב-e.commonEventObject.formInputs.myTimePicker.timeInput.
commonEventObject.hostApp	string האפליקציה המארחת שבה התוסף פעיל בזמן יצירת אובייקט האירוע. הערכים האפשריים כוללים: GMAIL CALENDAR DRIVE DOCS SHEETS SLIDES
commonEventObject.parameters	object פרמטרים נוספים שמספקים לפעולה באמצעות actionParameters או Action.setParameters(). תצוגה מקדימה למפתחים: בתוספים שמרחיבים את Google Chat, כדי להציע פריטים על סמך מה שהמשתמשים מקלידים בתפריטי בחירה מרובה, משתמשים בערך של המפתח "autocomplete_widget_query" (event.commonEventObject.parameters["autocomplete_widget_query"]). אפשר להשתמש בערך הזה כדי לשלוח שאילתה למסד נתונים ולהציע למשתמשים פריטים לבחירה בזמן שהם מקלידים. פרטים נוספים זמינים במאמר איסוף ועיבוד מידע ממשתמשי Google Chat.
commonEventObject.userLocale	string מושבתת כברירת מחדל. השפה והמזהה של המדינה או האזור של המשתמש בפורמט של קוד השפה ISO 639 וקוד המדינה או האזור ISO 3166. לדוגמה, en-US. כדי להפעיל את השדה הזה, צריך להגדיר את addOns.common.useLocaleFromApp לערך true במניפסט של התוסף. רשימת ההיקף של התוסף חייבת לכלול גם את https://www.googleapis.com/auth/script.locale. פרטים נוספים זמינים במאמר גישה לאזור הזמן ולשפה של המשתמש.
commonEventObject.timeZone	string מושבתת כברירת מחדל. מזהה אזור הזמן וההיסט שלו. כדי להפעיל את השדה הזה, צריך להגדיר את הערך של addOns.common.useLocaleFromApp ל-true במניפסט של התוסף. רשימת ההיקף של התוסף חייבת לכלול גם את הערך https://www.googleapis.com/auth/script.locale. פרטים נוספים זמינים במאמר גישה לאזור הזמן ולשפה של המשתמש.
commonEventObject.timeZone.id	string מזהה אזור הזמן של אזור הזמן של המשתמש. לדוגמה: America/New_York, Europe/Vienna ו- Asia/Seoul. כדי להפעיל את השדה הזה, צריך להגדיר את הערך של addOns.common.useLocaleFromApp ל-true במניפסט של התוסף. רשימת ההיקף של התוסף חייבת לכלול גם את הערך https://www.googleapis.com/auth/script.locale. פרטים נוספים זמינים במאמר גישה לאזור הזמן ולשפה של המשתמש.
commonEventObject.timeZone.offset	string ה היסט הזמן מאזור הזמן של שעון UTC, שנמדד באלפיות השנייה. פרטים נוספים זמינים במאמר גישה לאזור הזמן ולשפה של המשתמש.

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

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

אובייקט DateTimeInput
dateTimeInput.hasDate	boolean true אם תאריך השעה שהוזן כולל תאריך, ואם false כולל רק שעה.
dateTimeInput.hasTime	boolean true אם זמן התאריך שהוזן כולל שעה, ואם false כולל רק תאריך.
dateTimeInput.msSinceEpoch	string השעה שנבחרה על ידי המשתמש, באלפיות שנייה מאז תחילת הזמן (00:00:00 UTC ב-1 בינואר 1970).
אובייקט DateInput
dateInput.msSinceEpoch	string השעה שנבחרה על ידי המשתמש, באלפיות שנייה מאז תחילת הזמן (00:00:00 UTC ב-1 בינואר 1970).
אובייקט TimeInput
timeInput.hours	number מספר השעה שנבחר על ידי המשתמש.
timeInput.minutes	number מספר הדקה שנבחר על ידי המשתמש.

אובייקט של אירוע צ'אט

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

צ'אט
chat.user	object (User) משתמש Chat שביצע אינטראקציה עם אפליקציית Chat.
chat.space	object (Space) המרחבים המשותפים ב-Chat שבהם משתמשים קיימו אינטראקציה עם אפליקציית Chat.
chat.eventTime	string (Timestamp format) השעה שבה התרחשה האינטראקציה.
שדה האיחוד payload. הערך של payload יכול להיות רק אחת מהאפשרויות הבאות:
chat.messagePayload	object (MessagePayload) עומס העבודה שאפליקציות Chat מקבלות מטריגר Message.
chat.addedToSpacePayload	object (AddedToSpacePayload) נתוני העומס שמוצגים לאפליקציות Chat מהטריגר נוסף למרחב המשותף.
chat.removedFromSpacePayload	object (RemovedFromSpacePayload) נתוני העומס שכל אפליקציית Chat מקבלת מטריגר הוסרה מהמרחב המשותף.
chat.buttonClickedPayload	object (ButtonClickedPayload) עומס העבודה שאפליקציות Chat מקבלות כשמשתמשים לוחצים על לחצן בהודעה או בכרטיס. אם משתמש לוחץ על לחצן לשליחת מידע, האובייקט commonEventObject.formInputs מכיל את הערכים שנאספו מהמשתמש. למידע נוסף, ראו איסוף מידע ממשתמשים ב-Google Chat.
chat.widgetUpdatedPayload	object (WidgetUpdatedPayload) נתוני העומס שאותם מקבלות אפליקציות Chat כשמשתמשים מקלידים טקסט בתפריט הבחירה בכמה פריטים של ווידג'ט selectionInput. אפליקציות צ'אט יכולות להשתמש באובייקט האירוע הזה כדי לאכלס הצעות לפריטים ממקור נתונים דינמי. לדוגמה, כדי לאכלס בקשות תמיכה ממקור נתונים חיצוני, אפליקציית Chat יכולה לשלוח שאילתה למקור הנתונים על סמך מה שהמשתמש מקלידים בתפריט, ואז להציג את בקשות התמיכה התואמות כפריטים לבחירה. האובייקט CommonEventObject.parameters['autocomplete_widget_query'] מכיל את ערך המחרוזת שהמשתמש מקלידים בתפריט.
chat.appCommandPayload	object (AppCommandPayload) עומס העבודה שאפליקציות Chat מקבלות כשמשתמש משתמש בפקודה מאפליקציית Chat.

מטען ייעודי

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

מטען ייעודי (payload) של הודעה

MessagePayload
chat.messagePayload.message	object (Message) הודעה ב-Chat שהפעילה את האירוע.
chat.messagePayload.space	object (Space) המרחבים ב-Chat שבהם משתמש שלח את ההודעה שהפעילה את אפליקציית Chat.
chat.messagePayload.configCompleteRedirectUri	string כתובת ה-URL שאליה אפליקציית Chat צריכה להפנות את המשתמש אחרי שהוא משלים תהליך הרשאה או תהליך הגדרה מחוץ ל-Google Chat. מידע נוסף זמין במאמר חיבור התוסף של Google Workspace לשירות של צד שלישי.

נוסף למטען הייעודי לחלל

AddedToSpacePayload
chat.addedToSpacePayload.space	object (Space) המרחבים המשותפים ב-Chat שהמשתמש הוסיף או התקין בהם את אפליקציית Chat. כשאדמינים מתקינים אפליקציות ל-Chat, השדה space.adminInstalled מוגדר ל-true.
chat.addedToSpacePayload.interactionAdd	boolean האם משתמש הוסיף את אפליקציית Chat למרחב המשותף באמצעות הודעה. לדוגמה, להשתמש ב-@mention של אפליקציית Chat או להשתמש בפקודה. אם true, מערכת Chat שולחת אובייקט אירוע נוסף עם messagePayload שמכיל מידע על ההודעה.
chat.addedToSpacePayload.configCompleteRedirectUri	string כתובת ה-URL שאליה אפליקציית Chat צריכה להפנות את המשתמש אחרי שהוא משלים תהליך הרשאה או תהליך הגדרה מחוץ ל-Google Chat. מידע נוסף זמין במאמר חיבור התוסף של Google Workspace לשירות של צד שלישי.

הוסר ממטען החלל

RemovedFromSpacePayload
chat.removedFromSpacePayload.space	object (Space) מרחב Chat שממנו המשתמש הסיר או ה uninstall את אפליקציית Chat. כשאדמינים מסירים אפליקציות ל-Chat, השדה space.adminInstalled מוגדר ל-false.

עומס נתונים של לחיצה על כפתור

ButtonClickedPayload
chat.buttonClickedPayload.message	object (Message) הודעת Chat שמכילה את הלחצן שעליו המשתמש לחץ.
chat.buttonClickedPayload.space	object (Space) המרחבים המשותפים ב-Chat שבהם המשתמש לחץ על לחצן בהודעה באפליקציית Chat.
chat.buttonClickedPayload.isDialogEvent	boolean האפשרות הזו מציינת אם המשתמש לחץ על הכפתור כדי ליצור אינטראקציה עם תיבת דו-שיח.
chat.buttonClickedPayload.dialogEventType	enum (DialogEventType) אם הערך של isDialogEvent הוא true, סוג האינטראקציה בתיבת דו-שיח.
טיפוס enum‏ DialogEventType. הערך של dialogEventType יכול להיות רק אחד מהערכים הבאים:
TYPE_UNSPECIFIED	ערך ברירת המחדל. לא צוין.
REQUEST_DIALOG	משתמש מבקש תיבת דו-שיח. לדוגמה, הם משתמשים בפקודה או לוחצים על לחצן בהודעה.
SUBMIT_DIALOG	משתמש לוחץ על אלמנט אינטראקטיבי בתוך תיבת דו-שיח. לדוגמה, משתמש ממלא פרטים בתיבת דו-שיח ולוחץ על לחצן כדי לשלוח את הפרטים.

מטען נתונים מעודכן של הווידג'ט

WidgetUpdatedPayload
chat.widgetUpdatedPayload.space	object (Space) המרחבים ב-Chat שבהם התרחשה האינטראקציה.

המטען של פקודת האפליקציה

AppCommandPayload
chat.appCommandPayload.appCommandMetadata	object (AppCommandMetadata) מטא-נתונים על הפקודה שבה המשתמש השתמש ועל האופן שבו הוא הפעיל אותה.
chat.appCommandPayload.space	object (Space) מרחב העבודה ב-Chat שבו משתמש השתמש בפקודה.
chat.appCommandPayload.thread	object (Thread) אם האינטראקציה התרחשה בשרשור, השרשור ב-Chat שבו המשתמש השתמש בפקודה.
chat.appCommandPayload.message	object (Message) בפקודות דרך שורת הפקודה, ההודעה שמכילה את הפקודה דרך שורת הפקודה.
chat.appCommandPayload.configCompleteRedirectUri	string אם נדרשת הרשאה או הגדרה לפקודה, כתובת URL להפניה אוטומטית של המשתמש אליה אחרי השלמת התהליך מחוץ ל-Google Chat.
chat.appCommandPayload.isDialogEvent	boolean האם הפקודה פותחת תיבת דו-שיח.
chat.appCommandPayload.dialogEventType	enum (DialogEventType) סוג האינטראקציה עם תיבת דו-שיח.
טיפוס enum‏ DialogEventType. הערך של dialogEventType יכול להיות רק אחד מהערכים הבאים:
TYPE_UNSPECIFIED	ערך ברירת המחדל. לא צוין.
REQUEST_DIALOG	משתמש מבקש תיבת דו-שיח. לדוגמה, הם משתמשים בפקודה או לוחצים על לחצן בהודעה.
SUBMIT_DIALOG	משתמש לוחץ על אלמנט אינטראקטיבי בתוך תיבת דו-שיח. לדוגמה, משתמש ממלא פרטים בתיבת דו-שיח ולוחץ על לחצן כדי לשלוח את הפרטים.

מטא-נתונים של פקודות באפליקציה

AppCommandMetadata
chat.appCommandPayload.appCommandMetadata.appCommandId	string (int64 format) מזהה הפקודה.
chat.appCommandPayload.appCommandMetadata.appCommandType	enum (AppCommandType) סוג הפקודה.
טיפוס enum‏ AppCommandType. הערך של AppCommandType יכול להיות רק אחד מהערכים הבאים:
APP_COMMAND_TYPE_UNSPECIFIED	ערך ברירת המחדל. לא צוין.
SLASH_COMMAND	כדי להשתמש בפקודה, משתמשים שולחים הודעה שמתחילה בקו נטוי /.
QUICK_COMMAND	המשתמש בוחר את הפקודה מתפריט Chat באזור התשובה להודעה.

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

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

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

הערה: לרבים מהשדות באובייקט הזה ובמבנים המשניים שלו יש מיפוי ישיר לשדות באותו שם במשאב האירוע של Calendar API. אם תיאורי השדות שונים, המידע בטבלה הבאה נכון.

אובייקט של אירוע ביומן
calendar.attendees[]	list of attendee objects נתונים שנוצרו על ידי משתמשים רשימת המשתתפים באירוע ביומן.
calendar.calendarId	string מזהה היומן.
calendar.capabilities	object נתונים שנוצרו על ידי משתמשים. אובייקט שמתאר את היכולות של התוסף להציג או לעדכן את פרטי האירוע.
calendar.capabilities.canAddAttendees	boolean נתונים שנוצרו על ידי משתמשים. true אם התוסף יכול להוסיף משתתפים חדשים לרשימת המשתתפים באירוע; false אחרת.
calendar.capabilities.canSeeAttendees	boolean נתונים שנוצרו על ידי משתמשים. true אם התוסף יכול לקרוא את רשימת המשתתפים באירוע, false אחרת.
calendar.capabilities.canSeeConferenceData	boolean נתונים שנוצרו על ידי משתמשים. true אם התוסף יכול לקרוא את נתוני האירוע, false אחרת.
calendar.capabilities.canSetConferenceData	boolean נתונים שנוצרו על ידי משתמשים. true אם התוסף יכול לעדכן את נתוני האירוע של שיחת הוועידה, false אחרת.
calendar.capabilities.canAddAttachments	boolean נתונים שנוצרו על ידי משתמשים. true אם התוסף יכול להוסיף קבצים חדשים לאירוע; false במקרה אחר.
calendar.conferenceData	Conference data object נתונים שנוצרו על ידי משתמשים אובייקט שמייצג את כל נתוני הוועידה שמשויכים לאירוע הזה, כמו פרטי הוועידה ב-Google Meet.
calendar.id	string מזהה האירוע.
calendar.organizer	object אובייקט שמייצג את מארגן האירוע.
calendar.organizer.email	string כתובת האימייל של מארגן האירוע.
calendar.recurringEventId	string המזהה של אירוע חוזר.

משתתף/ת

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

אובייקט של משתתף
attendee.additionalGuests	number מספר האורחים הנוספים שהמשתתף ציין שהוא מביא. ברירת המחדל היא אפס.
attendee.comment	string התגובה של המשתתף, אם יש כזו.
attendee.displayName	string השם המוצג של המשתתף.
attendee.email	string כתובת האימייל של המשתתף.
attendee.optional	boolean true אם ההשתתפות של המשתתף הזה מסומנת כאופציונלית, אחרת false.
attendee.organizer	boolean true אם המשתתף הוא מארגן של האירוע.
attendee.resource	boolean true אם המשתתף מייצג משאב, כמו חדר או ציוד. false במקרים אחרים.
attendee.responseStatus	string סטטוס התשובה של המשתתף/ת. הערכים האפשריים הם: accepted: המשתתף או המשתתפת אישרו את ההזמנה לאירוע. declined: המשתתף דחה את ההזמנה לאירוע. needsAction: המשתתף לא ענה להזמנה לאירוע. tentative: המשתתף או המשתתפת אישרו באופן זמני את ההזמנה לאירוע.
attendee.self	boolean true אם המשתתף הזה מייצג את היומן שבו מופיע האירוע, אחרת false.

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

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

אובייקט נתונים של שיחת ועידה
conferenceData.conferenceId	string המזהה של שיחת הוועידה. המזהה הזה נועד לאפשר לאפליקציות לעקוב אחרי כנסים. אין להציג את המזהה הזה למשתמשים.
conferenceData.conferenceSolution	object אובייקט שמייצג את פתרון הווידאו, למשל Hangouts או Google Meet.
conferenceData.conferenceSolution.iconUri	string ה-URI של הסמל שגלוי למשתמשים ומייצג את הפתרון הזה לשיחות ועידה.
conferenceData.conferenceSolution.key	object המפתח שמזהה באופן ייחודי את פתרון הכנס של האירוע הזה.
conferenceData.conferenceSolution.key.type	string סוג הפתרון לשיחות ועידה. הערכים האפשריים הם: eventHangout ל-Hangouts לצרכנים (http://hangouts.google.com). eventNamedHangout לגרסה הקלאסית של Hangouts למשתמשים ב-Google Workspace‏ (http://hangouts.google.com). hangoutsMeet ל-Google Meet (http://meet.google.com).
conferenceData.conferenceSolution.name	string השם של פתרון הווידאוקונפרציה שגלוי למשתמשים (לא מותאם לשפה).
conferenceData.entryPoints[]	list of entry point objects הרשימה של נקודות הכניסה לפגישה, כמו כתובות URL או מספרי טלפון.
conferenceData.notes	string הערות נוספות (כמו הוראות מהאדמין של הדומיין או הודעות משפטיות) לגבי הכינוס שיוצגו למשתמש. יכול להכיל HTML. האורך המקסימלי הוא 2,048 תווים.
conferenceData.parameters	object אובייקט שמכיל מפה של נתוני הפרמטרים שהוגדרו לשימוש התוסף.
conferenceData.parameters.addOnParameters	object מפה של מפתחות וערכים של מחרוזות פרמטרים. המפתחות והערכים האלה מוגדרים על ידי מפתח התוסף כדי לצרף מידע לפגישה ספציפית לשימוש בתוסף.

נקודת כניסה

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

אובייקט של נקודת כניסה
entryPoint.accessCode	string קוד הגישה שמשמש לגישה לכנס. האורך המקסימלי הוא 128 תווים. בדרך כלל, ספקי כנסים משתמשים רק בקבוצת משנה של {accessCode, meetingCode, passcode, password, pin} כדי לספק גישה לכנסים. להתאים ולהציג רק את השדות שבהם משתמש ספק הכנס.
entryPoint.entryPointFeatures	list מאפייני נקודת הכניסה. בשלב הזה, התכונות האלה חלות רק על נקודות הכניסה של phone: toll: נקודת הכניסה היא שיחת טלפון בתשלום. toll_free: נקודת הכניסה היא שיחת טלפון ללא חיוב.
entryPoint.entryPointType	string סוג נקודת הכניסה. הערכים האפשריים הם: more: הוראות נוספות להצטרפות לפגישה, כמו מספרי טלפון חלופיים. לכל ועידה יכולה להיות רק נקודת כניסה אחת מסוג more. אם נקודת כניסה מסוג more קיימת, צריך גם לצרף לפחות נקודת כניסה מסוג אחר. phone: הצטרפות לכנס באמצעות מספר טלפון. לשיחת ועידה יכולות להיות אפס נקודות כניסה מסוג phone או יותר. יומן Google מציג רק את שתי נקודות הכניסה הראשונות בטלפון, אחרי עיצוב ומיון לפי סדר אלפביתי. sip: הצטרפות לפגישה דרך SIP. לכל כנס יכולה להיות נקודת כניסה אחת sip לכל היותר. video: הצטרפות לפגישה דרך HTTP. לכל כנס יכולה להיות נקודת כניסה אחת video לכל היותר.
entryPoint.label	string התווית הגלויה למשתמש של ה-URI של נקודת הכניסה (לא מותאמת לשפה).
entryPoint.meetingCode	string קוד הפגישה שמשמש לגישה לכנס. האורך המקסימלי הוא 128 תווים. בדרך כלל, ספקי כנסים משתמשים רק בקבוצת משנה של {accessCode, meetingCode, passcode, password, pin} כדי לספק גישה לכנסים. להתאים ולהציג רק את השדות שבהם משתמש ספק הכנס.
entryPoint.passcode	string קוד הגישה שמשמשים כדי לגשת לפגישה. האורך המקסימלי הוא 128 תווים. בדרך כלל, ספקי כנסים משתמשים רק בקבוצת משנה של {accessCode, meetingCode, passcode, password, pin} כדי לספק גישה לכנסים. להתאים ולהציג רק את השדות שבהם משתמש ספק הכנס.
entryPoint.password	string הסיסמה שבה משתמשים כדי לגשת לכנס. האורך המקסימלי הוא 128 תווים. בדרך כלל, ספקי כנסים משתמשים רק בקבוצת משנה של {accessCode, meetingCode, passcode, password, pin} כדי לספק גישה לכנסים. להתאים ולהציג רק את השדות שבהם משתמש ספק הכנס.
entryPoint.pin	string קוד האימות שמשמש לגישה לוועידה. האורך המקסימלי הוא 128 תווים. בדרך כלל, ספקי כנסים משתמשים רק בקבוצת משנה של {accessCode, meetingCode, passcode, password, pin} כדי לספק גישה לכנסים. להתאים ולהציג רק את השדות שבהם משתמש ספק הכנס.
entryPoint.regionCode	string קוד האזור של מספר הטלפון. המשתמשים זקוקים לה אם ה-URI לא כולל קידומת מדינה. הערכים מבוססים על רשימת קודי האזורים הציבורית של CLDR.
entryPoint.uri	string ה-URI של נקודת הכניסה. האורך המקסימלי הוא 1,300 תווים. הפורמט תלוי בסוג נקודת הכניסה: more: נדרשת סכימה מסוג http: או https:. phone: נדרש סכימה של tel:. ה-URI צריך לכלול את כל רצף החיוג (לדוגמה, "tel:‎[phone],,,12345678;1234"). sip: נדרשת סכימה מסוג sip: או sips:. לדוגמה, "sip:[e-mail]". video: נדרשת סכימה מסוג http: או https:.

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

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

אובייקט אירוע ב-Drive
drive.activeCursorItem	Drive item object הפריט ב-Drive שפועל כרגע.
drive.selectedItems[]	list of Drive item objects רשימה של פריטים (קבצים או תיקיות) שנבחרו ב-Drive.

פריט ב-Drive

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

אובייקט של פריט ב-Drive
item.addonHasFileScopePermission	boolean אם הערך הוא true, התוסף ביקש והתקבלה לו הרשאה ברמת https://www.googleapis.com/auth/drive.file לפריט הזה. אחרת, השדה הזה יהיה false. אם התוסף משתמש בהיקף מורשה יותר, כמו https://www.googleapis.com/auth/drive או https://www.googleapis.com/auth/drive.readonly, השדה הזה לא רלוונטי. תמיד צריך להשתמש בהיקפי הרשאה הכי מצומצמים שאפשר כשמתכננים תוספים כדי להגן על פרטי המשתמשים.
item.id	string המזהה של הפריט שנבחר.
item.iconUrl	string כתובת ה-URL של הסמל שמייצג את הפריט שנבחר.
item.mimeType	string סוג ה-MIME של הפריט שנבחר.
item.title	string השם של הפריט שנבחר.

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

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

אובייקט אירוע ב-Gmail
gmail.accessToken	string טוקן הגישה הספציפי ל-Gmail. אפשר להשתמש באסימון הזה עם השיטה GmailApp.setCurrentMessageAccessToken(accessToken) כדי לתת לתוסף גישה זמנית להודעת Gmail הפתוחה של המשתמש, או לאפשר לתוסף לכתוב טיוטות חדשות.
gmail.bccRecipients[]	list of strings מושבתת כברירת מחדל. רשימת כתובות האימייל של נמעני 'עותק מוסתר:' שכלולות כרגע בטיוטה שהתוסף יוצר. כדי להפעיל את השדה הזה, צריך להגדיר את השדה addOns.gmail.composeTrigger.draftAccess במניפסט לערך METADATA.
gmail.ccRecipients[]	list of strings מושבתת כברירת מחדל. רשימת כתובות האימייל של הנמענים ב'עותק' שכלולות כרגע בטיוטה שהתוסף יוצר. כדי להפעיל את השדה הזה, צריך להגדיר את השדה addOns.gmail.composeTrigger.draftAccess במניפסט לערך METADATA.
gmail.messageId	string המזהה של ההודעה ב-Gmail שנפתחת כרגע.
gmail.threadId	string מזהה השרשור הפתוח כרגע ב-Gmail.
gmail.toRecipients[]	list of strings מושבתת כברירת מחדל. רשימת כתובות האימייל של הנמענים בשדה 'אל' שכלולים כרגע בטיוטה שהתוסף יוצר. כדי להפעיל את השדה הזה, צריך להגדיר את השדה addOns.gmail.composeTrigger.draftAccess במניפסט לערך METADATA.

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

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

אובייקט אירוע ב-Docs
docs.id	string השדה הזה מופיע רק אם המשתמש העניק הרשאה להיקף https://www.googleapis.com/auth/drive.file. המזהה של המסמך הפתוח בממשק המשתמש של Docs.
docs.title	string השדה הזה מופיע רק אם המשתמש העניק הרשאה להיקף https://www.googleapis.com/auth/drive.file. השם של המסמך שנפתח בממשק המשתמש של Docs.
docs.addonHasFileScopePermission	boolean אם הערך הוא true, המשמעות היא שהתוסף ביקש והתקבלה לו הרשאת היקף https://www.googleapis.com/auth/drive.file למסמך שנפתח בממשק המשתמש של Docs. אחרת, הערך בשדה הזה הוא false.
docs.matchedUrl.url	string השדה הזה מופיע רק אם מתקיימים התנאים הבאים: https://www.googleapis.com/auth/workspace.linkpreview אושר על ידי המשתמש. כתובת ה-URL תואמת לתבנית המארח שצוינה בטריגר LinkPreviewTriggers. כתובת ה-URL של הקישור שיוצר תצוגה מקדימה ב-Google Docs. כדי להשתמש בשדה הזה, צריך להגדיר את LinkPreviewTriggers במניפסט של התוסף. פרטים נוספים זמינים במאמר תצוגה מקדימה של קישורים באמצעות צ'יפים חכמים. דוגמה לעומס נתונים כשמשתמש מציג תצוגה מקדימה של הקישור https://www.example.com/12345: "docs" : { "matchedUrl" : { "url" : "https://www.example.com/12345" } }

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

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

אובייקט אירוע ב-Sheets
sheets.id	string השדה הזה מופיע רק אם המשתמש העניק הרשאה להיקף https://www.googleapis.com/auth/drive.file. המזהה של הגיליון האלקטרוני שנפתח בממשק המשתמש של Sheets.
sheets.title	string השדה הזה מופיע רק אם המשתמש העניק הרשאה להיקף https://www.googleapis.com/auth/drive.file. השם של הגיליון האלקטרוני שנפתח בממשק המשתמש של Sheets.
sheets.addonHasFileScopePermission	boolean אם הערך הוא true, התוסף ביקש והתקבלה לו הרשאת היקף https://www.googleapis.com/auth/drive.file לגיליון האלקטרוני שנפתח בממשק המשתמש של Sheets. אחרת, הערך בשדה הזה הוא false.
sheets.matchedUrl.url	string השדה הזה מופיע רק אם מתקיימים התנאים הבאים: https://www.googleapis.com/auth/workspace.linkpreview אושר על ידי המשתמש. כתובת ה-URL תואמת לתבנית המארח שצוינה בטריגר LinkPreviewTriggers. כתובת ה-URL של הקישור שיוצר תצוגה מקדימה ב-Google Sheets. כדי להשתמש בשדה הזה, צריך להגדיר את LinkPreviewTriggers במניפסט של התוסף. פרטים נוספים זמינים במאמר תצוגה מקדימה של קישורים באמצעות צ'יפים חכמים. דוגמה לעומס נתונים כשמשתמש מציג תצוגה מקדימה של הקישור https://www.example.com/12345: "sheets" : { "matchedUrl" : { "url" : "https://www.example.com/12345" } }

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

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

אובייקט אירוע ב-Slides
slides.id	string השדה הזה מופיע רק אם המשתמש העניק הרשאה להיקף https://www.googleapis.com/auth/drive.file. המזהה של המצגת שנפתחה בממשק המשתמש של Slides.
slides.title	string השדה הזה מופיע רק אם המשתמש העניק הרשאה להיקף https://www.googleapis.com/auth/drive.file. הכותרת של המצגת שנפתחת בממשק המשתמש של Slides.
slides.addonHasFileScopePermission	boolean אם הערך הוא true, התוסף ביקש והתקבלה לו הרשאת היקף https://www.googleapis.com/auth/drive.file למצגת שנפתחה בממשק המשתמש של Slides. אחרת, הערך בשדה הזה הוא false.
slides.matchedUrl.url	string השדה הזה מופיע רק אם מתקיימים התנאים הבאים: https://www.googleapis.com/auth/workspace.linkpreview אושר על ידי המשתמש. כתובת ה-URL תואמת לתבנית המארח שצוינה בטריגר LinkPreviewTriggers. כתובת ה-URL של הקישור שיוצר תצוגה מקדימה ב-Google Slides. כדי להשתמש בשדה הזה, צריך להגדיר את LinkPreviewTriggers במניפסט של התוסף. פרטים נוספים זמינים במאמר תצוגה מקדימה של קישורים באמצעות צ'יפים חכמים. דוגמה לעומס נתונים כשמשתמש מציג תצוגה מקדימה של הקישור https://www.example.com/12345: "slides" : { "matchedUrl" : { "url" : "https://www.example.com/12345" } }