Events: list

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

ส่งคำขอ

คำขอ HTTP

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

พารามิเตอร์

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

ค่าที่ยอมรับได้ มีดังนี้
  • "default": กิจกรรมปกติ
  • "focusTime": กิจกรรมที่ต้องการสมาธิ
  • "fromGmail": กิจกรรมจาก Gmail
  • "outOfOffice": กิจกรรมลางาน
  • "workingLocation": กิจกรรมเกี่ยวกับสถานที่ทำงาน
iCalUID string ระบุรหัสกิจกรรมในรูปแบบ iปฏิทิน เพื่อให้ระบุไว้ในการตอบกลับ ไม่บังคับ ใช้ตัวเลือกนี้ในกรณีที่ต้องการค้นหากิจกรรมตามรหัส i Calendar ของกิจกรรม
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

ข้อความค้นหาเหล่านี้ยังจับคู่คีย์เวิร์ดที่กําหนดไว้ล่วงหน้ากับการแปลชื่อที่แสดงทั้งหมดของสถานที่ทำงาน การลางาน และกิจกรรมเวลาที่ต้องการสมาธิด้วย เช่น การค้นหา "Office" หรือ "Bureau" จะแสดงกิจกรรมสถานที่ทำงานของประเภท 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
  ]
}
ชื่อพร็อพเพอร์ตี้ ค่า คำอธิบาย หมายเหตุ
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 ด้านล่างเพื่อเรียกใช้เมธอดนี้กับข้อมูลแบบสดและดูการตอบกลับ