Đối tượng sự kiện

Trang này trình bày cấu trúc của các đối tượng sự kiện tiện ích bổ sung của Google Workspace.

Đối tượng sự kiện là các cấu trúc JSON được tự động tạo và truyền dưới dạng tham số đến các hàm kích hoạt hoặc lệnh gọi lại khi người dùng tương tác với một tiện ích bổ sung. Các đối tượng sự kiện mang thông tin phía máy khách về ứng dụng lưu trữ và bối cảnh hiện tại đến hàm gọi lại phía máy chủ của tiện ích bổ sung.

Tiện ích bổ sung của Google Workspace sử dụng các đối tượng sự kiện ở những nơi sau:

  • Điều kiện kích hoạt trên trang chủ. Mọi hàm homepageTrigger mà bạn xác định sẽ tự động được truyền một đối tượng sự kiện khi hàm kích hoạt trang chủ kích hoạt. Bạn có thể sử dụng đối tượng này trong hàm kích hoạt trang chủ để xác định ứng dụng lưu trữ đang hoạt động, nền tảng của ứng dụng khách, ngôn ngữ của người dùng và các thông tin khác.

    Các đối tượng sự kiện được tạo khi các trình kích hoạt trang chủ kích hoạt không chứa tất cả các trường có trong hai trường hợp còn lại; các trường liên quan đến tiện ích và thông tin theo bối cảnh sẽ bị bỏ qua.

  • Sự kiện kích hoạt theo bối cảnh. Mỗi ứng dụng lưu trữ cung cấp một tập hợp các điều kiện kích hoạt theo bối cảnh khác nhau sẽ kích hoạt khi người dùng chuyển sang một bối cảnh cụ thể. Ví dụ:

    • Gmail cung cấp một điều kiện kích hoạt theo bối cảnh khi người dùng mở thư và một điều kiện khác khi người dùng soạn thư.
    • Lịch Google cung cấp một điều kiện kích hoạt theo bối cảnh khi người dùng mở một sự kiện.
    • Google Drive cung cấp một điều kiện kích hoạt theo ngữ cảnh khi người dùng chọn tệp trên Drive.

    Khi một điều kiện kích hoạt theo bối cảnh kích hoạt, ứng dụng lưu trữ sẽ gọi runFunction tương ứng được liệt kê trong tệp kê khai của tiện ích bổ sung, truyền cho tiện ích bổ sung một đối tượng sự kiện làm tham số. Các đối tượng sự kiện được tạo khi các điều kiện kích hoạt theo bối cảnh kích hoạt chứa tất cả các trường có trong đối tượng sự kiện điều kiện kích hoạt trang chủ, cộng với các trường chứa thông tin theo bối cảnh.

  • Thao tác trên tiện ích. Các đối tượng sự kiện cũng được dùng để cung cấp khả năng tương tác tiện ích, sử dụng cùng một mô hình hành động mà các tiện ích bổ sung của Gmail sử dụng. Tiện ích bổ sung Google Workspace sử dụng tất cả các hàm trình xử lý tiện ích, đối tượng Action và phản hồi hành động giống nhau. Tuy nhiên, trong các tiện ích bổ sung của Google Workspace, các đối tượng sự kiện thao tác bao gồm nhiều thông tin hơn mà một hàm gọi lại có thể thực hiện.

    Các đối tượng sự kiện được tạo do các thao tác trên tiện ích chứa tất cả các trường có trong đối tượng sự kiện kích hoạt theo bối cảnh, cộng với các trường chứa thông tin về tiện ích.

  • Yếu tố kích hoạt đường liên kết xem trước. Trong Google Tài liệu, Trang tính và Trang trình bày, bạn có thể định cấu hình bản xem trước đường liên kết cho các dịch vụ bên thứ ba dựa trên các mẫu URL cụ thể. Khi người dùng tương tác với một đường liên kết đáp ứng mẫu, linkPreviewTriggers sẽ kích hoạt và một đối tượng sự kiện chứa đường liên kết sẽ được truyền đến hàm gọi lại của điều kiện kích hoạt. Tiện ích bổ sung của bạn có thể sử dụng đối tượng sự kiện này để tạo một khối thông minh và thẻ hiển thị thông tin về đường liên kết trong ứng dụng lưu trữ. Bạn cũng có thể tạo các thao tác trên tiện ích để cho phép người dùng tương tác với thẻ xem trước và nội dung của thẻ.

  • Trình kích hoạt ứng dụng Google Chat. Trong Google Chat, tiện ích bổ sung của bạn sẽ xuất hiện với người dùng dưới dạng một ứng dụng Chat và người dùng có thể tương tác với tiện ích bổ sung đó bằng cách thêm tiện ích bổ sung vào không gian, gửi tin nhắn, sử dụng lệnh dấu gạch chéo, v.v. Để tạo các tính năng tương tác, bạn thiết lập và sử dụng nhiều sự kiện kích hoạt ứng dụng Chat. Mỗi điều kiện kích hoạt sẽ gửi một tải trọng đối tượng sự kiện khác nhau giúp bạn xử lý hoặc phản hồi từng loại lượt tương tác.

Cấu trúc đối tượng sự kiện

Bảng sau đây mô tả cấu trúc cấp cao nhất của các đối tượng sự kiện trong tiện ích bổ sung Google Workspace. Cấu trúc đối tượng sự kiện bao gồm một trường cấp cao nhất commonEventObject cho thông tin độc lập với máy chủ lưu trữ. Mỗi đối tượng sự kiện cũng có thể có một trong các trường cấp cao nhất dành riêng cho máy chủ lưu trữ sau đây, do ứng dụng lưu trữ đang hoạt động xác định: gmailEventObject, calendarEventObject hoặc driveEventObject.

Để tương thích ngược, các đối tượng sự kiện của tiện ích bổ sung Google Workspace cũng bao gồm tất cả các trường ban đầu được dùng trong đối tượng sự kiện hành động của tiện ích bổ sung Gmail. Các trường này được liệt kê trong bảng bên dưới trong phần "Các trường của tiện ích bổ sung Gmail ban đầu"; thông tin trong các trường này được sao chép trong cấu trúc đối tượng mới.

