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

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

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

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

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

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

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

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

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

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

  • A date-only picker: a DateInput object.

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

  • A time-only picker: a TimeInput object.

    דוגמה: אם יש לכם בוחר עם מזהה myTimePicker, אפשר לגשת לאובייקט TimeInput באמצעות e.commonEventObject.formInputs.myTimePicker.timeInput.
commonEventObject.hostApp ‫string
מציין את אפליקציית המארח שבה התוסף פעיל כשנוצר אובייקט האירוע. הערכים האפשריים כוללים את הערכים הבאים:
  • GMAIL
  • CALENDAR
  • DRIVE
  • DOCS
  • SHEETS
  • SLIDES
commonEventObject.parameters object
כל פרמטר נוסף שמעבירים לפעולה באמצעות actionParameters או Action.setParameters().

גרסת Developer Preview: כדי להציע פריטים על סמך מה שהמשתמשים מקלידים בתפריטים לבחירה מרובה, בתוספים שמרחיבים את 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. פרטים נוספים זמינים במאמר בנושא גישה ללוקאל ולtimezone של משתמשים.
commonEventObject.timeZone.offset string
ההפרש בשעות מהזמן האוניברסלי המתואם (UTC) באזור הזמן של המשתמש, שנמדד באלפיות השנייה. פרטים נוספים זמינים במאמר בנושא גישה ללוקאל ולtimezone של משתמשים.

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

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

App command 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 המשתמש בוחר את הפקודה מתפריט Chat באזור התשובה להודעה.

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

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

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