Events: list

แสดงกิจกรรมในปฏิทินที่ระบุ ลองใช้เลย

ส่งคำขอ

คำขอ HTTP

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events

พารามิเตอร์

ชื่อพารามิเตอร์ ค่า คำอธิบาย
พารามิเตอร์เส้นทาง
calendarId string ตัวระบุปฏิทิน หากต้องการดึงรหัสปฏิทิน ให้เรียกใช้เมธอด calendarList.list หากต้องการเข้าถึงปฏิทินหลักของผู้ใช้ที่เข้าสู่ระบบอยู่ในปัจจุบัน ให้ใช้คีย์เวิร์ด "primary"
พารามิเตอร์การค้นหาที่ไม่บังคับ
alwaysIncludeEmail boolean เลิกใช้งานแล้วและระบบจะไม่สนใจ
eventTypes string ประเภทเหตุการณ์ที่จะแสดง ไม่บังคับ พารามิเตอร์นี้สามารถทำซ้ำได้หลายครั้งเพื่อแสดงกิจกรรมประเภทต่างๆ หากไม่ได้ตั้งค่า ระบบจะแสดงเหตุการณ์ทุกประเภท

ค่าที่ยอมรับมีดังนี้
  • "birthday": กิจกรรมพิเศษตลอดทั้งวันที่มีการเกิดซ้ำทุกปี
  • "default": กิจกรรมปกติ
  • focusTime: เวลาที่ต้องการสมาธิ
  • "fromGmail": กิจกรรมจาก Gmail
  • "outOfOffice": กิจกรรมลางาน
  • "workingLocation": กิจกรรมสถานที่ทำงาน
iCalUID string ระบุรหัสกิจกรรมในรูปแบบ iCalendar ที่จะระบุในการตอบกลับ ไม่บังคับ ใช้ตัวเลือกนี้หากต้องการค้นหากิจกรรมตามรหัส iCalendar
maxAttendees integer จำนวนผู้เข้าร่วมสูงสุดที่จะรวมไว้ในการตอบกลับ หากมีผู้เข้าร่วมมากกว่าจำนวนที่ระบุ ระบบจะแสดงผลเฉพาะผู้เข้าร่วม ไม่บังคับ
maxResults integer จำนวนเหตุการณ์สูงสุดที่แสดงในหน้าผลลัพธ์เดียว จำนวนเหตุการณ์ในหน้าผลลัพธ์อาจน้อยกว่าค่านี้ หรือไม่มีเลย แม้ว่าจะมีเหตุการณ์ที่ตรงกับคำค้นหามากกว่าก็ตาม ระบบจะตรวจหาหน้าที่ไม่สมบูรณ์ได้โดยใช้ช่อง nextPageToken ที่ไม่ว่างในการตอบกลับ โดยค่าเริ่มต้น ค่านี้คือ 250 เหตุการณ์ ขนาดหน้าเว็บต้องไม่เกิน 2,500 เหตุการณ์ ไม่บังคับ
orderBy string ลำดับของเหตุการณ์ที่แสดงในผลลัพธ์ ไม่บังคับ ค่าเริ่มต้นคือลำดับที่เสถียรซึ่งไม่ได้ระบุ

ค่าที่ยอมรับมีดังนี้
  • "startTime": จัดเรียงตามวันที่/เวลาเริ่มต้น (จากน้อยไปมาก) ซึ่งจะใช้ได้เมื่อมีเหตุการณ์การถามคำถามเดียวเท่านั้น (กล่าวคือ พารามิเตอร์ singleEvents เป็น True)
  • "updated": จัดเรียงตามเวลาที่แก้ไขครั้งล่าสุด (จากน้อยไปมาก)
pageToken string โทเค็นที่ระบุหน้าผลการค้นหาที่จะแสดง ไม่บังคับ
privateExtendedProperty string ข้อจํากัดของพร็อพเพอร์ตี้เพิ่มเติมที่ระบุเป็น propertyName=value จับคู่เฉพาะพร็อพเพอร์ตี้ส่วนตัว พารามิเตอร์นี้อาจซ้ำกันหลายครั้งเพื่อแสดงเหตุการณ์ที่ตรงกับข้อจํากัดทั้งหมดที่ระบุ
q string ข้อความค้นหาแบบอิสระเพื่อค้นหาเหตุการณ์ที่ตรงกับข้อความเหล่านี้ในช่องต่อไปนี้
  • summary
  • description
  • location
  • displayName ของผู้เข้าร่วม
  • email ของผู้เข้าร่วม
  • displayName ของผู้จัด
  • email ของผู้จัด
  • workingLocationProperties.officeLocation.buildingId
  • workingLocationProperties.officeLocation.deskId
  • workingLocationProperties.officeLocation.label
  • workingLocationProperties.customLocation.label

