ประเภทกิจกรรม

หน้านี้อธิบายพร็อพเพอร์ตี้ eventType และข้อกำหนดของประเภทเหตุการณ์ที่พร้อมใช้งานใน Google ปฏิทิน API

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

คุณสามารถค้นหาประเภทเหตุการณ์ได้ในตำแหน่งต่อไปนี้ใน API

  • เหตุการณ์ทั้งหมดจะแสดงผล eventType
  • ตั้งค่า eventType เมื่อสร้างหรืออัปเดตทรัพยากรเหตุการณ์ หากไม่ได้ตั้งค่า API จะใช้ 'default'
  • ระบุ eventTypes ในการเรียก events.list เพื่อแสดงรายการเหตุการณ์บางประเภท หากไม่ได้ระบุประเภท API จะแสดงผลเหตุการณ์ทุกประเภท
  • ระบุ eventTypes ในการเรียก events.watch เพื่อสมัครรับข้อมูลอัปเดตเกี่ยวกับเหตุการณ์บางประเภท หากไม่ได้ระบุประเภท คำขอจะสมัครรับข้อมูลเหตุการณ์ทุกประเภท

เหตุการณ์เริ่มต้น

ระบบจะสร้างและใช้เหตุการณ์ที่มีประเภทเหตุการณ์ default เป็นหนึ่งในทรัพยากรหลักของ Calendar API โดยรองรับ พร็อพเพอร์ตี้ ที่หลากหลายเพื่อปรับแต่งเหตุการณ์เพิ่มเติม

ดูหัวข้อ สร้างเหตุการณ์เพื่อเริ่มต้นใช้งาน เหตุการณ์ในปฏิทิน

วันเกิด

วันเกิดเป็นเหตุการณ์พิเศษที่จัดขึ้นทั้งวันและเกิดซ้ำทุกปี

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

Calendar API รองรับเมธอด events.get, events.instances และ events.list สำหรับการอ่านเหตุการณ์วันเกิด คุณสามารถตั้งค่า eventTypes เป็น 'birthday' เพื่อแสดงรายการเฉพาะเหตุการณ์วันเกิด หากไม่ได้ระบุประเภท การตอบกลับจะแสดงรายการวันเกิดพร้อมกับเหตุการณ์ประเภทอื่นๆ ทั้งหมด

ในออบเจ็กต์ Event ที่แสดงผล ให้ตรวจสอบช่อง birthdayProperties เพื่อดูรายละเอียดเพิ่มเติมเกี่ยวกับเหตุการณ์พิเศษนี้ birthdayProperties มีช่องต่อไปนี้

  • type: ประเภทของเหตุการณ์พิเศษนี้ ไม่ว่าจะเป็นวันเกิด วันครบรอบ หรือวันสำคัญอื่นๆ
  • customTypeName: ป้ายกำกับที่ผู้ใช้ระบุสำหรับเหตุการณ์พิเศษนี้ ระบบจะป้อนข้อมูลในช่องนี้หากtypeตั้งค่า เป็น 'custom'
  • contact: ชื่อทรัพยากรของรายชื่อติดต่อที่ลิงก์กับเหตุการณ์พิเศษนี้ (หากมี) โดยจะมีรูปแบบเป็น 'people/c12345' และใช้เพื่อดึงรายละเอียดรายชื่อติดต่อ จาก People API ได้

API ช่วยให้คุณสร้างเหตุการณ์วันเกิดได้โดยใช้ events.insert เมธอด ตามข้อกำหนดต่อไปนี้

  • eventType ตั้งค่า เป็น 'birthday'.
  • start และ end ช่องต้องกำหนด เหตุการณ์ที่จัดขึ้นทั้งวันซึ่งกินเวลา 1 วันพอดี
  • visibility ค่าของช่อง ต้องเป็น 'private'
  • transparency ค่าของช่องต้องเป็น 'transparent'
  • ต้องมีการเกิดซ้ำทุกปี ซึ่งหมายความว่าช่อง recurrence ต้องเป็น 'RRULE:FREQ=YEARLY' เหตุการณ์วันเกิดที่ตรงกับวันที่ 29 กุมภาพันธ์ ต้องมีกฎการเกิดซ้ำต่อไปนี้: 'RRULE:FREQ=YEARLY;BYMONTH=2;BYMONTHDAY=-1'
  • สามารถมี colorId, summary และ reminders ได้
  • สามารถมี birthdayProperties ได้ หากระบุ type ต้องเป็น 'birthday' และทั้ง customTypeName และ contact ต้องว่างเปล่า
  • ต้องไม่มีพร็อพเพอร์ตี้เหตุการณ์อื่นๆ

API ช่วยให้คุณอัปเดต colorId, summary และ reminders ของเหตุการณ์วันเกิด ได้โดยใช้เมธอด events.update และ events.patch นอกจากนี้ คุณยังอัปเดตช่อง start และ end เพื่อเปลี่ยนวันที่ของเหตุการณ์ได้ด้วย ในกรณีนี้ ค่าใหม่ต้องกำหนดเหตุการณ์ที่จัดขึ้นทั้งวันซึ่งกินเวลา 1 วันพอดี คุณจะอัปเดตรายละเอียดเวลาของเหตุการณ์วันเกิดไม่ได้หากเหตุการณ์นั้นลิงก์กับ contact หรือ type เป็น 'self'

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

คำขอที่พยายามสร้างหรืออัปเดตวันเกิดในวิธีที่ไม่รองรับจะล้มเหลว ในกรณีนี้ ให้ตรวจสอบข้อความแสดงข้อผิดพลาดเพื่อระบุปัญหา

