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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

בתוספים ל-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. פרטים נוספים זמינים במאמר בנושא גישה ללוקאל ולtimezone של המשתמש.

בתוספים ל-Google Workspace, המידע הזה מופיע בשדה eventObject.commonEventObject.timeZone.id.

eventObject.userTimezone.offset string
הוצאה משימוש ומושבתת כברירת מחדל. ההפרש בין הזמן האוניברסלי המתואם (UTC) לבין אזור הזמן של המשתמש, שנמדד באלפיות השנייה. פרטים נוספים זמינים במאמר בנושא גישה ללוקאל ולtimezone של המשתמש.

בתוספים ל-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: a DateTimeInput object.

    דוגמה: כדי לגשת לאובייקט DateTimeInput של בורר עם מזהה myDTPicker, משתמשים ב-e.commonEventObject.formInputs.myDTPicker.dateTimeInput.

  • A date-only picker: a DateInput object.

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

  • A time-only picker: a 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 הוא החלק באובייקט האירוע הכולל שכולל מידע על האינטראקציות של משתמש עם אפליקציית 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)

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

object (AddedToSpacePayload)

‫payload שאפליקציות ל-Chat מקבלות מטריגר מסוג Added to space.
chat.removedFromSpacePayload

object (RemovedFromSpacePayload)

המטען הייעודי (payload) שאפליקציות ל-Chat מקבלות מטריגר Removed from space.
chat.buttonClickedPayload

object (ButtonClickedPayload)

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

object (WidgetUpdatedPayload)

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

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

chat.appCommandPayload

object (AppCommandPayload)

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

מטען ייעודי

בהתאם לסוג האינטראקציה עם אפליקציית Chat, האירוע מכיל מטען ייעודי (payload) עם משאב אחד או יותר של 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 למרחב באמצעות הודעה. לדוגמה, אם מתייגים את אפליקציית Chat באמצעות @ או משתמשים בפקודה. אם true, ‏ Chat שולח אובייקט אירוע נוסף עם messagePayload שמכיל מידע על ההודעה.
chat.addedToSpacePayload.configCompleteRedirectUri string
כתובת ה-URL שאליה אפליקציית Chat צריכה להפנות את המשתמש אחרי שהוא משלים תהליך הרשאה או הגדרה מחוץ ל-Google Chat. מידע נוסף זמין במאמר בנושא חיבור תוסף ל-Google Workspace לשירות של צד שלישי.

הוסר ממטען הייעודי (payload) של המרחב
RemovedFromSpacePayload
chat.removedFromSpacePayload.space object (Space)
מרחב Chat שממנו המשתמש הסיר או ביטל את ההתקנה של אפליקציית Chat.

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

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

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