จัดการเวลาที่ต้องการสมาธิ การลางาน และกิจกรรมสถานที่ทำงาน

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

ใน Google ปฏิทิน ผู้ใช้สามารถสร้างกิจกรรมเวลาที่ต้องการสมาธิ ลางาน และสถานที่ทำงานเพื่อระบุสถานะและสถานที่ตั้งที่กำหนดเอง ฟีเจอร์เหล่านี้พร้อมใช้งานในปฏิทินหลักและสำหรับผู้ใช้ Google ปฏิทินบางรายเท่านั้น

โปรดดูรายละเอียดเพิ่มเติมที่หัวข้อใช้เวลาสมาธิใน Google ปฏิทิน และเปิดหรือปิดสถานที่ทํางานสําหรับผู้ใช้

อ่านและแสดงรายการเหตุการณ์สถานะปฏิทิน

คุณสามารถอ่านและแสดงรายการเหตุการณ์สถานะปฏิทินในแหล่งข้อมูล Events ของปฏิทิน API

หากต้องการอ่านเหตุการณ์สถานะ ให้ใช้เมธอด events.get โดยระบุ eventId ของเหตุการณ์

หากต้องการแสดงรายการเหตุการณ์สถานะ ให้ใช้เมธอด events.list โดยระบุค่าต่อไปนี้อย่างน้อย 1 ค่าในช่อง eventTypes

• 'focusTime'
• 'outOfOffice'
• 'workingLocation'

จากนั้นในออบเจ็กต์ Event ที่แสดง ให้ตรวจสอบว่าช่อง eventType มีค่าที่ขอ และดูรายละเอียดเกี่ยวกับสถานะที่ผู้ใช้สร้างขึ้นใน Google ปฏิทินจากช่องที่เกี่ยวข้อง

• focusTimeProperties
• outOfOfficeProperties
• workingLocationProperties

สมัครรับข้อมูลการเปลี่ยนแปลงในเหตุการณ์สถานะ

คุณสามารถสมัครรับข้อมูลการเปลี่ยนแปลงในเหตุการณ์สถานะในทรัพยากร Events ของปฏิทิน API

ใช้เมธอด events.watch โดยระบุ calendarId ของปฏิทินที่จะสมัครรับข้อมูล และค่าต่อไปนี้อย่างน้อย 1 ค่าในช่อง eventTypes

• 'focusTime'
• 'outOfOffice'
• 'workingLocation'

สร้างและอัปเดตเหตุการณ์สถานะปฏิทิน

หากต้องการสร้างเหตุการณ์สถานะ ให้สร้างอินสแตนซ์ของแหล่งข้อมูล Events โดยใช้เมธอด events.insert โดยตั้งค่าช่องที่ต้องกรอกสำหรับประเภทเหตุการณ์

หากคุณอัปเดตเหตุการณ์สถานะโดยใช้เมธอด events.update เหตุการณ์ต้องรักษาช่องที่ต้องกรอกไว้

สร้างเวลาที่ต้องการสมาธิ

วิธีสร้างกิจกรรมที่ต้องการสมาธิ

• ตั้งค่า eventType เป็น 'focusTime'
• ใส่ช่อง focusTimeProperties
• ตั้งค่าช่อง transparency เป็น 'opaque'
• ตั้งค่าช่อง start และ end ของกิจกรรมให้เป็นกิจกรรมแบบกำหนดเวลา (โดยระบุเวลาเริ่มต้นและเวลาสิ้นสุด)
  เวลาที่ต้องการสมาธิต้องไม่ใช่กิจกรรมตลอดทั้งวัน

โปรดดูรายละเอียดฟีเจอร์ที่หัวข้อใช้การกำหนดเวลาที่ต้องการสมาธิใน Google ปฏิทิน

สร้างการแจ้งการลางาน

วิธีสร้างเหตุการณ์แจ้งการลางาน

• ตั้งค่า eventType เป็น 'outOfOffice'
• ใส่ช่อง outOfOfficeProperties
• ตั้งค่าช่อง transparency เป็น 'opaque'
• ตั้งค่าช่อง start และ end ของกิจกรรมให้เป็นกิจกรรมแบบกำหนดเวลา (โดยระบุเวลาเริ่มต้นและเวลาสิ้นสุด)
  กิจกรรมลางานต้องไม่ใช่กิจกรรมตลอดวัน

