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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

אובייקט האירוע
eventObject.commonEventObject Common fields object
אובייקט שמכיל מידע שמשותף לכל אובייקטי האירועים, ללא קשר לאפליקציה המארחת.
eventObject.calendar Calendar event object
מוצג רק אם המארח שמתקשר הוא יומן Google. אובייקט שמכיל מידע על היומן ועל האירוע.
eventObject.chat Chat event object
מוצג רק אם המארח של השיחה הוא Google 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.

בתוספים ל-Google Workspace, המידע הזה נמצא בשדה eventObject.commonEventObject.formInputs. ווידג'טים עם ערכים בודדים מיוצגים כמערכים עם רכיב אחד.

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

בתוספים ל-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) של פעולות כשהמשתמש יוצר אינטראקציה עם ווידג'טים. פונקציית הקריאה החוזרת של התוסף יכולה לשלוח שאילתה לאובייקט האירוע הנפוץ כדי לקבוע את התוכן של ווידג'טים פתוחים בלקוח של המשתמש. לדוגמה, התוסף יכול לאתר את הטקסט שהמשתמש הזין בווידג'ט TextInput באובייקט eventObject.commentEventObject.formInputs.

שדות נפוצים של אובייקט האירוע
commonEventObject.platform string
מציין את המקור של האירוע (‎`WEB`‎, ‎`IOS`‎ או ‎ `ANDROID`‎).
commonEventObject.formInputs object
מפה שמכילה את הערכים הנוכחיים של הווידג'טים בכרטיס שמוצג. המפתחות של המפה הם מזהי המחרוזות שמוקצים לכל ווידג'ט.

המבנה של אובייקט הערך של המפה תלוי בסוג הווידג'ט:

  • ווידג'טים עם ערך יחיד (לדוגמה, תיבת טקסט): רשימה של מחרוזות (רכיב אחד בלבד).

    דוגמה: לווידג'ט של קלט טקסט עם המזהה 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.

    דוגמה: לכלי לבחירת צבע עם המזהה myDatePicker, ניגשים לאובייקט DateInput באמצעות e.commonEventObject.formInputs.myDatePicker.dateInput.

  • ‫A time-only picker: TimeInput object.

    דוגמה: לכלי לבחירת צבע עם המזהה myTimePicker, ניגשים לאובייקט TimeInput באמצעות 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) של אזור הזמן של המשתמש, נמדד באלפיות השנייה. למידע נוסף, קראו את המאמר גישה ללוקאל ולאזור הזמן של המשתמש.

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

פונקציות קריאה חוזרת (callback) של פעולות יכולות לקבל ערכים נוכחיים של ווידג'טים בשדה 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 הוא החלק באובייקט האירוע הכולל שנושא מידע על האינטראקציות של המשתמש עם אפליקציית Chat. הוא מופיע באובייקט אירוע רק אם התוסף מרחיב את Google Chat.

צ'אט
chat.user object (User)
המשתמש ב-Chat שהייתה לו אינטראקציה עם האפליקציה ל-Chat.
chat.space object (Space)
המרחב המשותף ב-Chat שבו המשתמש ביצע פעולה באפליקציה ל-Chat.
chat.eventTime

string (Timestamp format)

השעה שבה התרחשה האינטראקציה.

שדה של איחוד payload. בטריגר דף הבית של האפליקציה (כשמשתמש פותח את הכרטיסייה דף הבית), הערך payload לא מוגדר והערך chat מכיל את chat.user ו-chat.eventTime.

הערך payload יכול להיות רק אחד מהבאים:
chat.messagePayload

object (MessagePayload)

המטען הייעודי (payload) שאפליקציות הצ'אט מקבלות מטריגר של הודעה.
chat.addedToSpacePayload

object (AddedToSpacePayload)

המטען הייעודי (payload) שאפליקציות ל-Chat מקבלות מטריגר של צירוף למרחב.
chat.removedFromSpacePayload

object (RemovedFromSpacePayload)

המטען הייעודי (payload) שאפליקציות הצ'אט מקבלות מטריגר של הסרה ממרחב.
chat.buttonClickedPayload

object (ButtonClickedPayload)

המטען הייעודי (payload) שאפליקציות הצ'אט מקבלות כשמשתמשים לוחצים על כפתור בהודעה או בכרטיס. אם משתמש לוחץ על כפתור כדי לשלוח מידע, האובייקט commonEventObject.formInputs מכיל את הערכים שנאספו מהמשתמש. פרטים נוספים מופיעים במאמר איסוף מידע ממשתמשי Google Chat.
chat.widgetUpdatedPayload