นอกจากนี้ ข้อความค้นหาเหล่านี้ยังจับคู่คีย์เวิร์ดที่กำหนดไว้ล่วงหน้ากับคำแปลชื่อที่แสดงทั้งหมดของกิจกรรมสถานที่ทำงาน สถานะไม่อยู่ และเวลาโฟกัส เช่น การค้นหา "Office" หรือ "Bureau" จะแสดงกิจกรรมสถานที่ทำงานประเภท officeLocation ในขณะที่การค้นหา "ลางาน" หรือ "Abwesend" จะแสดงกิจกรรมลางาน ไม่บังคับ
sharedExtendedProperty string ข้อจํากัดของพร็อพเพอร์ตี้เพิ่มเติมที่ระบุเป็น propertyName=value จับคู่เฉพาะพร็อพเพอร์ตี้ที่แชร์ พารามิเตอร์นี้อาจซ้ำกันหลายครั้งเพื่อแสดงเหตุการณ์ที่ตรงกับข้อจํากัดทั้งหมดที่ระบุ
showDeleted boolean เลือกว่าจะรวมเหตุการณ์ที่ถูกลบ (โดยมี status เท่ากับ "cancelled") ไว้ในผลลัพธ์หรือไม่ ระบบจะยังคงรวมอินสแตนซ์ที่ยกเลิกของกิจกรรมที่เกิดซ้ำ (แต่ไม่ใช่กิจกรรมที่เกิดซ้ำพื้นฐาน) หากทั้ง showDeleted และ singleEvents เป็น False หากทั้ง showDeleted และ singleEvents เป็น True ระบบจะแสดงเฉพาะอินสแตนซ์เดียวของกิจกรรมที่ลบ (แต่จะไม่แสดงกิจกรรมที่เกิดซ้ำที่เกี่ยวข้อง) ไม่บังคับ ค่าเริ่มต้นคือ False
showHiddenInvitations boolean เลือกว่าจะรวมคำเชิญที่ซ่อนไว้ในผลลัพธ์หรือไม่ ไม่บังคับ ค่าเริ่มต้นคือ False
singleEvents boolean ว่าจะขยายกิจกรรมที่เกิดซ้ำเป็นอินสแตนซ์และแสดงเฉพาะกิจกรรมแบบครั้งเดียวและอินสแตนซ์ของกิจกรรมที่เกิดซ้ำ แต่ไม่แสดงกิจกรรมที่เกิดซ้ำพื้นฐาน ไม่บังคับ ค่าเริ่มต้นคือ False
syncToken string โทเค็นที่ได้จากฟิลด์ nextSyncToken ซึ่งแสดงในหน้าผลลัพธ์สุดท้ายจากคำขอรายการก่อนหน้า ซึ่งจะทำให้ผลลัพธ์ของคำขอรายการนี้มีเฉพาะรายการที่มีการเปลี่ยนแปลงนับตั้งแต่นั้นเป็นต้นมา กิจกรรมทั้งหมดที่ลบไปตั้งแต่คำขอรายการก่อนหน้าจะอยู่ในชุดผลลัพธ์เสมอ และไม่อนุญาตให้ตั้งค่า showDeleted เป็น False
มีพารามิเตอร์การค้นหาหลายรายการที่ระบุร่วมกับ nextSyncToken ไม่ได้เพื่อให้มั่นใจถึงความสอดคล้องของสถานะไคลเอ็นต์

ได้แก่
  • iCalUID
  • orderBy
  • privateExtendedProperty
  • q
  • sharedExtendedProperty
  • timeMin
  • timeMax
  • updatedMin