โปรดดูรายละเอียดฟีเจอร์ที่หัวข้อแจ้งให้ผู้อื่นทราบเมื่อคุณลางาน

สร้างสถานที่ทํางาน

วิธีสร้างเหตุการณ์สถานที่ทํางาน

• ตั้งค่า eventType เป็น 'workingLocation'
• ใส่ช่อง workingLocationProperties
• ตั้งค่าช่อง visibility เป็น 'public'
• ตั้งค่าช่อง transparency เป็น 'transparent'

• ตั้งค่าฟิลด์ start และ end ของเหตุการณ์เป็นค่าใดค่าหนึ่งต่อไปนี้

  • กิจกรรมแบบกำหนดเวลา (ระบุเวลาเริ่มต้นและสิ้นสุด)
  • กิจกรรมที่จัดทั้งวัน (ระบุวันที่เริ่มต้นและวันที่สิ้นสุด) ซึ่งครอบคลุมเวลา 1 วัน

  กิจกรรมสถานที่ทํางานตลอดวันจะครอบคลุมหลายวันไม่ได้ แต่กิจกรรมแบบกำหนดเวลาจะครอบคลุมได้

ฟิลด์ต่อไปนี้เป็นฟิลด์ที่ไม่บังคับ แต่เราขอแนะนำให้กรอกเพื่อให้ผู้ใช้ได้รับประสบการณ์การใช้งานที่ดีที่สุดเมื่อแทรก officeLocation

• workingLocationProperties.officeLocation.buildingId: ค่านี้ควรตรงกับ buildingId ในฐานข้อมูลทรัพยากรขององค์กร ซึ่งจะช่วยให้ผู้ใช้ได้รับประโยชน์จากฟีเจอร์ทั้งหมดของปฏิทิน เช่น คำแนะนำห้องประชุม
• workingLocationProperties.officeLocation.label: นี่คือป้ายกำกับที่แสดงในปฏิทินบนเว็บและไคลเอ็นต์บนอุปกรณ์เคลื่อนที่ คุณสามารถดึงข้อมูลรหัสอาคารและป้ายกำกับอาคารได้โดยใช้วิธี resources.buildings.list

ระบบไม่รองรับการสร้างและการอัปเดตเหตุการณ์สถานที่ทํางานผ่านปลายทางกลุ่ม

ดูรายละเอียดฟีเจอร์ได้ที่หัวข้อกำหนดเวลาและสถานที่ทำงาน และเปิดหรือปิดสถานที่ทำงานสำหรับผู้ใช้

วิธีแสดงเหตุการณ์สถานที่ทํางานที่ทับซ้อนกัน

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

• กิจกรรมที่กำหนดเวลาไว้จะมีความสำคัญเหนือกิจกรรมตลอดทั้งวัน
• เหตุการณ์เดี่ยวจะมีลําดับความสําคัญเหนือเหตุการณ์ที่เกิดซ้ำและข้อยกเว้นของเหตุการณ์เหล่านั้น
• กิจกรรมที่เริ่มช้ากว่าจะมีลำดับความสำคัญสูงกว่ากิจกรรมที่เริ่มเร็วกว่า
• เหตุการณ์ที่มีระยะเวลาสั้นกว่าจะมีความสําคัญเหนือกว่าเหตุการณ์ที่มีระยะเวลานานกว่า
• เหตุการณ์ที่สร้างล่าสุดจะมีความสําคัญเหนือกว่าเหตุการณ์ที่สร้างไว้ก่อนหน้านี้
• กิจกรรมที่ทับซ้อนกันบางส่วนควรแสดงเป็นกิจกรรม 2 รายการที่แตกต่างกัน โดยแต่ละกิจกรรมจะมีสถานที่ทำงานของตัวเอง

สร้างเหตุการณ์สถานะใน Google Apps Script

