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

ข้อความค้นหาเหล่านี้จะจับคู่คีย์เวิร์ดที่กําหนดไว้ล่วงหน้ากับคําแปลชื่อที่แสดงทั้งหมดของเหตุการณ์สถานที่ทํางาน ไม่อยู่ที่สำนักงาน และเวลาที่ต้องการสมาธิ เช่น การค้นหา "สำนักงาน" หรือ "สำนัก" จะแสดงเหตุการณ์สถานที่ทํางานที่ประเภท officeLocation ส่วนการค้นหา "ลางาน" หรือ "ไม่อยู่" จะแสดงเหตุการณ์ลางาน ไม่บังคับ
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 (ไม่มีแล้ว) และไคลเอ็นต์ควรล้างพื้นที่เก็บข้อมูลและทำการซิงค์อย่างเต็มรูปแบบโดยไม่มี 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" - ผู้ใช้มีสิทธิ์อ่านปฏิทิน กิจกรรมส่วนตัวจะปรากฏต่อผู้ใช้ที่มีสิทธิ์เข้าถึงระดับผู้อ่าน แต่ระบบจะซ่อนรายละเอียดกิจกรรม
  • "writer" - ผู้ใช้มีสิทธิ์อ่านและเขียนในปฏิทิน กิจกรรมส่วนตัวจะปรากฏต่อผู้ใช้ที่มีสิทธิ์เข้าถึงระดับผู้เขียน และผู้ใช้จะเห็นรายละเอียดกิจกรรม
  • "owner" - ผู้ใช้เป็นเจ้าของปฏิทิน บทบาทนี้มีสิทธิ์ทั้งหมดของบทบาทผู้เขียน พร้อมความสามารถในการดูและจัดการ ACL เพิ่มเติม
defaultReminders[] list การช่วยเตือนเริ่มต้นในปฏิทินสำหรับผู้ใช้ที่ตรวจสอบสิทธิ์แล้ว การช่วยเตือนเหล่านี้มีผลกับกิจกรรมทั้งหมดในปฏิทินนี้ที่ไม่ได้ลบล้างการช่วยเตือนดังกล่าวอย่างชัดเจน (กล่าวคือไม่ได้ตั้งค่า reminders.useDefault เป็น "จริง")
defaultReminders[].method string วิธีการที่ใช้โดยการช่วยเตือนนี้ ค่าที่เป็นไปได้มีดังนี้
  • "email" - ระบบจะส่งการช่วยเตือนทางอีเมล
  • "popup" - ระบบจะส่งการช่วยเตือนผ่านป๊อปอัป UI

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

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

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

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

ลองใช้งาน

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