พารามิเตอร์การค้นหาอื่นๆ ทั้งหมดควรเหมือนกับการซิงค์ครั้งแรกเพื่อหลีกเลี่ยงลักษณะการทำงานที่ไม่ได้กำหนดไว้ หาก syncToken หมดอายุ เซิร์ฟเวอร์จะตอบกลับด้วยโค้ดตอบกลับ 410 GONE และไคลเอ็นต์ควรล้างพื้นที่เก็บข้อมูลและทำการซิงค์แบบเต็มโดยไม่มี syncToken
ดูข้อมูลเพิ่มเติมเกี่ยวกับการซิงโครไนซ์แบบเพิ่ม
ไม่บังคับ ค่าเริ่มต้นคือแสดงรายการทั้งหมด
timeMax datetime ขอบเขตบน (ไม่รวม) สำหรับเวลาเริ่มต้นของเหตุการณ์ที่จะกรอง ไม่บังคับ ค่าเริ่มต้นคือไม่กรองตามเวลาเริ่มต้น ต้องเป็นการประทับเวลา RFC3339 ที่มีค่าชดเชยเขตเวลาที่จำเป็น เช่น 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z คุณระบุหน่วยเป็นมิลลิวินาทีได้ แต่ระบบจะไม่นำมาพิจารณา หากตั้งค่า timeMin ไว้ timeMax ต้องมากกว่า timeMin
timeMin datetime ขอบเขตล่าง (ไม่รวม) สำหรับเวลาสิ้นสุดของเหตุการณ์ที่จะกรอง ไม่บังคับ ค่าเริ่มต้นคือไม่กรองตามเวลาสิ้นสุด ต้องเป็นการประทับเวลา RFC3339 ที่มีค่าชดเชยเขตเวลาที่จำเป็น เช่น 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z คุณระบุหน่วยเป็นมิลลิวินาทีได้ แต่ระบบจะไม่นำมาพิจารณา หากตั้งค่า timeMax ไว้ timeMin ต้องน้อยกว่า timeMax
timeZone string เขตเวลาที่ใช้ในคำตอบ ไม่บังคับ ค่าเริ่มต้นคือเขตเวลาของปฏิทิน
updatedMin datetime ขอบเขตล่างของเวลาที่แก้ไขล่าสุดของเหตุการณ์ (เป็นการประทับเวลา RFC3339) เพื่อใช้กรอง เมื่อระบุแล้ว ระบบจะรวมรายการที่ลบตั้งแต่เวลานี้เสมอโดยไม่คำนึงถึง showDeleted ไม่บังคับ ค่าเริ่มต้นคือไม่กรองตามเวลาที่แก้ไขล่าสุด

การให้สิทธิ์

คำขอนี้อนุญาตให้สิทธิ์ที่มีขอบเขตต่อไปนี้อย่างน้อย 1 รายการ

ขอบเขต
https://www.googleapis.com/auth/calendar.readonly
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.events.readonly
https://www.googleapis.com/auth/calendar.events
https://www.googleapis.com/auth/calendar.app.created
https://www.googleapis.com/auth/calendar.events.freebusy
https://www.googleapis.com/auth/calendar.events.owned
https://www.googleapis.com/auth/calendar.events.owned.readonly
https://www.googleapis.com/auth/calendar.events.public.readonly

ดูข้อมูลเพิ่มเติมได้ที่หน้าการตรวจสอบสิทธิ์และการให้สิทธิ์

เนื้อความของคำขอ

อย่าระบุเนื้อหาคำขอด้วยเมธอดนี้

การตอบกลับ

หากทำสำเร็จ เมธอดนี้จะแสดงเนื้อหาการตอบกลับที่มีโครงสร้างดังต่อไปนี้

