หน้านี้ได้รับการแปลโดย Cloud Translation API

Events: list

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

ส่งคำขอ

คำขอ HTTP

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

พารามิเตอร์

ชื่อพารามิเตอร์	ค่า	คำอธิบาย
พารามิเตอร์เส้นทาง
`calendarId`	`string`	ตัวระบุปฏิทิน หากต้องการเรียกรหัสปฏิทิน ให้เรียกเมธอด calendarList.list หากต้องการเข้าถึงปฏิทินหลักของผู้ใช้ที่เข้าสู่ระบบอยู่ ให้ใช้คีย์เวิร์ด "`primary`"
พารามิเตอร์การค้นหาที่ไม่บังคับ
`alwaysIncludeEmail`	`boolean`	เลิกใช้งานแล้วและไม่สนใจ ระบบจะแสดงผลข้อมูลในช่อง `email` สําหรับผู้จัด ผู้สร้าง และผู้เข้าร่วมเสมอ แม้ว่าจะไม่มีที่อยู่อีเมลจริงพร้อมใช้งานก็ตาม (เช่น ค่าที่ใช้ได้และไม่สามารถใช้งานได้)
`eventTypes`	`string`	ประเภทกิจกรรมที่จะส่งคืน ไม่บังคับ ค่าที่เป็นไปได้คือ: `"default"` `"focusTime"` `"outOfOffice"` `"workingLocation"` คุณใช้พารามิเตอร์นี้ซ้ําได้หลายครั้งเพื่อส่งคืนเหตุการณ์ประเภทต่างๆ ในปัจจุบัน ค่าเหล่านี้เป็นเพียงค่าที่อนุญาตสําหรับช่องนี้: `["default", "focusTime", "outOfOffice"]` `["default", "focusTime", "outOfOffice", "workingLocation"]` `["workingLocation"]` ค่าเริ่มต้นคือ `["default", "focusTime", "outOfOffice"]` ชุดค่าผสมเพิ่มเติมของเหตุการณ์ทั้ง 4 ประเภทจะพร้อมใช้งานในรุ่นถัดไป
`iCalUID`	`string`	ระบุรหัสกิจกรรมในรูปแบบ iCalendar ที่จะระบุไว้ในการตอบกลับ ไม่บังคับ ใช้สําหรับค้นหากิจกรรมโดยใช้รหัส iCalendar
`maxAttendees`	`integer`	จํานวนผู้เข้าร่วมสูงสุดในการตอบกลับ หากมีผู้เข้าร่วมมากกว่าจํานวนที่ระบุ ผู้เข้าร่วมจะถูกส่งคืน ไม่บังคับ
`maxResults`	`integer`	จํานวนเหตุการณ์สูงสุดที่แสดงผลในหน้าผลการค้นหา 1 หน้า จํานวนเหตุการณ์ในหน้าผลลัพธ์อาจน้อยกว่าค่านี้ หรือไม่มีเลยแม้ว่าจะมีเหตุการณ์ที่ตรงกับคําค้นหามากกว่าก็ตาม ระบบตรวจหาหน้าที่ไม่ครบถ้วนได้โดยมีช่อง `nextPageToken` ที่ไม่ว่างเปล่าในการตอบกลับ โดยค่าเริ่มต้น ค่านี้จะเป็น 250 เหตุการณ์ หน้าเว็บต้องมีขนาดไม่เกิน 2,500 เหตุการณ์ ไม่บังคับ
`orderBy`	`string`	ลําดับของเหตุการณ์ที่ส่งกลับในผลลัพธ์ ไม่บังคับ ค่าเริ่มต้นคือลําดับที่คงที่และไม่ระบุ ค่าที่ยอมรับได้ ได้แก่ "`startTime`": เรียงตามวันที่/เวลาเริ่มต้น (น้อยไปมาก) ใช้ได้เฉพาะเมื่อค้นหาเหตุการณ์เดี่ยว (เช่น พารามิเตอร์ `singleEvents` เป็น True) "`updated`": เรียงตามเวลาแก้ไขล่าสุด (น้อยไปมาก)
`pageToken`	`string`	โทเค็นที่ระบุหน้าผลการค้นหาที่จะส่งคืน ไม่บังคับ
`privateExtendedProperty`	`string`	ระบุข้อจํากัดพร็อพเพอร์ตี้แบบขยายเป็น propertyName=value จับคู่เฉพาะพร็อพเพอร์ตี้ส่วนตัว อาจมีการใช้พารามิเตอร์นี้ซ้ําหลายครั้งเพื่อแสดงเหตุการณ์ที่ตรงกับข้อจํากัดทั้งหมดที่ระบุ
`q`	`string`	ข้อความค้นหาฟรีเพื่อค้นหากิจกรรมที่ตรงกับคําเหล่านี้: `summary`, `description`, `location`, `displayName` ของผู้เข้าร่วม, `email` ของผู้เข้าร่วม ไม่บังคับ
`sharedExtendedProperty`	`string`	ระบุข้อจํากัดพร็อพเพอร์ตี้แบบขยายเป็น propertyName=value จับคู่เฉพาะพร็อพเพอร์ตี้ที่แชร์ อาจมีการใช้พารามิเตอร์นี้ซ้ําหลายครั้งเพื่อแสดงเหตุการณ์ที่ตรงกับข้อจํากัดทั้งหมดที่ระบุ
`showDeleted`	`boolean`	กําหนดว่าจะรวมเหตุการณ์ที่ถูกลบ (ที่มี `status` เท่ากับ "`cancelled`") ในผลลัพธ์หรือไม่ ระบบจะรวมอินสแตนซ์ของกิจกรรมที่เกิดซ้ําซึ่งยกเลิกไปแล้ว (แต่ไม่รวมกิจกรรมที่เกิดซ้ํา)) หาก `showDeleted` และ `singleEvents` เป็นเท็จ ถ้า `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 Explorer ด้านล่างเพื่อเรียกใช้วิธีการนี้กับข้อมูลสดและดูการตอบกลับ