ออบเจ็กต์เหตุการณ์

หน้านี้จะอธิบายโครงสร้างของออบเจ็กต์เหตุการณ์ของส่วนเสริม Google Workspace

ออบเจ็กต์เหตุการณ์คือโครงสร้าง JSON ที่สร้างขึ้นโดยอัตโนมัติและส่งผ่าน เป็นพารามิเตอร์ไปยังฟังก์ชันทริกเกอร์หรือฟังก์ชันเรียกกลับเมื่อผู้ใช้โต้ตอบกับ ส่วนเสริม ออบเจ็กต์เหตุการณ์จะนำข้อมูลฝั่งไคลเอ็นต์เกี่ยวกับแอปโฮสต์และบริบทปัจจุบันไปยังฟังก์ชันเรียกกลับฝั่งเซิร์ฟเวอร์ของส่วนเสริม

ส่วนเสริมของ Google Workspace จะใช้ออบเจ็กต์เหตุการณ์ในที่ต่อไปนี้

• ทริกเกอร์หน้าแรก ระบบจะส่งออบเจ็กต์เหตุการณ์ ไปยังฟังก์ชัน homepageTrigger ทุกฟังก์ชันที่คุณกำหนดโดยอัตโนมัติเมื่อฟังก์ชันทริกเกอร์หน้าแรกเริ่มทำงาน คุณสามารถใช้ออบเจ็กต์นี้ในฟังก์ชันทริกเกอร์หน้าแรกเพื่อระบุแอปโฮสต์ที่ใช้งานอยู่ แพลตฟอร์มของไคลเอ็นต์ ภาษาของผู้ใช้ และข้อมูลอื่นๆ

  ออบเจ็กต์เหตุการณ์ที่สร้างขึ้นเมื่อทริกเกอร์หน้าแรกเริ่มทำงานจะไม่มีฟิลด์ทั้งหมดที่รวมอยู่ในอีก 2 กรณี โดยจะไม่มีฟิลด์ที่เกี่ยวข้องกับวิดเจ็ตและข้อมูลตามบริบท

• ทริกเกอร์ตามบริบท แอปพลิเคชันโฮสต์แต่ละรายการมีชุดทริกเกอร์ตามบริบทที่แตกต่างกัน ซึ่งจะ ทํางานเมื่อผู้ใช้เข้าสู่บริบทที่เฉพาะเจาะจง เช่น

  • Gmail มีทริกเกอร์ตามบริบทเมื่อผู้ใช้เปิดข้อความ และอีกทริกเกอร์เมื่อผู้ใช้เขียนข้อความ
  • Google ปฏิทินมีทริกเกอร์ตามบริบทเมื่อผู้ใช้เปิดกิจกรรม
  • Google ไดรฟ์มีทริกเกอร์ตามบริบทเมื่อผู้ใช้เลือกไฟล์ในไดรฟ์

  เมื่อทริกเกอร์ตามบริบททํางาน แอปพลิเคชันโฮสต์จะเรียกใช้runFunctionที่เกี่ยวข้องซึ่งระบุไว้ในไฟล์ Manifest ของส่วนเสริม โดยส่งออบเจ็กต์เหตุการณ์เป็นพารามิเตอร์ ออบเจ็กต์เหตุการณ์ที่สร้างขึ้นเมื่อทริกเกอร์ตามบริบททํางานจะมีช่องทั้งหมดที่รวมอยู่ในออบเจ็กต์เหตุการณ์ทริกเกอร์หน้าแรก รวมถึงช่องที่มีข้อมูลตามบริบท

• การดำเนินการของวิดเจ็ต นอกจากนี้ยังใช้ออบเจ็กต์เหตุการณ์ เพื่อมอบการโต้ตอบของวิดเจ็ต โดยใช้รูปแบบการดำเนินการเดียวกันกับที่ส่วนเสริม Gmail ใช้ ส่วนเสริมของ Google Workspace ใช้ฟังก์ชันตัวแฮนเดิลวิดเจ็ต Action ออบเจ็กต์ และการตอบกลับการดำเนินการ ทั้งหมดเหมือนกัน อย่างไรก็ตาม ในส่วนเสริมของ Google Workspace ออบเจ็กต์เหตุการณ์การดำเนินการ จะมีข้อมูลเพิ่มเติมที่ฟังก์ชันการเรียกกลับสามารถดำเนินการได้

  ออบเจ็กต์เหตุการณ์ที่สร้างขึ้นเป็นผลจากการกระทำของวิดเจ็ตจะมีฟิลด์ทั้งหมด ที่รวมอยู่ในออบเจ็กต์เหตุการณ์ทริกเกอร์ตามบริบท รวมถึงฟิลด์ที่มี ข้อมูลวิดเจ็ต

• ทริกเกอร์ลิงก์ตัวอย่าง ใน Google เอกสาร, ชีต และสไลด์ คุณสามารถ กำหนดค่าตัวอย่างลิงก์สำหรับบริการของบุคคลที่สาม ตามรูปแบบ URL ที่เฉพาะเจาะจงได้ เมื่อผู้ใช้โต้ตอบกับลิงก์ที่ตรงกับรูปแบบ linkPreviewTriggers จะทริกเกอร์ และระบบจะส่งออบเจ็กต์เหตุการณ์ที่มีลิงก์ไปยังฟังก์ชันเรียกกลับของทริกเกอร์ ส่วนเสริมของคุณสามารถใช้ออบเจ็กต์เหตุการณ์นี้เพื่อสร้างชิปอัจฉริยะและการ์ดที่แสดงข้อมูลเกี่ยวกับลิงก์ภายในแอปพลิเคชันโฮสต์ นอกจากนี้ คุณยังสร้างการดำเนินการของวิดเจ็ตเพื่อให้ผู้ใช้โต้ตอบกับ การ์ดตัวอย่างและเนื้อหาของการ์ดได้ด้วย