Đối tượng sự kiện
eventObject.commonEventObject Common fields object
Một đối tượng chứa thông tin chung cho tất cả các đối tượng sự kiện, bất kể ứng dụng lưu trữ.
eventObject.calendar Calendar event object
Chỉ xuất hiện nếu máy chủ gọi là Lịch Google. Một đối tượng chứa thông tin về lịch và sự kiện.
eventObject.chat Chat event object
Chỉ xuất hiện nếu máy chủ lưu trữ cuộc gọi là Google Chat. Một đối tượng chứa thông tin về Chat.
eventObject.drive Drive event object
Chỉ xuất hiện nếu máy chủ gọi là Google Drive. Một đối tượng chứa thông tin về Drive.
eventObject.gmail Gmail event object
Chỉ xuất hiện nếu máy chủ lưu trữ cuộc gọi là Gmail. Một đối tượng chứa thông tin về Gmail.
eventObject.docs Docs event object
Chỉ xuất hiện nếu máy chủ lưu trữ cuộc gọi là Google Tài liệu. Một đối tượng chứa thông tin về Tài liệu.
eventObject.sheets Sheets event object
Chỉ xuất hiện nếu máy chủ lưu trữ gọi là Google Trang tính. Một đối tượng chứa thông tin về Trang tính.
eventObject.slides Slides event object
Chỉ xuất hiện nếu máy chủ gọi là Google Trang trình bày. Một đối tượng chứa thông tin về Trang trình bày.
Các trường của tiện ích bổ sung gốc trong Gmail
eventObject.messageMetadata.accessToken string
Không dùng nữa. Mã truy cập. Bạn có thể dùng cách này để bật quyền truy cập vào dữ liệu người dùng bằng các phạm vi tạm thời của tiện ích bổ sung Gmail.

Đối với tiện ích bổ sung của Google Workspace, hãy tìm thông tin này trong trường eventObject.gmail.accessToken.

eventObject.messageMetadata.messageId string
Không dùng nữa. Mã thư của chuỗi thư mở trong giao diện người dùng Gmail.

Đối với tiện ích bổ sung của Google Workspace, hãy tìm thông tin này trong trường eventObject.gmail.messageId.

eventObject.clientPlatform string
Không dùng nữa. Cho biết nguồn gốc của sự kiện (web, iOS hoặc Android).

Đối với tiện ích bổ sung của Google Workspace, hãy tìm thông tin này trong trường eventObject.commonEventObject.platform.

eventObject.formInput object
Không dùng nữa. Bản đồ các giá trị hiện tại của tất cả các tiện ích biểu mẫu trong thẻ, chỉ giới hạn một giá trị cho mỗi tiện ích. Khoá là mã nhận dạng chuỗi được liên kết với các tiện ích và giá trị là các chuỗi. Đối tượng sự kiện cung cấp formInput để thuận tiện khi bạn cần đọc dữ liệu từ nhiều tiện ích có các giá trị đơn lẻ dự kiến, chẳng hạn như đầu vào văn bản và công tắc. Đối với các tiện ích có nhiều giá trị (chẳng hạn như hộp đánh dấu), bạn có thể đọc từng giá trị từ formInputs.

Đối với tiện ích bổ sung Google Workspace, hãy tìm thông tin này trong trường eventObject.commonEventObject.formInputs. Thay vào đó, các tiện ích có giá trị đơn được biểu thị dưới dạng mảng có một phần tử.

eventObject.formInputs object
Không dùng nữa. Bản đồ các giá trị hiện tại của các tiện ích trong thẻ, được trình bày dưới dạng danh sách chuỗi. Khoá là mã nhận dạng chuỗi được liên kết với tiện ích. Đối với các tiện ích có một giá trị, giá trị được trình bày trong một mảng có một phần tử. Đối với các tiện ích có nhiều giá trị (chẳng hạn như nhóm hộp đánh dấu), tất cả các giá trị đều được trình bày trong một danh sách.

Đối với tiện ích bổ sung của Google Workspace, hãy tìm thông tin này trong trường eventObject.commonEventObject.formInputs.

eventObject.parameters object
Không dùng nữa. Bản đồ của mọi tham số bổ sung mà bạn cung cấp cho Action bằng cách sử dụng Action.setParameters(). Khoá và giá trị của bản đồ là các chuỗi.

Đối với tiện ích bổ sung của Google Workspace, hãy tìm thông tin này trong trường eventObject.commonEventObject.parameters.

eventObject.userCountry string
Ngừng sử dụng và tắt theo mặc định. Mã gồm 2 chữ cái cho biết quốc gia hoặc khu vực của người dùng. Đây cũng có thể là mã quốc gia bằng số UN M49.

Đối với tiện ích bổ sung của Google Workspace, hãy tìm thông tin này trong trường eventObject.commonEventObject.userLocale.

eventObject.userLocale string
Ngừng sử dụng và tắt theo mặc định. Mã ISO 639 gồm hai chữ cái cho biết ngôn ngữ của người dùng. Hãy xem phần Truy cập vào ngôn ngữ và múi giờ của người dùng để biết thêm thông tin.

Đối với tiện ích bổ sung của Google Workspace, hãy tìm thông tin này trong trường eventObject.commonEventObject.userLocale.

eventObject.userTimezone.id string
Ngừng sử dụng và tắt theo mặc định. Giá trị nhận dạng múi giờ của múi giờ của người dùng. Ví dụ: America/New_York, Europe/Vienna và Asia/Seoul. Hãy xem phần Truy cập vào ngôn ngữ và múi giờ của người dùng để biết thêm thông tin.

Đối với tiện ích bổ sung của Google Workspace, hãy tìm thông tin này trong trường eventObject.commonEventObject.timeZone.id.

eventObject.userTimezone.offset string
Ngừng sử dụng và tắt theo mặc định. Độ lệch thời gian so với Giờ phối hợp quốc tế (UTC) của múi giờ người dùng, tính bằng mili giây. Hãy xem phần Truy cập vào ngôn ngữ và múi giờ của người dùng để biết thêm thông tin.

Đối với tiện ích bổ sung của Google Workspace, hãy tìm thông tin này trong trường eventObject.commonEventObject.timeZone.offset.

Đối tượng sự kiện chung

Đối tượng sự kiện chung là phần của đối tượng sự kiện tổng thể, mang thông tin chung, độc lập với máy chủ lưu trữ đến tiện ích bổ sung từ ứng dụng của người dùng. Thông tin này bao gồm các thông tin chi tiết như ngôn ngữ của người dùng, ứng dụng lưu trữ và nền tảng.

