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

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

גוף הבקשה

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

תשובה

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

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

    .
defaultReminders[] list תזכורות ברירת המחדל ביומן למשתמש המאומת. התזכורות האלה חלות על כל האירועים ביומן שלא מוגדרים בהם ערכים שסותרים את התזכורות האלה (כלומר, לא מוגדר בהם reminders.useDefault הערך True).
defaultReminders[].method string השיטה שבה נעשה שימוש בתזכורת הזו. הערכים האפשריים הם:
  • ‫email – התזכורות נשלחות באימייל.
  • ‫popup – התזכורות נשלחות באמצעות חלון קופץ בממשק המשתמש.

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

 ניתן לכתיבה
defaultReminders[].minutes integer מספר הדקות לפני תחילת האירוע שבהן התזכורת צריכה לפעול. הערכים התקינים הם בין 0 ל-40320 (4 שבועות בדקות).

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

 ניתן לכתיבה
nextPageToken string אסימון שמשמש לגישה לדף הבא של התוצאה הזו. המאפיין מושמט אם אין תוצאות נוספות, ובמקרה כזה מופיע nextSyncToken.
items[] list רשימת האירועים ביומן.
nextSyncToken string אסימון שמשמש בשלב מאוחר יותר כדי לאחזר רק את הרשומות שהשתנו מאז שהתוצאה הזו הוחזרה. המאפיין הזה לא מופיע אם יש תוצאות נוספות. במקרה כזה, מופיע nextPageToken.

רוצה לנסות?

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