Event

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

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

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

ייצוג ב-JSON 
{
  "type": enum (EventType),
  "eventTime": string,
  "token": string,
  "threadKey": string,
  "message": {
    object (Message)
  },
  "user": {
    object (User)
  },
  "thread": {
    object (Thread)
  },
  "space": {
    object (Space)
  },
  "action": {
    object (FormAction)
  },
  "configCompleteRedirectUrl": string,
  "isDialogEvent": boolean,
  "dialogEventType": enum (DialogEventType),
  "common": {
    object (CommonEventObject)
  },
  "appCommandMetadata": {
    object (AppCommandMetadata)
  }
}
שדות
type

enum (EventType)

סוג האינטראקציה של המשתמש עם האפליקציה ל-Chat, כמו MESSAGE או ADDED_TO_SPACE.
eventTime

string (Timestamp format)

חותמת הזמן שמציינת מתי התרחש אירוע האינטראקציה.
token

string

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

באפליקציות מודרניות ל-Chat לא משתמשים בשדה הזה. הוא לא מופיע בתגובות מה-API ובדף ההגדרות של Chat API.
threadKey

string

המפתח שהוגדר באפליקציית Chat לשרשור שקשור לאירוע האינטראקציה. מידע נוסף זמין בכתובת spaces.messages.thread.threadKey.
message

object (Message)

באירועי אינטראקציה מסוג ADDED_TO_SPACE,‏ CARD_CLICKED ו-MESSAGE, ההודעה שהפעילה את אירוע האינטראקציה, אם רלוונטי.
user

object (User)

המשתמש שהייתה לו אינטראקציה עם האפליקציה ל-Chat.
thread

object (Thread)

השרשור שבו המשתמש יצר אינטראקציה עם אפליקציית הצ'אט. זה יכול להיות שרשור חדש שנוצר על ידי הודעה שנשלחה לאחרונה. השדה הזה מאוכלס אם אירוע האינטראקציה משויך להודעה או לשרשור ספציפיים.
space

object (Space)

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

object (FormAction)

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

string

כתובת ה-URL הזו מאוכלסת באירועי אינטראקציה מסוג MESSAGE, ADDED_TO_SPACE ו-APP_COMMAND. אחרי שהמשתמשים מסיימים את תהליך ההרשאה או ההגדרה מחוץ ל-Google Chat, הם צריכים להיות מופנים לכתובת ה-URL הזו כדי לאותת ל-Google Chat שתהליך ההרשאה או ההגדרה הצליח. מידע נוסף מופיע במאמר קישור אפליקציות ל-Chat לשירותים ולכלים אחרים.
isDialogEvent

boolean

באירועי אינטראקציה מסוג CARD_CLICKED ו-MESSAGE, אם המשתמש יוצר אינטראקציה עם תיבת דו-שיח או עומד ליצור איתה אינטראקציה.
dialogEventType

enum (DialogEventType)

סוג אירוע האינטראקציה של תיבת הדו-שיח שהתקבל.
common

object (CommonEventObject)

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

object (AppCommandMetadata)

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

CommonEventObject

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

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

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

ייצוג ב-JSON 
{
  "userLocale": string,
  "hostApp": enum (HostApp),
  "platform": enum (Platform),
  "timeZone": {
    object (TimeZone)
  },
  "formInputs": {
    string: {
      object (Inputs)
    },
    ...
  },
  "parameters": {
    string: string,
    ...
  },
  "invokedFunction": string
}
שדות
userLocale

string

מושבתת כברירת מחדל. מזהה השפה והמדינה או האזור של המשתמש בפורמט של קוד שפה לפי תקן ISO 639 וקוד מדינה או אזור לפי תקן ISO 3166. לדוגמה, en-US.

כדי להפעיל את השדה הזה, צריך להגדיר את addOns.common.useLocaleFromApp ל-true במניפסט של התוסף. רשימת ההיקפים של התוסף צריכה לכלול גם את https://www.googleapis.com/auth/script.locale. פרטים נוספים זמינים במאמר גישה למיקום ולאזור הזמן של המשתמש.
hostApp

enum (HostApp)

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

  • GMAIL
  • CALENDAR
  • DRIVE
  • DOCS
  • SHEETS
  • SLIDES
  • CHAT
platform

enum (Platform)