Ngoài trang chủ và các trình kích hoạt theo ngữ cảnh, các tiện ích bổ sung sẽ tạo và truyền các đối tượng sự kiện đến các hàm gọi lại hành động khi người dùng tương tác với các tiện ích. Hàm gọi lại của tiện ích bổ sung có thể truy vấn đối tượng sự kiện chung để xác định nội dung của các tiện ích đang mở trong ứng dụng của người dùng. Ví dụ: tiện ích bổ sung của bạn có thể xác định vị trí văn bản mà người dùng đã nhập vào một tiện ích TextInput trong đối tượng eventObject.commentEventObject.formInputs.

Các trường đối tượng sự kiện chung
commonEventObject.platform string
Cho biết nguồn gốc của sự kiện ("WEB", "IOS" hoặc "ANDROID").
commonEventObject.formInputs object
Một bản đồ chứa các giá trị hiện tại của các tiện ích trong thẻ được hiển thị. Khoá bản đồ là mã nhận dạng chuỗi được chỉ định cho mỗi tiện ích.

Cấu trúc của đối tượng giá trị bản đồ phụ thuộc vào loại tiện ích:

  • Tiện ích có một giá trị (ví dụ: hộp văn bản): danh sách các chuỗi (chỉ có một phần tử).

    Ví dụ: đối với một tiện ích nhập văn bản có employeeName làm mã nhận dạng, hãy truy cập vào giá trị nhập văn bản bằng: e.commonEventObject.formInputs.employeeName.stringInputs.value[0]

  • Tiện ích có nhiều giá trị (ví dụ: nhóm hộp đánh dấu): danh sách các chuỗi.

    Ví dụ: đối với một tiện ích có nhiều giá trị với participants làm mã nhận dạng, hãy truy cập vào mảng giá trị bằng: e.commonEventObject.formInputs.participants.stringInputs.value.

  • A date-time picker: a DateTimeInput object.

    Ví dụ: Đối với bộ chọn có mã nhận dạng là myDTPicker, hãy truy cập vào đối tượng DateTimeInput bằng cách sử dụng e.commonEventObject.formInputs.myDTPicker.dateTimeInput.

  • A date-only picker: a DateInput object.

    Ví dụ: Đối với một bộ chọn có mã nhận dạng là myDatePicker, hãy truy cập vào đối tượng DateInput bằng cách sử dụng e.commonEventObject.formInputs.myDatePicker.dateInput.

  • A time-only picker: a TimeInput object.

    Ví dụ: Đối với một bộ chọn có mã nhận dạng là myTimePicker, hãy truy cập vào đối tượng TimeInput bằng cách sử dụng e.commonEventObject.formInputs.myTimePicker.timeInput.
commonEventObject.hostApp string
Cho biết ứng dụng lưu trữ mà tiện ích bổ sung đang hoạt động khi đối tượng sự kiện được tạo. Sau đây là các giá trị có thể có:
  • GMAIL
  • CALENDAR
  • DRIVE
  • DOCS
  • SHEETS
  • SLIDES
commonEventObject.parameters object
Mọi thông số bổ sung mà bạn cung cấp cho một thao tác bằng cách sử dụng actionParameters hoặc Action.setParameters().

Bản dùng thử cho nhà phát triển: Đối với các tiện ích bổ sung mở rộng Google Chat, để đề xuất các mục dựa trên nội dung mà người dùng nhập vào trình đơn chọn nhiều, hãy sử dụng giá trị của khoá "autocomplete_widget_query" (event.commonEventObject.parameters["autocomplete_widget_query"]). Bạn có thể sử dụng giá trị này để truy vấn cơ sở dữ liệu và đề xuất các mục có thể chọn cho người dùng khi họ nhập. Để biết thông tin chi tiết, hãy xem phần Thu thập và xử lý thông tin của người dùng Google Chat.
commonEventObject.userLocale string
Tắt theo mặc định. Mã nhận dạng ngôn ngữ và quốc gia/khu vực của người dùng theo định dạng mã ngôn ngữ ISO 639 – mã quốc gia/khu vực ISO 3166. Ví dụ: en-US.

Để bật trường này, bạn phải đặt addOns.common.useLocaleFromApp thành true trong tệp kê khai của tiện ích bổ sung. Danh sách phạm vi của tiện ích bổ sung cũng phải bao gồm https://www.googleapis.com/auth/script.locale. Hãy xem phần Truy cập vào ngôn ngữ và múi giờ của người dùng để biết thêm thông tin.

commonEventObject.timeZone string
Tắt theo mặc định. Mã nhận dạng và độ lệch múi giờ. Để bật trường này, bạn phải đặt addOns.common.useLocaleFromApp thành true trong tệp kê khai của tiện ích bổ sung. Danh sách phạm vi của tiện ích bổ sung cũng phải bao gồm https://www.googleapis.com/auth/script.locale. Hãy xem phần Truy cập vào ngôn ngữ và múi giờ của người dùng để biết thêm thông tin.
commonEventObject.timeZone.id string
Giá trị nhận dạng múi giờ của múi giờ của người dùng. Ví dụ: America/New_York, Europe/Vienna và Asia/Seoul. Để bật trường này, bạn phải đặt addOns.common.useLocaleFromApp thành true trong tệp kê khai của tiện ích bổ sung. Danh sách phạm vi của tiện ích bổ sung cũng phải bao gồm https://www.googleapis.com/auth/script.locale. Hãy xem phần Truy cập vào ngôn ngữ và múi giờ của người dùng để biết thêm thông tin.
commonEventObject.timeZone.offset string
Độ lệch thời gian so với Giờ phối hợp quốc tế (UTC) của múi giờ của người dùng, tính bằng mili giây. Hãy xem phần Truy cập vào ngôn ngữ và múi giờ của người dùng để biết thêm thông tin.

Đầu vào biểu mẫu của bộ chọn ngày giờ

Hàm gọi lại của thao tác có thể nhận các giá trị hiện tại của tiện ích trong trường commonEventObject.formInputs. Điều này bao gồm các giá trị ngày hoặc giờ mà người dùng chọn trong các tiện ích bộ chọn ngày hoặc giờ. Tuy nhiên, cấu trúc của thông tin sẽ khác nhau tuỳ thuộc vào việc tiện ích được định cấu hình làm bộ chọn ngày giờ, bộ chọn chỉ ngày hoặc bộ chọn chỉ giờ. Những điểm khác biệt về cấu trúc được mô tả trong bảng sau:

