Event

یک رویداد تعاملی برنامه چت گوگل که نشان‌دهنده و حاوی داده‌هایی درباره تعامل کاربر با یک برنامه چت است. برای پیکربندی برنامه چت خود برای دریافت رویدادهای تعاملی، به بخش «دریافت و پاسخ به تعاملات کاربر» مراجعه کنید.

علاوه بر دریافت رویدادها از تعاملات کاربر، برنامه‌های چت می‌توانند رویدادهای مربوط به تغییرات در فضاها، مانند زمانی که یک عضو جدید به یک فضا اضافه می‌شود، را دریافت کنند. برای کسب اطلاعات در مورد رویدادهای فضا، به بخش «کار با رویدادها از Google 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 )

نوع تعامل کاربر با برنامه چت، مانند MESSAGE یا ADDED_TO_SPACE .

eventTime

string ( Timestamp format)

مهر زمانی که نشان می‌دهد رویداد تعامل چه زمانی رخ داده است.

token

string

یک مقدار مخفی که برنامه‌های چت قدیمی می‌توانند از آن برای تأیید اینکه آیا درخواست از طرف گوگل است یا خیر، استفاده کنند. گوگل به طور تصادفی توکن را تولید می‌کند و مقدار آن ثابت می‌ماند. می‌توانید توکن را از صفحه پیکربندی API چت در کنسول ابری گوگل دریافت، لغو یا بازسازی کنید.

برنامه‌های چت مدرن از این فیلد استفاده نمی‌کنند. این فیلد در پاسخ‌های API و صفحه پیکربندی Chat API وجود ندارد.

threadKey

string

کلید تعریف‌شده توسط برنامه‌ی چت برای رشته‌ی مربوط به رویداد تعامل. برای اطلاعات بیشتر به spaces.messages.thread.threadKey مراجعه کنید.

message

object ( Message )

برای رویدادهای تعاملی ADDED_TO_SPACE ، CARD_CLICKED و MESSAGE ، در صورت وجود، پیامی که رویداد تعاملی را فعال کرده است.

user

object ( User )

کاربری که با برنامه چت تعامل داشته است.

thread

object ( Thread )

رشته‌ای که کاربر در آن با برنامه چت تعامل داشته است. این می‌تواند در یک رشته جدید ایجاد شده توسط یک پیام تازه ارسال شده باشد. اگر رویداد تعامل با یک پیام یا رشته خاص مرتبط باشد، این فیلد پر می‌شود.

space

object ( Space )

فضایی که کاربر در آن با برنامه چت تعامل داشته است.

action

object ( FormAction )

برای رویدادهای تعاملی CARD_CLICKED ، داده‌های مربوط به عملکرد فرم هنگام کلیک کاربر روی یک کارت یا کادر محاوره‌ای. برای کسب اطلاعات بیشتر، به بخش «خواندن داده‌های فرم ورودی توسط کاربران روی کارت‌ها» مراجعه کنید.

configCompleteRedirectUrl

string

این URL برای رویدادهای تعاملی MESSAGE ، ADDED_TO_SPACE و APP_COMMAND پر می‌شود. پس از تکمیل یک جریان مجوز یا پیکربندی خارج از Google Chat، کاربران باید به این URL هدایت شوند تا به Google Chat نشان دهند که جریان مجوز یا پیکربندی موفقیت‌آمیز بوده است. برای اطلاعات بیشتر، به بخش «اتصال یک برنامه چت با سایر سرویس‌ها و ابزارها» مراجعه کنید.

isDialogEvent

boolean

برای رویدادهای تعاملی CARD_CLICKED و MESSAGE ، اینکه آیا کاربر در حال تعامل با یک کادر محاوره‌ای است یا قرار است با آن تعامل داشته باشد.

dialogEventType

enum ( DialogEventType )

نوع رویداد تعامل محاوره‌ای دریافتی.

common

object ( CommonEventObject )

اطلاعاتی درباره کلاینت کاربر، مانند زبان، برنامه میزبان و پلتفرم را نشان می‌دهد. برای برنامه‌های چت، CommonEventObject شامل اطلاعاتی است که توسط کاربران در تعامل با دیالوگ‌ها ارسال می‌شود، مانند داده‌های وارد شده روی کارت.

appCommandMetadata

object ( AppCommandMetadata )

