หน้านี้ได้รับการแปลโดย Cloud Translation API

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

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

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

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

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

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

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

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

'focusTime'
'outOfOffice'
'workingLocation'

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

ติดตามการเปลี่ยนแปลงในเหตุการณ์สถานะ

คุณสามารถสมัครรับข้อมูลการเปลี่ยนแปลงเกี่ยวกับเหตุการณ์สถานะในทรัพยากร Events ของ Calendar 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 Calendar API ได้ที่เอกสารอ้างอิง

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

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

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

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

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

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

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

วางข้อความต่อไปนี้ลงในตัวแก้ไขโค้ด

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/workspace/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/workspace/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/workspace/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/workspace/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}`;
}

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

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