Đối tượng DateTimeInput
dateTimeInput.hasDate boolean
true nếu ngày giờ đầu vào có chứa ngày; nếu false chỉ có thời gian.
dateTimeInput.hasTime boolean
true nếu ngày giờ đầu vào có chứa thời gian; nếu false chỉ có ngày.
dateTimeInput.msSinceEpoch string
Thời gian do người dùng chọn, tính bằng mili giây kể từ thời gian bắt đầu của hệ thống (00:00:00 UTC ngày 1 tháng 1 năm 1970).
Đối tượng DateInput
dateInput.msSinceEpoch string
Thời gian do người dùng chọn, tính bằng mili giây kể từ thời gian bắt đầu của hệ thống (00:00:00 UTC ngày 1 tháng 1 năm 1970).
Đối tượng TimeInput
timeInput.hours number
Số giờ do người dùng chọn.
timeInput.minutes number
Số phút do người dùng chọn.

Đối tượng sự kiện Chat

Đối tượng sự kiện Chat là phần của đối tượng sự kiện tổng thể, mang thông tin về hoạt động tương tác của người dùng với một ứng dụng Chat. Đối tượng này chỉ xuất hiện trong một đối tượng sự kiện nếu tiện ích bổ sung mở rộng Google Chat.

Chat (Trò chuyện)
chat.user object (User)
Người dùng Chat đã tương tác với ứng dụng Chat.
chat.space object (Space)
Không gian Chat nơi người dùng tương tác với ứng dụng Chat.
chat.eventTime

string (Timestamp format)

Thời điểm xảy ra lượt tương tác.

Trường nhóm payload.

payload chỉ có thể là một trong những trạng thái sau:
chat.messagePayload

object (MessagePayload)

Tải trọng mà các ứng dụng Chat nhận được từ một sự kiện kích hoạt Tin nhắn.
chat.addedToSpacePayload

object (AddedToSpacePayload)

Tải trọng mà các ứng dụng Chat nhận được từ sự kiện kích hoạt Được thêm vào không gian.
chat.removedFromSpacePayload

object (RemovedFromSpacePayload)

Tải trọng mà các ứng dụng Chat nhận được từ một sự kiện kích hoạt Bị xoá khỏi không gian.
chat.buttonClickedPayload

object (ButtonClickedPayload)

Tải trọng mà các ứng dụng Chat nhận được khi người dùng nhấp vào một nút trong tin nhắn hoặc thẻ. Nếu người dùng nhấp vào một nút để gửi thông tin, thì đối tượng commonEventObject.formInputs sẽ chứa các giá trị được thu thập từ người dùng. Để biết thông tin chi tiết, hãy xem bài viết Thu thập thông tin từ người dùng Google Chat.
chat.widgetUpdatedPayload

object (WidgetUpdatedPayload)

Tải trọng mà các ứng dụng Chat nhận được khi người dùng nhập văn bản vào trình đơn chọn nhiều mục của tiện ích selectionInput. Các ứng dụng trò chuyện có thể dùng đối tượng sự kiện này để điền các mục được đề xuất từ một nguồn dữ liệu động. Ví dụ: để điền sẵn các trường hợp hỗ trợ từ một nguồn dữ liệu bên ngoài, một ứng dụng Chat có thể truy vấn nguồn dữ liệu dựa trên nội dung mà người dùng nhập vào trình đơn, sau đó trả về mọi trường hợp hỗ trợ phù hợp dưới dạng các mục có thể chọn.

Đối tượng CommonEventObject.parameters['autocomplete_widget_query'] chứa giá trị kiểu chuỗi mà người dùng nhập vào trình đơn.

chat.appCommandPayload

object (AppCommandPayload)

Tải trọng mà các ứng dụng Chat nhận được khi người dùng sử dụng một lệnh trong ứng dụng Chat.

Phần tải

Tuỳ thuộc vào loại hoạt động tương tác của ứng dụng Chat, sự kiện này chứa một tải trọng có một hoặc nhiều tài nguyên Chat API.

Tải trọng thông báo
MessagePayload
chat.messagePayload.message object (Message)
Tin nhắn trong Chat đã kích hoạt sự kiện.
chat.messagePayload.space object (Space)
Phòng Chat nơi người dùng gửi tin nhắn đã kích hoạt ứng dụng Chat.
chat.messagePayload.configCompleteRedirectUri string
URL mà ứng dụng Chat sẽ chuyển hướng người dùng đến sau khi họ hoàn tất quy trình uỷ quyền hoặc định cấu hình bên ngoài Google Chat. Để biết thêm thông tin, hãy xem bài viết Kết nối tiện ích bổ sung Google Workspace với dịch vụ bên thứ ba.

Đã thêm vào tải trọng không gian
AddedToSpacePayload
chat.addedToSpacePayload.space object (Space)
Không gian Chat mà người dùng đã thêm hoặc cài đặt ứng dụng Chat.

Khi quản trị viên cài đặt các ứng dụng trong Chat, trường space.adminInstalled sẽ được đặt thành true.

chat.addedToSpacePayload.interactionAdd boolean
Việc người dùng thêm ứng dụng Chat vào một không gian bằng tin nhắn. Ví dụ: @đề cập đến ứng dụng Chat hoặc sử dụng một lệnh. Nếu true, Chat sẽ gửi một đối tượng sự kiện khác có messagePayload chứa thông tin về tin nhắn.
chat.addedToSpacePayload.configCompleteRedirectUri string
URL mà ứng dụng Chat sẽ chuyển hướng người dùng đến sau khi họ hoàn tất quy trình uỷ quyền hoặc định cấu hình bên ngoài Google Chat. Để biết thêm thông tin, hãy xem bài viết Kết nối tiện ích bổ sung Google Workspace với dịch vụ bên thứ ba.

Đã xoá khỏi tải trọng không gian
RemovedFromSpacePayload
chat.removedFromSpacePayload.space object (Space)
Không gian Chat mà người dùng đã xoá hoặc gỡ cài đặt ứng dụng Chat.

Khi quản trị viên gỡ cài đặt các ứng dụng trong Chat, trường space.adminInstalled sẽ được đặt thành false.