object (WidgetUpdatedPayload)

המטען הייעודי (payload) שאפליקציות הצ'אט מקבלות כשמשתמשים מקלידים טקסט בתפריט לבחירה מרובה של ווידג'ט selectionInput. אפליקציות צ'אט יכולות להשתמש באובייקט האירוע הזה כדי לאכלס פריטים מוצעים ממקור נתונים דינמי. לדוגמה, כדי לאכלס בקשות תמיכה ממקור נתונים חיצוני, אפליקציית Chat יכולה לשלוח שאילתה למקור הנתונים על סמך מה שהמשתמש מקליד בתפריט, ואז להחזיר בקשות תמיכה תואמות כפריטים שאפשר לבחור.

האובייקט CommonEventObject.parameters['autocomplete_widget_query'] מכיל את ערך המחרוזת שהמשתמש מקליד בתפריט.

chat.appCommandPayload

object (AppCommandPayload)

המטען הייעודי (payload) שאפליקציות הצ'אט מקבלות כשמשתמש משתמש בפקודה מאפליקציית הצ'אט.

מטען ייעודי

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

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

כשאדמינים מתקינים אפליקציות ל-Chat, השדה space.adminInstalled מוגדר כ-true.

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

כשהאדמינים מסירים אפליקציות צ'אט, השדה space.adminInstalled מוגדר כ-false.

מטען ייעודי (payload) של לחיצה על כפתור
ButtonClickedPayload
chat.buttonClickedPayload.message object (Message)
הודעת הצ'אט שמכילה את הכפתור שהמשתמש לחץ עליו.
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 משתמש לוחץ על רכיב אינטראקטיבי בתיבת דו-שיח. לדוגמה, משתמש ממלא מידע בתיבת דו-שיח ולוחץ על כפתור כדי לשלוח את המידע.
מטען ייעודי (payload) מעודכן של הווידג'ט
WidgetUpdatedPayload
chat.widgetUpdatedPayload.space object (Space)
המרחב המשותף ב-Chat שבו התרחשה האינטראקציה.
מטען ייעודי (payload) של פקודת אפליקציה
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 המשתמש בוחר את הפקודה מתפריט הצ'אט באזור התשובה להודעה.

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

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

בטבלה הבאה מפורטים השדות שמופיעים בשדה calendarEventObject של אובייקט אירוע. שדות שמסומנים כנתונים שנוצרו על ידי משתמשים מופיעים באובייקט האירוע רק אם הנתונים מופיעים באירוע ביומן והשדה addOns.calendar.currentEventAccess במניפסט של התוסף מוגדר כ-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 במניפסט שלו כ-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 במניפסט שלו לערך 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 במניפסט של התוסף מוגדר הערך READ או READ_WRITE.

אובייקט של נקודת כניסה
entryPoint.accessCode string
קוד הגישה ששימש כדי לגשת לשיחת הוועידה. האורך המקסימלי הוא 128 תווים. ספקי שיחות ועידה בדרך כלל משתמשים רק בקבוצת משנה של {accessCode, meetingCode, passcode, password, pin} כדי לספק גישה לשיחות ועידה. התאימו את השדות לאלה שספק שיחות הוועידה משתמש בהם, והציגו רק אותם.
entryPoint.entryPointFeatures list
התכונות של נקודת הכניסה. כרגע, התכונות האלה חלות רק על נקודות הכניסה של phone:
  • ‫toll: נקודת הכניסה היא שיחת טלפון בתשלום.
  • toll_free: נקודת הכניסה היא שיחת טלפון חינם.
entryPoint.entryPointType string
סוג נקודת הכניסה. הערכים האפשריים הם:
  • ‫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:+12345678900,,,12345678;1234").
  • ‫sip: צריך לציין סכימה מסוג sip: או sips:. לדוגמה, "sip:12345678@myprovider.com".
  • ‫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.
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 כדי לתת לתוסף גישה זמנית להודעת 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 במניפסט של התוסף. פרטים נוספים זמינים במאמר תצוגה מקדימה של קישורים באמצעות צ'יפים חכמים.

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

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

מטען ייעודי (payload) לדוגמה כשמשתמש צופה בתצוגה מקדימה של הקישור https://www.example.com/12345:

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