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 שיסופק בתגובה. זה שינוי אופציונלי. משתמשים באפשרות הזו כדי לחפש אירוע לפי מזהה iCalendar שלו.
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 מונחי החיפוש האלה מתאימים גם למילות מפתח מוגדרות מראש לכל התרגומים של כותרות התצוגה של אירועים מסוג 'מיקום עבודה', 'לא בעבודה' ו'זמן לעצמי'. לדוגמה, חיפוש של 'Office' או 'Bureau' יחזיר אירועים של מיקום עבודה מסוג 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

מידע נוסף זמין בדף אימות והרשאה.

גוף הבקשה

אין לספק גוף בקשה בשיטה הזו.

תשובה

אם הפעולה בוצעה ללא שגיאות, ה-method מחזיר גוף תגובה עם המבנה הבא:

{
  "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 שבהמשך כדי להפעיל את השיטה הזו על נתונים פעילים ולראות את התגובה.