Đố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 trong 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ố để kích hoạt hoặc gọi lại các hàm 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.

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

• Trình kích hoạt 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 điều kiện 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 điều kiện 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 sự kiện kích hoạt trang chủ không chứa tất cả các trường có trong hai trường hợp khác; các trường liên quan đến tiện ích và thông tin theo ngữ cảnh bị bỏ qua.

• Trình 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 trình kích hoạt theo bối cảnh khác nhau sẽ kích hoạt khi người dùng nhập 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 ngữ cảnh cho thời điểm người dùng mở thư và một điều kiện kích hoạt khác cho thời điểm người dùng soạn thư.
  • Lịch Google cung cấp một điều kiện kích hoạt theo ngữ cảnh cho thời điểm người dùng mở một sự kiện.
  • Google Drive cung cấp một trình kích hoạt theo ngữ cảnh cho thời điểm người dùng chọn tệp trên Drive.

  Khi một trình kích hoạt theo ngữ 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 tiện ích bổ sung, truyền đối tượng sự kiện dưới dạng tham số. Các đối tượng sự kiện được tạo khi trình kích hoạt theo ngữ cảnh kích hoạt chứa tất cả các trường có trong đối tượng sự kiện trình kích hoạt trang chủ, cùng với các trường chứa thông tin theo ngữ cảnh.

• Thao tác với tiện ích. Các đối tượng sự kiện cũng được dùng để cung cấp tính tương tác của 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. Các tiện ích bổ sung của 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, đối tượng sự kiện hành động còn bao gồm nhiều thông tin hơn mà hàm gọi lại có thể xử lý.

  Các đối tượng sự kiện được tạo do các hành động của tiện ích chứa tất cả các trường có trong đối tượng sự kiện của trình 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.

• Xem trước trình kích hoạt đường liên kết. 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ụ của 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 vào hàm gọi lại của trình 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 hành động 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 (Bản dùng thử cho nhà phát triển). Trong Google Chat, tiện ích bổ sung của bạn sẽ xuất hiện dưới dạng một ứng dụng Chat. 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 vào không gian, gửi tin nhắn, sử dụng lệnh dấu gạch chéo, v.v. Để xây dựng các tính năng tương tác, bạn thiết lập và sử dụng nhiều trình kích hoạt ứng dụng Chat. Mỗi trình kích hoạt sẽ gửi một trọng tải đố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 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 của Google Workspace. Cấu trúc đối tượng sự kiện bao gồm 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ủ 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 sử dụng trong các đố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 dưới đây trong phần "Các trường tiện ích bổ sung ban đầu của Gmail"; thông tin trong các trường này được tái tạo trong cấu trúc đối tượng mới.

Đối tượng sự kiện phổ biến

Đối tượng sự kiện chung là một 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ủ đế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 chi tiết như ngôn ngữ, ứng dụng lưu trữ và nền tảng của người dùng.

Ngoài trình kích hoạt theo ngữ cảnh và trang chủ, các tiện ích bổ sung còn tạo và truyền đối tượng sự kiện đến hàm gọi lại thao tác khi người dùng tương tác với 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 tiện ích TextInput trong đối tượng eventObject.commentEventObject.formInputs.

Dữ liệu đầu vào của biểu mẫu bộ chọn ngày giờ

Hàm gọi lại thao tác có thể nhận giá trị tiện ích hiện tại trong trường commonEventObject.formInputs. Dữ liệu này bao gồm các giá trị ngày hoặc giờ mà người dùng đã chọn trong 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 dưới dạng bộ chọn ngày-giờ, bộ chọn chỉ ngày hoặc bộ chọn chỉ giờ. Các điểm khác biệt về cấu trúc được mô tả trong bảng sau:

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

Đối tượng sự kiện Lịch là một 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. Thuộc tính này chỉ xuất hiện trong đối tượng sự kiện nếu ứng dụng lưu trữ là Lịch Google.

Bảng sau đây liệt kê các trường có trong trường calendarEventObject của đố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 nếu và chỉ khi dữ liệu đó xuất hiện trong sự kiện Lịch và tiện ích bổ sung đặt trường manifest addOns.calendar.currentEventAccess thành READ hoặc READ_WRITE.

Người tham dự

Đối tượng người tham dự chứa thông tin về từng người tham dự sự kiện trong Lịch Google. 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 Lịch và tiện ích bổ sung đặt trường manifest addOns.calendar.currentEventAccess thành READ hoặc READ_WRITE.

Dữ liệu hội nghị

Đối tượng dữ liệu hội nghị chứa thông tin về các hội nghị được đính kèm vào sự kiện trên Lịch Google. Đây 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 Lịch và tiện ích bổ sung đặt trường manifest addOns.calendar.currentEventAccess thành READ hoặc READ_WRITE.

Điểm mục nhập

Các đối tượng điểm truy cập chứa 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 nếu và chỉ khi dữ liệu có trong sự kiện Lịch và tiện ích bổ sung đặt trường manifest addOns.calendar.currentEventAccess thành READ hoặc READ_WRITE.

Đối tượng sự kiện của Drive

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

Mục trên Drive

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

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

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

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

Đối tượng sự kiện của Docs là một phần của đối tượng sự kiện tổng thể, chứa thông tin về tài liệu của người dùng và nội dung của tài liệu đó. Thuộc tính này chỉ xuất hiện trong đối tượng sự kiện nếu ứng dụng lưu trữ là Google Tài liệu.

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

Đối tượng sự kiện của Trang tính

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

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

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

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

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