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.

נסה בעצמך!

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