Event

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

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

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

ייצוג ב-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)

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

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

מייצג מידע על הלקוח של המשתמש, כמו מיקום, אפליקציית מארח ופלטפורמה. באפליקציות ל-Chat, ‏ 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))

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

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

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

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

דוגמה: כדי לגשת לערך של קלט טקסט עם employeeName כמזהה, משתמשים ב-e.commonEventObject.formInputs.employeeName.stringInputs.value[0].

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

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

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

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

דוגמה: כדי לגשת לאובייקט TimeInput של בורר עם מזהה myTimePicker, משתמשים ב-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 
{

  // Union field inputs can be only one of the following:
  "stringInputs": {
    object (StringInputs)
  },
  "dateTimeInput": {
    object (DateTimeInput)
  },
  "dateInput": {
    object (DateInput)
  },
  "timeInput": {
    object (TimeInput)
  }
  // End of list of possible types for union field inputs.
}
שדות

שדה איחוד inputs.

הערך inputs יכול להיות רק אחד מהערכים הבאים:
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)

הזמן מאז תחילת התקופה של זמן מערכת, באלפיות השנייה.
hasDate

boolean

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

boolean

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

DateInput

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

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

string (int64 format)

הזמן מאז תחילת התקופה של זמן מערכת, באלפיות השנייה.

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)

סוג הפקודה באפליקציית Chat.