Google Apps Script คือภาษาสคริปต์ในระบบคลาวด์ที่อิงตาม JavaScript ซึ่งช่วยให้คุณสร้างแอปพลิเคชันทางธุรกิจที่ผสานรวมกับ Google Workspace ได้ สคริปต์จะพัฒนาในตัวแก้ไขโค้ดบนเบราว์เซอร์ และระบบจะจัดเก็บและเรียกใช้สคริปต์เหล่านั้นในเซิร์ฟเวอร์ของ Google โปรดดูGoogle Apps Script เริ่มต้นใช้งานเพื่อเริ่มใช้ Apps Script ในการส่งคำขอไปยัง Google Calendar API

วิธีการต่อไปนี้อธิบายวิธีจัดการเหตุการณ์สถานะโดยใช้ Google Calendar API เป็นบริการขั้นสูงใน Google Apps Script ดูรายการแหล่งข้อมูลและเมธอดทั้งหมดของ Google ปฏิทิน API ได้ที่เอกสารอ้างอิง

สร้างและตั้งค่าสคริปต์

1. สร้างสคริปต์โดยไปที่ script.google.com/create
2. ในแผงด้านซ้าย ข้างบริการ ให้คลิกเพิ่มบริการ
3. เลือก Google Calendar API แล้วคลิกเพิ่ม
4. หลังจากเปิดใช้แล้ว API จะปรากฏในแผงด้านซ้าย คุณสามารถแสดงเมธอดและคลาสที่ใช้ได้ใน API โดยใช้คีย์เวิร์ด Calendar ในเครื่องมือแก้ไข

(ไม่บังคับ) อัปเดตโปรเจ็กต์ Google Cloud

โปรเจ็กต์ Google Apps Script แต่ละโปรเจ็กต์จะมีโปรเจ็กต์ Google Cloud ที่เกี่ยวข้อง สคริปต์ของคุณสามารถใช้โปรเจ็กต์เริ่มต้นที่ Google Apps Script สร้างโดยอัตโนมัติ หากต้องการใช้โปรเจ็กต์ Google Cloud ที่กําหนดเอง ให้ทําตามขั้นตอนต่อไปนี้เพื่ออัปเดตโปรเจ็กต์ที่เชื่อมโยงกับสคริปต์

1. คลิกการตั้งค่าโปรเจ็กต์ ทางด้านซ้ายของเครื่องมือแก้ไข
2. ในส่วนโปรเจ็กต์ Google Cloud Platform (GCP) ให้คลิกเปลี่ยนโปรเจ็กต์
3. ป้อนหมายเลขโปรเจ็กต์ Google Cloud ที่อยู่ในโปรแกรมตัวอย่างสำหรับนักพัฒนาซอฟต์แวร์ แล้วคลิกตั้งค่าโปรเจ็กต์
4. ทางด้านซ้าย ให้เลือก "เครื่องมือแก้ไข" เพื่อกลับไปที่เครื่องมือแก้ไขโค้ด

เพิ่มโค้ดลงในสคริปต์

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีสร้าง อ่าน และแสดงรายการเหตุการณ์สถานะในปฏิทินหลัก