{
  "kind": "calendar#events",
  "etag": etag,
  "summary": string,
  "description": string,
  "updated": datetime,
  "timeZone": string,
  "accessRole": string,
  "defaultReminders": [
    {
      "method": string,
      "minutes": integer
    }
  ],
  "nextPageToken": string,
  "nextSyncToken": string,
  "items": [
    events Resource
  ]
}
ชื่อพร็อพเพอร์ตี้ ค่า คำอธิบาย หมายเหตุ
kind string ประเภทของคอลเล็กชัน ("calendar#events")
etag etag ETag ของคอลเล็กชัน
summary string ชื่อปฏิทิน อ่านอย่างเดียว
description string คำอธิบายของปฏิทิน อ่านอย่างเดียว
updated datetime เวลาที่แก้ไขปฏิทินครั้งล่าสุด (เป็นการประทับเวลา RFC3339) อ่านอย่างเดียว
timeZone string เขตเวลาของปฏิทิน อ่านอย่างเดียว
accessRole string บทบาทการเข้าถึงของผู้ใช้สำหรับปฏิทินนี้ อ่านอย่างเดียว ค่าที่เป็นไปได้มีดังนี้
  • "none" - ผู้ใช้ไม่มีสิทธิ์เข้าถึง
  • "freeBusyReader" - ผู้ใช้มีสิทธิ์อ่านข้อมูลว่าง/ไม่ว่าง
  • "reader" - ผู้ใช้มีสิทธิ์อ่านปฏิทิน กิจกรรมส่วนตัวจะปรากฏต่อผู้ใช้ที่มีสิทธิ์เข้าถึงระดับผู้อ่าน แต่ระบบจะซ่อนรายละเอียดกิจกรรม
  • "writerWithoutPrivateAccess" - ผู้ใช้มีสิทธิ์อ่านและเขียนในปฏิทิน กิจกรรมส่วนตัวจะปรากฏต่อผู้ใช้ที่มีสิทธิ์เข้าถึง writerWithoutPrivateAccess แต่ระบบจะซ่อนรายละเอียดกิจกรรม
  • "writer" - ผู้ใช้มีสิทธิ์อ่านและเขียนในปฏิทิน กิจกรรมส่วนตัวจะปรากฏต่อผู้ใช้ที่มีสิทธิ์เข้าถึงระดับผู้เขียน และรายละเอียดกิจกรรมจะปรากฏให้เห็น
  • "owner" - ผู้ใช้มีสิทธิ์เข้าถึงระดับผู้จัดการในปฏิทิน บทบาทนี้มีสิทธิ์ทั้งหมดของบทบาทผู้เขียน รวมถึงความสามารถเพิ่มเติมในการดูและแก้ไขระดับการเข้าถึงของผู้ใช้รายอื่น

    ได้หลายคน
defaultReminders[] list การช่วยเตือนเริ่มต้นในปฏิทินสำหรับผู้ใช้ที่ได้รับการตรวจสอบสิทธิ์ การช่วยเตือนเหล่านี้จะมีผลกับกิจกรรมทั้งหมดในปฏิทินนี้ที่ไม่ได้ลบล้างการช่วยเตือนอย่างชัดเจน (เช่น ไม่ได้ตั้งค่า reminders.useDefault เป็น True)
defaultReminders[].method string วิธีการที่ใช้โดยการช่วยเตือนนี้ ค่าที่เป็นไปได้มีดังนี้
  • email - ระบบจะส่งการแจ้งเตือนทางอีเมล
  • popup - ระบบจะส่งการแจ้งเตือนผ่านป๊อปอัป UI

ต้องระบุเมื่อเพิ่มการช่วยเตือน

 เขียนได้
defaultReminders[].minutes integer จำนวนนาทีก่อนเริ่มกิจกรรมที่ควรทริกเกอร์การช่วยเตือน ค่าที่ใช้ได้คือตั้งแต่ 0 ถึง 40320 (4 สัปดาห์ในหน่วยนาที)

ต้องระบุเมื่อเพิ่มการช่วยเตือน

 เขียนได้
nextPageToken string โทเค็นที่ใช้เพื่อเข้าถึงหน้าถัดไปของผลลัพธ์นี้ ข้ามหากไม่มีผลลัพธ์เพิ่มเติม ในกรณีนี้จะระบุ nextSyncToken
items[] list รายการกิจกรรมในปฏิทิน
nextSyncToken string โทเค็นที่ใช้ในภายหลังเพื่อดึงเฉพาะรายการที่มีการเปลี่ยนแปลงนับตั้งแต่ระบบแสดงผลลัพธ์นี้ ละเว้นหากมีผลลัพธ์เพิ่มเติม ในกรณีนี้จะมีการระบุ nextPageToken

ลองใช้งาน

ใช้โปรแกรมสำรวจ API ด้านล่างเพื่อเรียกเมธอดนี้ในข้อมูลสดและดูการตอบกลับ