Tải trọng khi nhấp vào nút
ButtonClickedPayload
chat.buttonClickedPayload.message object (Message)
Tin nhắn Chat chứa nút mà người dùng đã nhấp vào.
chat.buttonClickedPayload.space object (Space)
Phòng Chat nơi người dùng nhấp vào một nút trong tin nhắn của ứng dụng Chat.
chat.buttonClickedPayload.isDialogEvent boolean
Người dùng có nhấp vào nút để tương tác với một hộp thoại hay không.
chat.buttonClickedPayload.dialogEventType enum (DialogEventType)
Nếu isDialogEvent là true, loại tương tác trong một hộp thoại.

Enum DialogEventType.

Giá trị của dialogEventType chỉ có thể là một trong những giá trị sau:
TYPE_UNSPECIFIED Giá trị mặc định. Không xác định.
REQUEST_DIALOG Người dùng yêu cầu một hộp thoại. Ví dụ: họ sử dụng một lệnh hoặc nhấp vào một nút trong tin nhắn.
SUBMIT_DIALOG Người dùng nhấp vào một phần tử tương tác trong hộp thoại. Ví dụ: người dùng điền thông tin vào một hộp thoại rồi nhấp vào một nút để gửi thông tin đó.

Tải trọng đã cập nhật của tiện ích
WidgetUpdatedPayload
chat.widgetUpdatedPayload.space object (Space)
Không gian Chat nơi diễn ra hoạt động tương tác.

Tải trọng lệnh ứng dụng
AppCommandPayload
chat.appCommandPayload.appCommandMetadata object (AppCommandMetadata)
Siêu dữ liệu về lệnh mà người dùng đã sử dụng và cách họ kích hoạt lệnh.
chat.appCommandPayload.space object (Space)
Phòng Chat mà người dùng đã dùng lệnh.
chat.appCommandPayload.thread object (Thread)
Nếu lượt tương tác xảy ra trong một chuỗi tin nhắn, thì đó là chuỗi tin nhắn trên Chat nơi người dùng sử dụng lệnh.
chat.appCommandPayload.message object (Message)
Đối với lệnh dấu gạch chéo, đây là tin nhắn có chứa lệnh dấu gạch chéo.
chat.appCommandPayload.configCompleteRedirectUri string
Nếu lệnh yêu cầu uỷ quyền hoặc định cấu hình, thì đây là URL để chuyển hướng người dùng đến sau khi họ hoàn tất quy trình bên ngoài Google Chat.
chat.appCommandPayload.isDialogEvent boolean
Liệu lệnh có mở một hộp thoại hay không.
chat.appCommandPayload.dialogEventType enum (DialogEventType)
Loại tương tác với một hộp thoại.

Enum DialogEventType.

Giá trị của dialogEventType chỉ có thể là một trong những giá trị sau:
TYPE_UNSPECIFIED Giá trị mặc định. Không xác định.
REQUEST_DIALOG Người dùng yêu cầu một hộp thoại. Ví dụ: họ sử dụng một lệnh hoặc nhấp vào một nút trong tin nhắn.
SUBMIT_DIALOG Người dùng nhấp vào một phần tử tương tác trong hộp thoại. Ví dụ: người dùng điền thông tin vào một hộp thoại rồi nhấp vào một nút để gửi thông tin đó.
Siêu dữ liệu lệnh ứng dụng
AppCommandMetadata
chat.appCommandPayload.appCommandMetadata.appCommandId

string (int64 format)

Mã lệnh.
chat.appCommandPayload.appCommandMetadata.appCommandType enum (AppCommandType)
Loại lệnh.

Enum AppCommandType.

Giá trị của AppCommandType chỉ có thể là một trong những giá trị sau:
APP_COMMAND_TYPE_UNSPECIFIED Giá trị mặc định. Không xác định.
SLASH_COMMAND Người dùng sử dụng lệnh bằng cách gửi một tin nhắn bắt đầu bằng dấu gạch chéo /.
QUICK_COMMAND Người dùng chọn lệnh trong trình đơn Chat ở khu vực trả lời tin nhắn.

Đối tượng sự kiện trên lịch

Đối tượng sự kiện trên Lịch là phần của đối tượng sự kiện tổng thể, chứa thông tin về lịch và sự kiện trên lịch của người dùng. Tham số này chỉ xuất hiện trong đối tượng sự kiện nếu tiện ích bổ sung mở rộng Lịch Google.

Bảng sau đây liệt kê các trường có trong trường calendarEventObject của một đối tượng sự kiện. Các trường được đánh dấu là Dữ liệu do người dùng tạo sẽ xuất hiện trong đối tượng sự kiện chỉ khi dữ liệu đó xuất hiện trong sự kiện trên Lịch và tiện ích bổ sung đặt trường addOns.calendar.currentEventAccess manifest thành READ hoặc READ_WRITE.

Đối tượng sự kiện trên lịch
calendar.attendees[] list of attendee objects
Dữ liệu do người dùng tạo. Danh sách người tham dự sự kiện trên lịch.
calendar.calendarId string
Mã lịch.
calendar.capabilities object
Dữ liệu do người dùng tạo. Một đối tượng mô tả các chức năng của tiện ích bổ sung để xem hoặc cập nhật thông tin sự kiện.
calendar.capabilities.canAddAttendees boolean
Dữ liệu do người dùng tạo. true nếu tiện ích bổ sung có thể thêm người tham dự mới vào danh sách người tham dự sự kiện; false nếu không.
calendar.capabilities.canSeeAttendees boolean
Dữ liệu do người dùng tạo. true nếu tiện ích bổ sung có thể đọc danh sách người tham dự sự kiện; false nếu không.
calendar.capabilities.canSeeConferenceData boolean
Dữ liệu do người dùng tạo. true nếu tiện ích bổ sung có thể đọc dữ liệu hội nghị của sự kiện; false nếu không.
calendar.capabilities.canSetConferenceData boolean
Dữ liệu do người dùng tạo. true nếu tiện ích bổ sung có thể cập nhật dữ liệu hội nghị của sự kiện; false nếu không.
calendar.capabilities.canAddAttachments boolean
Dữ liệu do người dùng tạo. true nếu tiện ích bổ sung có thể thêm tệp đính kèm mới vào sự kiện; false nếu không.
calendar.conferenceData Conference data object
Dữ liệu do người dùng tạo. Một đối tượng đại diện cho mọi dữ liệu về hội nghị truyền hình được liên kết với sự kiện này, chẳng hạn như thông tin chi tiết về hội nghị truyền hình trên Google Meet.
calendar.id string
Mã sự kiện.
calendar.organizer object
Một đối tượng đại diện cho người tổ chức sự kiện.
calendar.organizer.email string
Địa chỉ email của người tổ chức sự kiện.
calendar.recurringEventId string
Mã của một sự kiện định kỳ.