טיפוס הנתונים enum של הפלטפורמה שמציין את הפלטפורמה שבה האירוע נוצר (WEB, ‏IOS או ANDROID). לא נתמך על ידי אפליקציות ל-Chat.
timeZone

object (TimeZone)

מושבתת כברירת מחדל. מזהה אזור הזמן וההפרש מהזמן האוניברסלי המתואם (UTC). כדי להפעיל את השדה הזה, צריך להגדיר את addOns.common.useLocaleFromApp ל-true במניפסט של התוסף. רשימת ההיקפים של התוסף צריכה לכלול גם את https://www.googleapis.com/auth/script.locale. פרטים נוספים זמינים במאמר גישה למיקום ולאזור הזמן של המשתמש.

נתמך רק בסוגי האירועים CARD_CLICKED ו-SUBMIT_DIALOG.
formInputs

map (key: string, value: object (Inputs))

מפה שמכילה את הערכים הנוכחיים של הווידג'טים בכרטיס שמוצג. המפתחות של המפה הם ערכי המחרוזת name שמוקצים לכל ווידג'ט קלט (כמו TextInput.name,‏ SelectionInput.name,‏ DateTimePicker.name או DecoratedText.SwitchControl.name).

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

הערה: הדוגמאות הבאות מותאמות לסביבת ההרצה של V8 ב-Apps Script. אם אתם משתמשים בסביבת זמן הריצה Rhino, אתם צריכים להוסיף [""] אחרי הערך. לדוגמה, במקום e.commonEventObject.formInputs.employeeName.stringInputs.value[0], צריך להגדיר את הפורמט של אובייקט האירוע בתור e.commonEventObject.formInputs.employeeName[""].stringInputs.value[0]. מידע נוסף על סביבות הרצה ב-Apps Script זמין במאמר סקירה כללית על סביבת ההרצה של V8.

  • ווידג'טים עם ערך יחיד (לדוגמה, ווידג'ט TextInput או ווידג'ט SelectionInput מסוג DROPDOWN או RADIO_BUTTON): אובייקט StringInputs שמכיל רשימה עם רכיב אחד (או רשימה ריקה אם לא נבחרה אפשרות).

דוגמה: לווידג'ט של קלט טקסט עם employeeName בתור name, אפשר לגשת לערך של קלט הטקסט באמצעות: e.commonEventObject.formInputs.employeeName.stringInputs.value[0].

  • ווידג'טים עם כמה ערכים (לדוגמה, ווידג'ט SelectionInput מסוג CHECK_BOX, SWITCH או MULTI_SELECT): אובייקט StringInputs שמכיל את רשימת המחרוזות value של הפריטים שנבחרו.

דוגמה: בווידג'ט עם כמה ערכים שה-name שלו הוא participants, ניגשים למערך הערכים באמצעות: e.commonEventObject.formInputs.participants.stringInputs.value.

  • ווידג'ט DecoratedText.SwitchControl: אובייקט StringInputs. כאשר selected הוא true, stringInputs.value מכיל את השדה value של המתג (או "" אם value לא צוין; אם מספר מתגים חולקים את אותו name, ה-value של כל מתג שנבחר נכלל ברשימה). כשהערך של selected הוא false, המאפיין value של המתג מושמט מ-stringInputs.value.

  • בורר תאריך ושעה (DateTimePickerType.DATE_AND_TIME): DateTimeInput object.

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

  • בורר תאריכים בלבד (DateTimePickerType.DATE_ONLY): DateInput object.

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

דוגמה: לכלי לבחירת צבעים עם name של myTimePicker, ניגשים לאובייקט TimeInput באמצעות e.commonEventObject.formInputs.myTimePicker.timeInput.
parameters

map (key: string, value: string)

כל פרמטר נוסף שאתם מספקים לפעולה באמצעות actionParameters או Action.setParameters().

תצוגה מקדימה למפתחים: בתוספים שמרחיבים את Google Chat, כדי להציע פריטים על סמך מה שהמשתמשים מקלידים בתפריטים לבחירה מרובה, משתמשים בערך של המפתח "autocomplete_widget_query" (event.commonEventObject.parameters["autocomplete_widget_query"]). אתם יכולים להשתמש בערך הזה כדי לשלוח שאילתה למסד נתונים ולהציע למשתמשים פריטים לבחירה בזמן שהם מקלידים. פרטים נוספים זמינים במאמר איסוף ועיבוד מידע ממשתמשי Google Chat.
invokedFunction

