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"].
שילובים נוספים של ארבעת סוגי האירועים האלה יהיו זמינים בגרסאות מאוחרות יותר.
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 של המשתתף. אופציונלי.
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, והלקוח יצטרך לנקות את האחסון שלו ולבצע סנכרון מלא ללא 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" – המשתמש קרא את היומן וכתוב אותו ביומן Google. אירועים פרטיים יופיעו בפני משתמשים עם גישת כותב, ופרטי האירוע יוצגו.
  • '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 בהמשך כדי להפעיל את השיטה הזו על נתונים בזמן אמת ולראות את התשובה.