API รองรับการดำเนินการ events.import สำหรับเหตุการณ์วันเกิด แต่ระบบจะนำเข้าเหตุการณ์เป็นเหตุการณ์เริ่มต้น กล่าวคือ eventType จะเป็น 'default'

API รองรับเมธอด events.watch เพื่อสมัครรับข้อมูลการเปลี่ยนแปลงเกี่ยวกับเหตุการณ์วันเกิดในปฏิทิน คุณสามารถตั้งค่า eventTypes เป็น 'birthday' เพื่อสมัครรับข้อมูลอัปเดตเกี่ยวกับเหตุการณ์วันเกิด หากไม่ได้ระบุประเภท คำขอจะสมัครรับข้อมูลเหตุการณ์ทุกประเภท รวมถึงวันเกิด

คุณสามารถลบเหตุการณ์วันเกิดได้โดยใช้เมธอด events.deleteของ Calendar API การลบเหตุการณ์วันเกิดออกจากปฏิทินจะไม่ส่งผลต่อข้อมูลใน Google Contacts หรือ โปรไฟล์บัญชี Google

ระบบไม่รองรับการเปลี่ยนผู้จัดเหตุการณ์วันเกิดโดยใช้เมธอด events.move หรือ events.update

กิจกรรมจาก Gmail

เหตุการณ์ที่สร้างจาก Gmail โดยอัตโนมัติ จะมีประเภทเหตุการณ์ 'fromGmail'

Calendar API ไม่อนุญาตให้สร้างเหตุการณ์ประเภทนี้โดยใช้ events.insert เมธอด

API ช่วยให้คุณอัปเดตพร็อพเพอร์ตี้เพิ่มเติม colorId, reminders, visibility, transparency, status, attendees, private, และ shared ได้โดยใช้เมธอด events.update และ events.patch

API รองรับเมธอด events.get และ events.list สำหรับการอ่านกิจกรรมจาก Gmail คุณสามารถตั้งค่า eventTypes เป็น 'fromGmail' เพื่อแสดงรายการเฉพาะเหตุการณ์ที่สร้างจาก Gmail หากไม่ได้ระบุประเภท ระบบจะแสดงรายการกิจกรรมจาก Gmail พร้อมกับเหตุการณ์ประเภทอื่นๆ ทั้งหมด

API รองรับเมธอด events.watch เพื่อสมัครรับข้อมูลการเปลี่ยนแปลงเกี่ยวกับกิจกรรมจาก Gmail ในปฏิทิน หากไม่ได้ระบุประเภท คำขอจะสมัครรับข้อมูลเหตุการณ์ทุกประเภท รวมถึง 'fromGmail'

คุณสามารถลบกิจกรรมจาก Gmail ได้โดยใช้เมธอด events.delete ของ Calendar API

ระบบไม่รองรับการเปลี่ยนผู้จัดเหตุการณ์จาก Gmail โดยใช้ events.move หรือ events.update เมธอด

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

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

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

สำรวจประเภทเหตุการณ์ใน Apps Script

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

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

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

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

(ไม่บังคับ) อัปเดตโปรเจ็กต์ที่อยู่ในระบบคลาวด์

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

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

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

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

    const CALENDAR_ID = 'CALENDAR_ID' || 'primary';

/** Lists default events. */
function listDefaultEvents() {
  listEvents('default');
}

/** Lists birthday events. */
function listBirthdays() {
  listEvents('birthday');
}

/** Lists events from Gmail. */
function listEventsFromGmail() {
  listEvents('fromGmail');
}

/**
  * Lists events with the given event type. If no type is specified, lists all events.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/list
  */
function listEvents(eventType = undefined) {
  // Query parameters for the list request.
  const optionalArgs = {
    eventTypes: eventType ? [eventType] : undefined,
    singleEvents: true,
    timeMax: '2024-07-30T00:00:00+01:00',
    timeMin: '2024-07-29T00:00:00+01:00',
  }
  try {
    var response = Calendar.Events.list(CALENDAR_ID, optionalArgs);
    response.items.forEach(event => 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() {
  try {
    var response = Calendar.Events.get(CALENDAR_ID, 'EVENT_ID');
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

/** Creates a default event. */
function createDefaultEvent() {
  const event = {
    start: { dateTime: '2024-07-30T10:30:00+01:00'},
    end: { dateTime: '2024-07-30T12:30:00+01:00'},
    description: 'Created from Apps Script.',
    eventType: 'default',
    summary: 'Sample event',
  }
  createEvent(event);
}

/** Creates a birthday event. */
function createBirthday() {
  const event = {
    start: { date: '2024-01-29' },
    end: { date: '2024-01-30' },
    eventType: 'birthday',
    recurrence: ["RRULE:FREQ=YEARLY"],
    summary: "My friend's birthday",
    transparency: "transparent",
    visibility: "private",
  }
  createEvent(event);
}

/**
  * Creates a Calendar event.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/insert
  */
function createEvent(event) {

  try {
    var response = Calendar.Events.insert(event, CALENDAR_ID);
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

    แทนที่ค่าต่อไปนี้

    • CALENDAR_ID: อีเมลของปฏิทินที่จะดึงและสร้างเหตุการณ์ ค่าคงที่นี้จะตั้งค่าเริ่มต้นเป็น 'primary' ซึ่งเป็นคีย์เวิร์ดสำหรับเข้าถึงปฏิทินหลักของผู้ใช้ที่ ลงชื่อเข้าใช้ การเปลี่ยนค่านี้จะช่วยให้คุณอ่านเหตุการณ์ในปฏิทินของผู้ใช้รายอื่นที่คุณมีสิทธิ์เข้าถึงได้
    • EVENT_ID: รหัสของเหตุการณ์ คุณสามารถเรียก events.list เพื่อ ดึงรหัสเหตุการณ์ได้

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

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