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

מונחי החיפוש האלה מתאימים גם למילות מפתח מוגדרות מראש לכל התרגומים של כותרות התצוגה של אירועים מסוג 'מיקום עבודה', 'לא בעבודה' ו'זמן לעצמי'. לדוגמה, חיפוש של 'משרד' או 'לשכה' מחזיר אירועים של מיקום עבודה מסוג 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
https://www.googleapis.com/auth/calendar.app.created
https://www.googleapis.com/auth/calendar.events.freebusy
https://www.googleapis.com/auth/calendar.events.owned
https://www.googleapis.com/auth/calendar.events.owned.readonly
https://www.googleapis.com/auth/calendar.events.public.readonly

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

גוף הבקשה

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

תשובה

אם הפעולה בוצעה ללא שגיאות, ה-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?

נסה בעצמך!

אפשר להשתמש ב-API Explorer שבהמשך כדי להפעיל את השיטה הזו על נתונים פעילים ולראות את התגובה.