فراداده درباره یک دستور برنامه چت.

شیء رویداد مشترک

شیء رویداد مشترک، بخشی از شیء رویداد کلی است که اطلاعات عمومی و مستقل از میزبان را از کلاینت کاربر به افزونه منتقل می‌کند. این اطلاعات شامل جزئیاتی مانند زبان کاربر، برنامه میزبان و پلتفرم است.

علاوه بر تریگرهای صفحه اصلی و زمینه‌ای، افزونه‌ها اشیاء رویداد را ساخته و به توابع فراخوانی اکشن منتقل می‌کنند، زمانی که کاربر با ویجت‌ها تعامل دارد. تابع فراخوانی افزونه شما می‌تواند از شیء رویداد مشترک برای تعیین محتوای ویجت‌های باز در کلاینت کاربر پرس‌وجو کند. به عنوان مثال، افزونه شما می‌تواند متنی را که کاربر در یک ویجت TextInput در شیء eventObject.commentEventObject.formInputs وارد کرده است، پیدا کند.

برای برنامه‌های چت، نام تابعی که کاربر هنگام تعامل با یک ویجت فراخوانی کرده است.

نمایش 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 ). توسط برنامه‌های چت پشتیبانی نمی‌شود.

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 به آرایه مقدار دسترسی پیدا کنید.

مثال : برای یک انتخابگر با شناسه myDTPicker ، با استفاده از e.commonEventObject.formInputs.myDTPicker.dateTimeInput به شیء DateTimeInput دسترسی پیدا کنید.

مثال : برای یک انتخابگر با شناسه myDatePicker ، با استفاده از e.commonEventObject.formInputs.myDatePicker.dateInput به شیء DateInput دسترسی پیدا کنید.

مثال : برای یک انتخابگر با شناسه myTimePicker ، با استفاده از e.commonEventObject.formInputs.myTimePicker.timeInput به شیء 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 استفاده کنند. به بخش «ساخت رابط‌های تعاملی برای برنامه‌های چت» مراجعه کنید.

منطقه زمانی

شناسه و اختلاف زمانی منطقه زمانی نسبت به زمان هماهنگ جهانی (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 که فقط مقادیر زمان را می‌پذیرد.

پایان میدان‌های ناسازگار.

ورودی‌های رشته‌ای

پارامتر ورودی برای ویجت‌های معمولی. برای ویجت‌های تک مقداری، یک لیست تک مقداری است. برای ویجت‌های چند مقداری، مانند چک‌باکس، تمام مقادیر ارائه می‌شوند.

نمایش JSON 
{
  "value": [
    string
  ]
}
فیلدها
value[]

string

فهرستی از رشته‌های وارد شده توسط کاربر.

ورودی تاریخ و زمان

مقادیر ورودی تاریخ و زمان.

نمایش JSON 
{
  "msSinceEpoch": string,
  "hasDate": boolean,
  "hasTime": boolean
}
فیلدها
msSinceEpoch

string ( int64 format)

زمان از زمان آغازین، بر حسب میلی‌ثانیه.

hasDate

boolean

آیا ورودی datetime شامل تاریخ تقویمی باشد یا خیر.

hasTime

boolean

آیا ورودی datetime شامل مهر زمانی (timestamp) می‌شود یا خیر.

ورودی تاریخ

مقادیر ورودی تاریخ.

نمایش JSON 
{
  "msSinceEpoch": string
}
فیلدها
msSinceEpoch

string ( int64 format)

زمان از زمان آغازین، بر حسب میلی‌ثانیه.

ورودی زمان

مقادیر ورودی زمان.

نمایش JSON 
{
  "hours": integer,
  "minutes": integer
}
فیلدها
hours

integer

ساعت در یک سیستم ۲۴ ساعته.

minutes

integer

تعداد دقایق گذشته از ساعت. مقادیر معتبر از ۰ تا ۵۹ هستند.

فراداده‌ی AppCommand

فراداده درباره یک دستور برنامه چت .

نمایش JSON 
{
  "appCommandId": integer,
  "appCommandType": enum (AppCommandType)
}
فیلدها
appCommandId

integer

شناسه‌ی دستوری که در پیکربندی API چت مشخص شده است.

appCommandType

enum ( AppCommandType )

نوع دستور برنامه چت.