1. วางข้อมูลต่อไปนี้ลงในเครื่องมือแก้ไขโค้ด

   primary คือคีย์เวิร์ดในการเข้าถึงปฏิทินหลักของผู้ใช้ที่ลงชื่อเข้าใช้ หากต้องการเรียกข้อมูลกิจกรรมในปฏิทินอื่น ให้ตั้งค่าพารามิเตอร์ calendarId เป็นอีเมล ซึ่งจะช่วยให้คุณอ่านกิจกรรมสถานะในปฏิทินของผู้ใช้รายอื่นที่คุณมีสิทธิ์เข้าถึงระดับว่าง/ไม่ว่างเป็นอย่างน้อยได้ ปฏิทินรองจะไม่มีกิจกรรมสถานะ

   /** Creates a focus time event. */
   function createFocusTime() {
     const event = {
       start: { dateTime: '2023-11-14T10:00:00+01:00' },
       end: { dateTime: '2023-11-14T12:00:00+01:00' },
       eventType: 'focusTime',
       focusTimeProperties: {
         chatStatus: 'doNotDisturb',
         autoDeclineMode: 'declineOnlyNewConflictingInvitations',
         declineMessage: 'Declined because I am in focus time.',
       }
     }
     createEvent(event);
   }
   
   /** Creates an out of office event. */
   function createOutOfOffice() {
     const event = {
       start: { dateTime: '2023-11-15T10:00:00+01:00' },
       end: { dateTime: '2023-11-15T18:00:00+01:00' },
       eventType: 'outOfOffice',
       outOfOfficeProperties: {
         autoDeclineMode: 'declineOnlyNewConflictingInvitations',
         declineMessage: 'Declined because I am on vacation.',
       }
     }
     createEvent(event);
   }
   
   /** Creates a working location event. */
   function createWorkingLocation() {
     const event = {
       start: { date: "2023-06-01" },
       end: { date: "2023-06-02" },
       eventType: "workingLocation",
       visibility: "public",
       transparency: "transparent",
       workingLocationProperties: {
         type: 'customLocation',
         customLocation: { label: "a custom location" },
       }
     }
     createEvent(event);
   }
   
   /**
     * Creates a Calendar event.
     * See https://developers.google.com/calendar/api/v3/reference/events/insert
     */
   function createEvent(event) {
     const calendarId = 'primary';
   
     try {
       var response = Calendar.Events.insert(event, calendarId);
       var event = (response.eventType === 'workingLocation') ? parseWorkingLocation(response) : response;
       console.log(event);
     } catch (exception) {
       console.log(exception.message);
     }
   }
   
   /**
     * Reads the event with the given eventId.
     * See https://developers.google.com/calendar/api/v3/reference/events/get
     */
   function readEvent() {
     const calendarId = 'primary';
   
     // Replace with a valid eventId.
     const eventId = "sample-event-id";
   
     try {
       var response = Calendar.Events.get(calendarId, eventId);
       var event = (response.eventType === 'workingLocation') ? parseWorkingLocation(response) : response;
       console.log(event);
     } catch (exception) {
       console.log(exception.message);
     }
   }
   
   /** Lists focus time events. */
   function listFocusTimes() {
     listEvents('focusTime');
   }
   
   /** Lists out of office events. */
   function listOutOfOffices() {
     listEvents('outOfOffice');
   }
   
   /** Lists working location events. */
   function listWorkingLocations() {
     listEvents('workingLocation');
   }
   
   /**
     * Lists events with the given event type.
     * See https://developers.google.com/calendar/api/v3/reference/events/list
     */
   function listEvents(eventType = 'default') {
     const calendarId = 'primary'
   
     // Query parameters for the list request.
     const optionalArgs = {
       eventTypes: [eventType],
       showDeleted: false,
       singleEvents: true,
       timeMax: '2023-04-01T00:00:00+01:00',
       timeMin: '2023-03-27T00:00:00+01:00',
     }
     try {
       var response = Calendar.Events.list(calendarId, optionalArgs);
       response.items.forEach(event =>
         console.log(eventType === 'workingLocation' ? parseWorkingLocation(event) : event));
     } catch (exception) {
       console.log(exception.message);
     }
   }
   
   /**
     * Parses working location properties of an event into a string.
     * See https://developers.google.com/calendar/api/v3/reference/events#resource
     */
   function parseWorkingLocation(event) {
     if (event.eventType != "workingLocation") {
       throw new Error("'" + event.summary + "' is not a working location event.");
     }
   
     var location = 'No Location';
     const workingLocation = event.workingLocationProperties;
     if (workingLocation) {
       if (workingLocation.type === 'homeOffice') {
         location = 'Home';
       }
       if (workingLocation.type === 'officeLocation') {
         location = workingLocation.officeLocation.label;
       }
       if (workingLocation.type === 'customLocation') {
         location = workingLocation.customLocation.label;
       }
     }
     return `${event.start.date}: ${location}`;
   }
   

เรียกใช้ตัวอย่างโค้ด

1. เหนือเครื่องมือแก้ไขโค้ด ให้เลือกฟังก์ชันที่จะเรียกใช้จากเมนูแบบเลื่อนลง แล้วคลิกเรียกใช้
2. ในการเรียกใช้ครั้งแรก ระบบจะแจ้งให้คุณให้สิทธิ์เข้าถึง ตรวจสอบและอนุญาตให้ Apps Script เข้าถึงปฏิทิน
3. คุณสามารถตรวจสอบผลลัพธ์ของการดำเนินการสคริปต์ได้ในบันทึกการดำเนินการที่ปรากฏที่ด้านล่างของหน้าต่าง