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 
{

  "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)

הזמן שעבר מאז תקופת זמן המערכת, באלפיות השנייה.
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.