Người tham dự

Các đối tượng người tham dự mang thông tin về từng người tham dự sự kiện trên Lịch Google. Thông tin này có trong đối tượng sự kiện nếu và chỉ nếu dữ liệu có trong sự kiện trên Lịch và tiện ích bổ sung đặt trường addOns.calendar.currentEventAccess manifest thành READ hoặc READ_WRITE.

Đối tượng người tham dự
attendee.additionalGuests number
Số lượng khách bổ sung mà người tham dự cho biết họ sẽ mang theo. Giá trị mặc định là 0.
attendee.comment string
Bình luận phản hồi của người tham dự (nếu có).
attendee.displayName string
Tên hiển thị của người tham dự.
attendee.email string
Địa chỉ email của người tham dự.
attendee.optional boolean
true nếu trạng thái tham dự của người tham dự này được đánh dấu là không bắt buộc; false nếu không.
attendee.organizer boolean
true nếu người tham dự là người tổ chức sự kiện này.
attendee.resource boolean
true nếu người tham dự đại diện cho một tài nguyên, chẳng hạn như phòng hoặc thiết bị; false nếu không.
attendee.responseStatus string
Trạng thái phản hồi của người tham dự. Các giá trị có thể có bao gồm:
  • accepted: Khách mời đã chấp nhận lời mời tham dự sự kiện.
  • declined: Khách mời đã từ chối lời mời tham dự sự kiện.
  • needsAction: Khách mời chưa phản hồi lời mời tham dự sự kiện.
  • tentative: Khách mời đã tạm thời chấp nhận lời mời tham dự sự kiện.
attendee.self boolean
true nếu người tham dự này đại diện cho lịch mà sự kiện này xuất hiện; false nếu không.

Dữ liệu hội nghị

Các đối tượng dữ liệu hội nghị mang thông tin về những hội nghị được đính kèm vào các sự kiện trên Lịch Google. Đó có thể là các giải pháp hội nghị của Google, chẳng hạn như Google Meet, hoặc hội nghị của bên thứ ba. Thông tin này có trong đối tượng sự kiện nếu và chỉ khi dữ liệu có trong sự kiện trên Lịch và tiện ích bổ sung đặt trường addOns.calendar.currentEventAccess manifest thành READ hoặc READ_WRITE.