• ทริกเกอร์ของแอป Google Chat ใน Google Chat ส่วนเสริมจะปรากฏต่อผู้ใช้เป็นแอป Chat และผู้ใช้สามารถโต้ตอบกับส่วนเสริมได้โดยการเพิ่มส่วนเสริมไปยังพื้นที่ทำงาน ส่งข้อความ ใช้คำสั่งเครื่องหมายทับ และอื่นๆ หากต้องการสร้างฟีเจอร์แบบอินเทอร์แอกทีฟ คุณต้องตั้งค่าและใช้ทริกเกอร์แอป Chat ต่างๆ ทริกเกอร์แต่ละรายการจะส่ง เพย์โหลดออบเจ็กต์เหตุการณ์ที่แตกต่างกัน ซึ่งจะช่วย ให้คุณประมวลผลหรือตอบสนองต่อการโต้ตอบแต่ละประเภทได้

โครงสร้างออบเจ็กต์เหตุการณ์

ตารางต่อไปนี้อธิบายโครงสร้างระดับบนสุดของ ออบเจ็กต์เหตุการณ์ของส่วนเสริม Google Workspace โครงสร้างออบเจ็กต์เหตุการณ์มีฟิลด์ระดับบนสุด commonEventObject สำหรับข้อมูลที่ไม่ขึ้นอยู่กับโฮสต์ ออบเจ็กต์เหตุการณ์แต่ละรายการยังมีฟิลด์ระดับบนสุดที่เฉพาะเจาะจงโฮสต์ต่อไปนี้ได้ด้วย โดยพิจารณาจากแอปโฮสต์ที่ใช้งานอยู่ ได้แก่ gmailEventObject, calendarEventObject หรือ driveEventObject

ส่วนเสริมของ Google Workspace ออบเจ็กต์เหตุการณ์ยังมีฟิลด์เดิมทั้งหมดที่ใช้ใน ออบเจ็กต์เหตุการณ์การดำเนินการของส่วนเสริม Gmail เพื่อให้ใช้งานร่วมกับเวอร์ชันก่อนหน้าได้ ฟิลด์เหล่านี้แสดงอยู่ในตารางด้านล่างในส่วน "ฟิลด์ส่วนเสริม Gmail เดิม" ข้อมูลในฟิลด์เหล่านี้จะทำซ้ำในโครงสร้างออบเจ็กต์ใหม่

ออบเจ็กต์เหตุการณ์ทั่วไป

ออบเจ็กต์เหตุการณ์ทั่วไปคือส่วนของออบเจ็กต์เหตุการณ์โดยรวมที่มีข้อมูลทั่วไปที่ไม่ขึ้นกับโฮสต์ซึ่งส่งไปยังส่วนเสริมจากไคลเอ็นต์ของผู้ใช้ ข้อมูลนี้มีรายละเอียดต่างๆ เช่น ภาษาของผู้ใช้ แอปโฮสต์ และแพลตฟอร์ม

นอกจากทริกเกอร์ในหน้าแรกและตามบริบทแล้ว ส่วนเสริมยังสร้างและส่งออบเจ็กต์เหตุการณ์ไปยังฟังก์ชันการเรียกกลับของการดำเนินการ เมื่อผู้ใช้โต้ตอบกับวิดเจ็ต ฟังก์ชันเรียกกลับของส่วนเสริมจะค้นหาออบเจ็กต์เหตุการณ์ทั่วไปเพื่อกำหนดเนื้อหาของวิดเจ็ตที่เปิดอยู่ในไคลเอ็นต์ของผู้ใช้ได้ เช่น ส่วนเสริมสามารถค้นหาข้อความที่ผู้ใช้ป้อนลงในวิดเจ็ต TextInput ในออบเจ็กต์ eventObject.commentEventObject.formInputs ได้

อินพุตแบบฟอร์มเครื่องมือเลือกวันที่และเวลา

ฟังก์ชันเรียกกลับการดำเนินการ จะรับค่าปัจจุบันของวิดเจ็ตในช่อง commonEventObject.formInputs ได้ ซึ่งรวมถึงค่าวันที่หรือเวลาที่ผู้ใช้เลือกในวิดเจ็ตเครื่องมือเลือกวันที่หรือเวลา อย่างไรก็ตาม โครงสร้างของข้อมูลจะแตกต่างกันไป ขึ้นอยู่กับว่าได้กำหนดค่า วิดเจ็ตเป็นเครื่องมือเลือกวันที่และเวลา เครื่องมือเลือกวันที่เท่านั้น หรือเครื่องมือเลือกเวลาเท่านั้น ความแตกต่างเชิงโครงสร้างมีคำอธิบายในตารางต่อไปนี้

ออบเจ็กต์เหตุการณ์แชท

ออบเจ็กต์เหตุการณ์ของ Chat คือส่วนหนึ่งของออบเจ็กต์เหตุการณ์โดยรวม ซึ่งมีข้อมูลเกี่ยวกับการโต้ตอบของผู้ใช้กับ แอป Chat โดยจะอยู่ในออบเจ็กต์เหตุการณ์ก็ต่อเมื่อส่วนเสริมขยาย Google Chat

เพย์โหลด

เหตุการณ์จะมีเพย์โหลดที่มีทรัพยากร Chat API อย่างน้อย 1 รายการ ทั้งนี้ขึ้นอยู่กับประเภทของการโต้ตอบกับแอป Chat

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

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

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