string

שם הפונקציה שרוצים להפעיל.

השדה הזה לא מאוכלס בתוספים ל-Google Workspace שמרחיבים את Google Chat. במקום זאת, כדי לקבל נתוני פונקציות כמו מזהים, תוספים שמרחיבים את Chat צריכים להשתמש בשדה parameters. איך יוצרים ממשקים אינטראקטיביים לאפליקציות ל-Chat

TimeZone

מזהה אזור הזמן וההפרש מהזמן האוניברסלי המתואם (UTC). נתמך רק בסוגי האירועים CARD_CLICKED ו-SUBMIT_DIALOG.

ייצוג ב-JSON 
{
  "id": string,
  "offset": integer
}
שדות
id

string

קוד מסד הנתונים של אזור הזמן IANA TZ, כמו "America/Toronto".
offset

integer

ההפרש בין אזור הזמן של המשתמש לבין זמן אוניברסלי מתואם (UTC), באלפיות השנייה.

כניסות קלט

סוגי הנתונים שהמשתמשים יכולים להזין בכרטיסים או בתיבות דו-שיח. סוג הקלט תלוי בסוג הערכים שהווידג'ט מקבל.

ייצוג ב-JSON 
{

  "stringInputs": {
    object (StringInputs)
  },
  "dateTimeInput": {
    object (DateTimeInput)
  },
  "dateInput": {
    object (DateInput)
  },
  "timeInput": {
    object (TimeInput)
  }
}
שדות
ברשימה הבאה מופיעים שדות שמוציאים זה את זה. בתשובה יוגדר לכל היותר אחד מהשדות הבאים:
stringInputs

object (StringInputs)

רשימה של מחרוזות שמייצגות את הערכים שהמשתמש מזין בווידג'ט.

אם הווידג'ט מקבל רק ערך אחד, כמו ווידג'ט TextInput, הרשימה מכילה אובייקט מחרוזת אחד. אם הווידג'ט מקבל כמה ערכים, כמו ווידג'ט SelectionInput של תיבות סימון, הרשימה מכילה אובייקט מחרוזת לכל ערך שהמשתמש מזין או בוחר.
dateTimeInput

object (DateTimeInput)

ערכי קלט של תאריך ושעה מווידג'ט DateTimePicker שמקבל גם תאריך וגם שעה.
dateInput

object (DateInput)

ערכי קלט של תאריכים מווידג'ט DateTimePicker שמקבל רק ערכי תאריכים.
timeInput

object (TimeInput)

ערכי קלט של זמן מווידג'ט DateTimePicker שמקבל רק ערכי זמן.
סוף השדות שמוציאים זה את זה.

StringInputs

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

ייצוג ב-JSON 
{
  "value": [
    string
  ]
}
שדות
value[]

string

רשימה של מחרוזות שהמשתמש הזין.

DateTimeInput

ערכי קלט של תאריך ושעה.

ייצוג ב-JSON 
{
  "msSinceEpoch": string,
  "hasDate": boolean,
  "hasTime": boolean
}
שדות
msSinceEpoch

string (int64 format)

הזמן שחלף מאז ראשית זמן יוניקס (Unix epoch), באלפיות השנייה.
hasDate

boolean

אם הקלט של datetime כולל תאריך ביומן.
hasTime

boolean

אם הקלט של datetime כולל חותמת זמן.

DateInput

ערכי קלט של תאריכים.

ייצוג ב-JSON 
{
  "msSinceEpoch": string
}
שדות
msSinceEpoch

string (int64 format)

הזמן שחלף מאז ראשית זמן יוניקס (Unix epoch), באלפיות השנייה.

TimeInput

ערכי קלט של זמן.

ייצוג ב-JSON 
{
  "hours": integer,
  "minutes": integer
}
שדות
hours

integer

השעה בשעון של 24 שעות.
minutes

integer

מספר הדקות אחרי השעה העגולה. הערכים התקינים הם 0 עד 59.

AppCommandMetadata

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

ייצוג ב-JSON 
{
  "appCommandId": integer,
  "appCommandType": enum (AppCommandType)
}
שדות
appCommandId

integer

המזהה של הפקודה שצוינה בהגדרות של Chat API.
appCommandType

enum (AppCommandType)

סוג הפקודה של אפליקציית הצ'אט.