Đối tượng dữ liệu hội nghị
conferenceData.conferenceId string
Mã nhận dạng của hội nghị. Mã nhận dạng này nhằm mục đích cho phép các ứng dụng theo dõi các hội nghị; bạn không nên hiển thị mã nhận dạng này cho người dùng.
conferenceData.conferenceSolution object
Một đối tượng đại diện cho giải pháp hội nghị, chẳng hạn như Hangouts hoặc Google Meet.
conferenceData.conferenceSolution.iconUri string
URI cho biểu tượng mà người dùng nhìn thấy, biểu tượng này đại diện cho giải pháp hội nghị này.
conferenceData.conferenceSolution.key object
Khoá xác định duy nhất giải pháp hội nghị cho sự kiện này.
conferenceData.conferenceSolution.key.type string
Loại giải pháp hội nghị truyền hình. Các giá trị có thể có bao gồm:
  • eventHangout cho Hangouts dành cho người tiêu dùng (http://hangouts.google.com).
  • eventNamedHangout cho Hangouts phiên bản cũ dành cho người dùng Google Workspace (http://hangouts.google.com).
  • hangoutsMeet cho Google Meet (http://meet.google.com).
conferenceData.conferenceSolution.name string
Tên hiển thị cho người dùng của giải pháp hội nghị này (chưa được bản địa hoá).
conferenceData.entryPoints[] list of entry point objects
Danh sách các điểm truy cập vào hội nghị, chẳng hạn như URL hoặc số điện thoại.
conferenceData.notes string
Ghi chú bổ sung (chẳng hạn như hướng dẫn của quản trị viên miền hoặc thông báo pháp lý) về hội nghị để hiển thị cho người dùng. Có thể chứa HTML. Độ dài tối đa là 2048 ký tự.
conferenceData.parameters object
Một đối tượng chứa bản đồ dữ liệu tham số đã xác định để tiện ích bổ sung sử dụng.
conferenceData.parameters.addOnParameters object
Bản đồ gồm các khoá và giá trị chuỗi tham số. Các khoá và giá trị này do nhà phát triển tiện ích bổ sung xác định để đính kèm thông tin vào một hội nghị cụ thể cho mục đích sử dụng của tiện ích bổ sung.

Điểm mục nhập

Các đối tượng điểm truy cập mang thông tin về phương thức truy cập đã thiết lập vào một hội nghị nhất định, chẳng hạn như qua điện thoại hoặc video. Thông tin này có trong đối tượng sự kiện chỉ khi dữ liệu có trong sự kiện trên Lịch và tiện ích bổ sung đặt trường addOns.calendar.currentEventAccess manifest thành READ hoặc READ_WRITE.

Đối tượng điểm truy cập
entryPoint.accessCode string
Mã truy cập dùng để truy cập vào hội nghị. Độ dài tối đa là 128 ký tự. Các nhà cung cấp dịch vụ hội nghị thường chỉ sử dụng một nhóm nhỏ {accessCode, meetingCode, passcode, password, pin} để cấp quyền truy cập vào hội nghị. Khớp và chỉ hiển thị các trường mà nhà cung cấp dịch vụ hội nghị sử dụng.
entryPoint.entryPointFeatures list
Các tính năng của điểm truy cập. Hiện tại, các tính năng này chỉ áp dụng cho các điểm truy cập phone:
  • toll: Điểm truy cập là cuộc gọi điện thoại có tính phí.
  • toll_free: Điểm truy cập là cuộc gọi điện thoại miễn phí.
entryPoint.entryPointType string
Loại điểm truy cập. Các giá trị có thể có là: sau đây:
  • more: Hướng dẫn bổ sung về cách tham gia hội nghị, chẳng hạn như số điện thoại thay thế. Một hội nghị truyền hình chỉ có thể có một điểm truy cập more; nếu có, bạn cũng phải có ít nhất một loại điểm truy cập khác.
  • phone: Tham gia hội nghị qua số điện thoại. Một hội nghị có thể không có hoặc có nhiều điểm truy cập phone. Lịch Google chỉ hiển thị 2 điểm truy cập đầu tiên vào điện thoại, sau khi định dạng và sắp xếp theo bảng chữ cái.
  • sip: Tham gia hội nghị qua SIP. Một hội nghị truyền hình có thể có tối đa một điểm truy cập sip.
  • video: Tham gia hội nghị qua HTTP. Một hội nghị truyền hình có thể có tối đa một điểm truy cập video.
entryPoint.label string
Nhãn mà người dùng nhìn thấy cho URI điểm truy cập (chưa được bản địa hoá).
entryPoint.meetingCode string
Mã cuộc họp dùng để truy cập vào hội nghị. Độ dài tối đa là 128 ký tự. Các nhà cung cấp dịch vụ hội nghị thường chỉ sử dụng một nhóm nhỏ {accessCode, meetingCode, passcode, password, pin} để cấp quyền truy cập vào hội nghị. Khớp và chỉ hiển thị các trường mà nhà cung cấp dịch vụ hội nghị sử dụng.
entryPoint.passcode string
Mật mã dùng để truy cập vào hội nghị. Độ dài tối đa là 128 ký tự. Các nhà cung cấp dịch vụ hội nghị thường chỉ sử dụng một nhóm nhỏ {accessCode, meetingCode, passcode, password, pin} để cấp quyền truy cập vào hội nghị. Khớp và chỉ hiển thị các trường mà nhà cung cấp dịch vụ hội nghị sử dụng.
entryPoint.password string
Mật khẩu dùng để truy cập vào hội nghị. Độ dài tối đa là 128 ký tự. Các nhà cung cấp dịch vụ hội nghị thường chỉ sử dụng một nhóm nhỏ {accessCode, meetingCode, passcode, password, pin} để cấp quyền truy cập vào hội nghị. Khớp và chỉ hiển thị các trường mà nhà cung cấp dịch vụ hội nghị sử dụng.
entryPoint.pin string
Mã PIN dùng để truy cập vào hội nghị. Độ dài tối đa là 128 ký tự. Các nhà cung cấp dịch vụ hội nghị thường chỉ sử dụng một nhóm nhỏ {accessCode, meetingCode, passcode, password, pin} để cấp quyền truy cập vào hội nghị. Khớp và chỉ hiển thị các trường mà nhà cung cấp dịch vụ hội nghị sử dụng.
entryPoint.regionCode string
Mã khu vực của số điện thoại. Người dùng cần có thông tin này nếu URI không có mã quốc gia. Các giá trị dựa trên danh sách mã vùng CLDR công khai.
entryPoint.uri string
URI của điểm truy cập. Độ dài tối đa là 1.300 ký tự. Định dạng phụ thuộc vào loại điểm truy cập:
  • more: Bạn bắt buộc phải sử dụng giản đồ http: hoặc https:.
  • phone: Bạn phải có một giản đồ tel:. URI phải bao gồm toàn bộ chuỗi quay số (ví dụ: "tel:+12345678900,,,12345678;1234").
  • sip: Bạn bắt buộc phải sử dụng giản đồ sip: hoặc sips:. Ví dụ: "sip:12345678@myprovider.com".
  • video: Bạn bắt buộc phải sử dụng giản đồ http: hoặc https:.

Đối tượng sự kiện trên Drive

Đối tượng sự kiện Drive là phần của đối tượng sự kiện tổng thể, mang thông tin về Google Drive của người dùng và nội dung trong đó. Tham số này chỉ xuất hiện trong một đối tượng sự kiện nếu tiện ích bổ sung mở rộng Google Drive.

Đối tượng sự kiện trên Drive
drive.activeCursorItem Drive item object
Mục trên Drive hiện đang hoạt động.
drive.selectedItems[] list of Drive item objects
Danh sách các mục (tệp hoặc thư mục) được chọn trong Drive.

Mục trên Drive

Các đối tượng mục trên Drive mang thông tin về các mục cụ thể trên Drive, chẳng hạn như tệp hoặc thư mục.

Đối tượng mục trên Drive
item.addonHasFileScopePermission boolean
Nếu true, thì tiện ích bổ sung đã yêu cầu và nhận được uỷ quyền theo phạm vi https://www.googleapis.com/auth/drive.file cho mục này; nếu không, trường này sẽ là false.
item.id string
Mã nhận dạng của mặt hàng được chọn.
item.iconUrl string
URL của biểu tượng đại diện cho mục đã chọn.
item.mimeType string
Loại MIME của mục đã chọn.
item.title string
Tiêu đề của mục đã chọn.

Đối tượng sự kiện Gmail

Đối tượng sự kiện Gmail là phần của đối tượng sự kiện tổng thể, mang thông tin về thư của người dùng trên Gmail. Tham số này chỉ xuất hiện trong một đối tượng sự kiện nếu ứng dụng lưu trữ là Gmail.

Đối tượng sự kiện Gmail
gmail.accessToken string
Mã thông báo truy cập dành riêng cho Gmail. Bạn có thể dùng mã thông báo này với phương thức GmailApp.setCurrentMessageAccessToken(accessToken) để cấp cho tiện ích bổ sung của bạn quyền truy cập tạm thời vào thư Gmail hiện đang mở của người dùng hoặc cho phép tiện ích bổ sung của bạn soạn thảo thư nháp mới.
gmail.bccRecipients[] list of strings
Tắt theo mặc định. Danh sách địa chỉ email của người nhận "BCC:" hiện có trong bản nháp mà tiện ích bổ sung đang soạn. Để bật trường này, bạn phải đặt trường addOns.gmail.composeTrigger.draftAccess trong tệp kê khai thành METADATA.
gmail.ccRecipients[] list of strings
Tắt theo mặc định. Danh sách địa chỉ email của người nhận "CC:" hiện có trong bản nháp mà tiện ích bổ sung đang soạn. Để bật trường này, bạn phải đặt trường addOns.gmail.composeTrigger.draftAccess trong tệp kê khai thành METADATA.
gmail.messageId string
Mã của thư trong Gmail hiện đang mở.
gmail.threadId string
Mã nhận dạng chuỗi email hiện đang mở trong Gmail.
gmail.toRecipients[] list of strings
Tắt theo mặc định. Danh sách địa chỉ email của người nhận "Đến:" hiện có trong bản nháp mà tiện ích bổ sung đang soạn. Để bật trường này, bạn phải đặt trường addOns.gmail.composeTrigger.draftAccess trong tệp kê khai thành METADATA.

Đối tượng sự kiện trên Tài liệu

Đối tượng sự kiện Docs là phần của đối tượng sự kiện tổng thể, mang thông tin về tài liệu của người dùng và nội dung của tài liệu đó. Tham số này chỉ xuất hiện trong một đối tượng sự kiện nếu tiện ích bổ sung mở rộng Google Tài liệu.

Đối tượng sự kiện trên Tài liệu
docs.id string
Chỉ xuất hiện nếu người dùng đã uỷ quyền cho phạm vi https://www.googleapis.com/auth/drive.file.
Mã nhận dạng của tài liệu được mở trong giao diện người dùng của Docs.
docs.title string
Chỉ xuất hiện nếu người dùng đã uỷ quyền cho phạm vi https://www.googleapis.com/auth/drive.file.
Tiêu đề của tài liệu được mở trong giao diện người dùng của Docs.
docs.addonHasFileScopePermission boolean
Nếu true, tiện ích bổ sung đã yêu cầu và nhận được uỷ quyền phạm vi https://www.googleapis.com/auth/drive.file cho tài liệu được mở trong giao diện người dùng Tài liệu; nếu không, trường này sẽ là false.
docs.matchedUrl.url string
Chỉ xuất hiện nếu đáp ứng các điều kiện sau:
  • https://www.googleapis.com/auth/workspace.linkpreview đã được người dùng uỷ quyền.
  • URL khớp với mẫu máy chủ được chỉ định trong điều kiện kích hoạt LinkPreviewTriggers.

URL của đường liên kết tạo bản xem trước trong Google Tài liệu. Để sử dụng trường này, bạn phải định cấu hình LinkPreviewTriggers trong tệp kê khai của tiện ích bổ sung. Hãy xem phần Xem trước đường liên kết bằng khối thông minh để biết thêm thông tin chi tiết.

Ví dụ về tải trọng khi người dùng xem trước đường liên kết https://www.example.com/12345: 

"docs" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}

Đối tượng sự kiện trên Trang tính

Đối tượng sự kiện Sheets là phần của đối tượng sự kiện tổng thể, mang thông tin về tài liệu của người dùng và nội dung của tài liệu đó. Tham số này chỉ xuất hiện trong một đối tượng sự kiện nếu tiện ích bổ sung mở rộng Google Trang tính.

Đối tượng sự kiện trên Trang tính
sheets.id string
Chỉ xuất hiện nếu người dùng đã uỷ quyền cho phạm vi https://www.googleapis.com/auth/drive.file. Mã nhận dạng của bảng tính mở trong giao diện người dùng Trang tính.
sheets.title string
Chỉ xuất hiện nếu người dùng đã uỷ quyền cho phạm vi https://www.googleapis.com/auth/drive.file. Tiêu đề của bảng tính sẽ mở ra trong giao diện người dùng Trang tính.
sheets.addonHasFileScopePermission boolean
Nếu true, thì tiện ích bổ sung đã yêu cầu và nhận được uỷ quyền phạm vi https://www.googleapis.com/auth/drive.file cho bảng tính mở trong giao diện người dùng Trang tính; nếu không, trường này sẽ là false.
sheets.matchedUrl.url string
Chỉ xuất hiện nếu đáp ứng các điều kiện sau:
  • https://www.googleapis.com/auth/workspace.linkpreview đã được người dùng uỷ quyền.
  • URL khớp với mẫu máy chủ được chỉ định trong điều kiện kích hoạt LinkPreviewTriggers.

URL của đường liên kết tạo bản xem trước trong Google Trang tính. Để sử dụng trường này, bạn phải định cấu hình LinkPreviewTriggers trong tệp kê khai của tiện ích bổ sung. Hãy xem phần Xem trước đường liên kết bằng khối thông minh để biết thêm thông tin chi tiết.

Ví dụ về tải trọng khi người dùng xem trước đường liên kết https://www.example.com/12345:

"sheets" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}

Đối tượng sự kiện trên Trang trình bày

Đối tượng sự kiện Trang trình bày là phần của đối tượng sự kiện tổng thể, mang thông tin về tài liệu của người dùng và nội dung của tài liệu đó. Tham số này chỉ xuất hiện trong một đối tượng sự kiện nếu tiện ích bổ sung mở rộng Google Trang trình bày.

Đối tượng sự kiện trên Trang trình bày
slides.id string
Chỉ xuất hiện nếu người dùng đã uỷ quyền cho phạm vi https://www.googleapis.com/auth/drive.file. Mã nhận dạng của bản trình bày đang mở trong giao diện người dùng Trang trình bày.
slides.title string
Chỉ xuất hiện nếu người dùng đã uỷ quyền cho phạm vi https://www.googleapis.com/auth/drive.file. Tiêu đề của bản trình bày mở trong giao diện người dùng Trang trình bày.
slides.addonHasFileScopePermission boolean
Nếu true, thì tiện ích bổ sung đã yêu cầu và nhận được uỷ quyền phạm vi https://www.googleapis.com/auth/drive.file cho bản trình bày mở trong giao diện người dùng Trang trình bày; nếu không, trường này sẽ là false.
slides.matchedUrl.url string
Chỉ xuất hiện nếu đáp ứng các điều kiện sau:
  • https://www.googleapis.com/auth/workspace.linkpreview đã được người dùng uỷ quyền.
  • URL khớp với mẫu máy chủ được chỉ định trong điều kiện kích hoạt LinkPreviewTriggers.

URL của đường liên kết tạo bản xem trước trong Google Trang trình bày. Để sử dụng trường này, bạn phải định cấu hình LinkPreviewTriggers trong tệp kê khai của tiện ích bổ sung. Hãy xem phần Xem trước đường liên kết bằng khối thông minh để biết thêm thông tin chi tiết.

Ví dụ về tải trọng khi người dùng xem trước đường liên kết https://www.example.com/12345:

"slides" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}