Events: list

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

ส่งคำขอ

คำขอ HTTP

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

พารามิเตอร์

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

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

ค่าที่ยอมรับมีดังนี้
  • "startTime": เรียงลำดับตามวันที่/เวลาเริ่มต้น (จากน้อยไปมาก) ซึ่งจะใช้ได้เมื่อค้นหาเหตุการณ์เดียว (เช่น พารามิเตอร์ singleEvents เป็น "จริง")
  • "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 ขณะที่การค้นหา "ลางาน" หรือ "Abwesend" จะแสดงผลกิจกรรมลางาน ไม่บังคับ
sharedExtendedProperty string ข้อจำกัดพร็อพเพอร์ตี้ที่ขยายระบุเป็น propertyName=value จับคู่เฉพาะพร็อพเพอร์ตี้ที่แชร์ พารามิเตอร์นี้อาจถูกทำซ้ำหลายครั้งเพื่อแสดงเหตุการณ์ที่ตรงกับข้อจำกัดที่ระบุทั้งหมด
showDeleted boolean จะรวมเหตุการณ์ที่ถูกลบ (ที่มี status เท่ากับ "cancelled") ในผลลัพธ์หรือไม่ อินสแตนซ์ของกิจกรรมที่เกิดซ้ำที่ยกเลิก (แต่ไม่ใช่กิจกรรมที่เกิดซ้ำที่เกี่ยวข้อง) จะยังคงรวมอยู่ด้วย หาก showDeleted และ singleEvents เป็นเท็จทั้งคู่ หาก showDeleted และ singleEvents เป็น "จริง" ทั้งคู่ ระบบจะแสดงผลกิจกรรมที่ลบไปแล้วเพียงครั้งเดียว (แต่ไม่แสดงผลกิจกรรมที่เกิดซ้ำ) ไม่บังคับ ทั้งนี้ ระบบตั้งค่าเริ่มต้นไว้เป็น "เท็จ"
showHiddenInvitations boolean จะรวมคำเชิญที่ซ่อนไว้ในผลลัพธ์ไหม ไม่บังคับ ทั้งนี้ ระบบตั้งค่าเริ่มต้นไว้เป็น "เท็จ"
singleEvents boolean เลือกว่าจะขยายกิจกรรมที่เกิดซ้ำเป็นหลายเหตุการณ์ และแสดงผลเฉพาะกิจกรรมแบบครั้งเดียวและกิจกรรมที่เกิดซ้ำ แต่ไม่รวมกิจกรรมที่เกิดซ้ำที่เกี่ยวข้อง ไม่บังคับ ทั้งนี้ ระบบตั้งค่าเริ่มต้นไว้เป็น "เท็จ"
syncToken string โทเค็นที่ได้รับจากช่อง nextSyncToken จะแสดงในหน้าสุดท้ายของผลลัพธ์จากคำขอรายการก่อนหน้า ทำให้ผลลัพธ์ของคำขอรายการนี้มีเฉพาะรายการที่เปลี่ยนแปลงนับจากวันนั้น เหตุการณ์ทั้งหมดที่ถูกลบเนื่องจากคำขอรายการก่อนหน้าจะอยู่ในชุดผลลัพธ์เสมอ และไม่ได้รับอนุญาตให้ตั้งค่า showDeleted เป็น "เท็จ"
มีพารามิเตอร์การค้นหาหลายรายการที่ระบุร่วมกับ 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

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

เนื้อหาของคำขอ

อย่าแสดงเนื้อหาของคำขอด้วยวิธีนี้

คำตอบ

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

{
  "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
  ]
}
ชื่อพร็อพเพอร์ตี้ ค่า คำอธิบาย Notes
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

ตัวอย่าง

หมายเหตุ: ตัวอย่างโค้ดที่มีสำหรับวิธีการนี้ไม่ได้แสดงถึงภาษาโปรแกรมที่รองรับทั้งหมด (ดูรายการภาษาที่รองรับได้ในหน้าไลบรารีของไคลเอ็นต์)

Java

ใช้ไลบรารีของไคลเอ็นต์ Java

import com.google.api.services.calendar.Calendar;
import com.google.api.services.calendar.model.Event;
import com.google.api.services.calendar.model.Events;

// ...

// Initialize Calendar service with valid OAuth credentials
Calendar service = new Calendar.Builder(httpTransport, jsonFactory, credentials)
    .setApplicationName("applicationName").build();

// Iterate over the events in the specified calendar
String pageToken = null;
do {
  Events events = service.events().list('primary').setPageToken(pageToken).execute();
  List<Event> items = events.getItems();
  for (Event event : items) {
    System.out.println(event.getSummary());
  }
  pageToken = events.getNextPageToken();
} while (pageToken != null);

Python

ใช้ไลบรารีของไคลเอ็นต์ Python

page_token = None
while True:
  events = service.events().list(calendarId='primary', pageToken=page_token).execute()
  for event in events['items']:
    print event['summary']
  page_token = events.get('nextPageToken')
  if not page_token:
    break

PHP

ใช้ไลบรารีของไคลเอ็นต์ PHP

$events = $service->events->listEvents('primary');

while(true) {
  foreach ($events->getItems() as $event) {
    echo $event->getSummary();
  }
  $pageToken = $events->getNextPageToken();
  if ($pageToken) {
    $optParams = array('pageToken' => $pageToken);
    $events = $service->events->listEvents('primary', $optParams);
  } else {
    break;
  }
}

Ruby

ใช้ไลบรารีของไคลเอ็นต์ Ruby

page_token = nil
begin
  result = client.list_events('primary', page_token: page_token)
  result.items.each do |e|
    print e.summary + "\n"
  end
  if result.next_page_token != page_token
    page_token = result.next_page_token
  else
    page_token = nil
  end
end while !page_token.nil?

ลองใช้เลย

ใช้ API Explorer ด้านล่างเพื่อเรียกใช้เมธอดนี้ในข้อมูลสดและดูการตอบสนอง