דף זה תורגם על ידי Cloud Translation API.

Events: list

הפונקציה מחזירה אירועים ביומן שצוין. אפשר לנסות עכשיו או לראות דוגמה.

בקשה

בקשת HTTP

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

פרמטרים

שם הפרמטר	ערך	תיאור
פרמטרים של נתיב
`calendarId`	`string`	מזהה היומן. כדי לאחזר מזהי יומנים, צריך להפעיל את השיטה calendarList.list. כדי להיכנס ליומן הראשי של המשתמש שמחובר כרגע, אפשר להשתמש באפשרות '`primary`' במילת מפתח.
פרמטרים אופציונליים של שאילתה
`alwaysIncludeEmail`	`boolean`	הוצא משימוש והמערכת התעלמה ממנו.
`eventTypes`	`string`	סוגי אירועים שיוחזרו. זה שינוי אופציונלי. אפשר לחזור על הפרמטר הזה כמה פעמים כדי להחזיר אירועים מסוגים שונים. אם המדיניות לא מוגדרת, כל סוגי האירועים יוחזרו. הערכים הקבילים הם: "`default`": אירועים רגילים. '`focusTime`': אירועי 'זמן לעצמי'. "`fromGmail`": אירועים מ-Gmail. "`outOfOffice`": אירועים לא בעבודה. "`workingLocation`": אירועים של מיקום עבודה.
`iCalUID`	`string`	מציינת מזהה אירוע בפורמט icalendar שיסופק בתשובה. זה שינוי אופציונלי. אפשר להשתמש באפשרות הזו אם רוצים לחפש אירוע לפי מזהה ה-iיומן שלו.
`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`

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

גוף הבקשה

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

תשובה

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

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