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

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

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

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

คำตอบ

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

{
  "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

ตัวอย่าง

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

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 ด้านล่างเพื่อเรียกใช้เมธอดนี้กับข้อมูลจริงและดูการตอบกลับ