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 מציין מזהה אירוע בפורמט i Calendar שיש לספק בתגובה. זה שינוי אופציונלי. ניתן להשתמש באפשרות הזו אם רוצים לחפש אירוע לפי מזהה icalendar שלו.
maxAttendees integer המספר המקסימלי של משתתפים שיש לכלול בתשובה. אם יש יותר ממספר המשתתפים שצוין, רק המשתתף יוחזר. זה שינוי אופציונלי.
maxResults integer המספר המקסימלי של אירועים שהוחזרו בדף תוצאות אחד. מספר האירועים בדף שיתקבל עשוי להיות נמוך מהערך הזה, או לא להיות בכלל, גם אם יש יותר אירועים שתואמים לשאילתה. ניתן לזהות דפים לא מלאים באמצעות שדה nextPageToken שאינו ריק בתגובה. כברירת מחדל, הערך הוא 250 אירועים. גודל הדף לא יכול להיות גדול מ-2500 אירועים. זה שינוי אופציונלי.
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, ואילו חיפוש של "לא בעבודה" או "Abwesend" יחזיר אירועים מסוג 'לא בעבודה'. זה שינוי אופציונלי.
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 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. זה שינוי אופציונלי. ברירת המחדל היא לא לסנן לפי מועד השינוי האחרון.

אישור

הבקשה הזו מאפשרת הרשאה עם לפחות אחד מההיקפים הבאים:

היקף
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 לא מוגדרת כ-True).
defaultReminders[].method string השיטה שבה נעשה שימוש בתזכורת הזו. הערכים האפשריים הם:
  • 'email' - התזכורות נשלחות באימייל.
  • 'popup' – התזכורות נשלחות דרך חלון קופץ של ממשק המשתמש.

חובה כשמוסיפים תזכורת.

 ניתן לכתיבה
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?

רוצה לנסות?

צריך להשתמש ב-APIs Explorer שבהמשך כדי לקרוא לשיטה הזו בנתונים בזמן אמת ולראות את התגובה.