‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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` – למשתמש יש גישת קריאה ליומן. אירועים פרטיים יופיעו למשתמשים עם גישת קריאה, אבל פרטי האירועים יוסתרו. ‫`writerWithoutPrivateAccess` – למשתמש יש גישת קריאה וכתיבה ליומן. אירועים פרטיים יופיעו למשתמשים עם גישת writerWithoutPrivateAccess, אבל פרטי האירועים יוסתרו. ‫`writer` – למשתמש יש גישת קריאה וכתיבה ליומן. אירועים פרטיים יופיעו למשתמשים עם הרשאת כתיבה, ופרטי האירוע יהיו גלויים. ‫`owner` – למשתמש יש גישת ניהול ליומן. לתפקיד הזה יש את כל ההרשאות של תפקיד הכותב, עם היכולת הנוספת לראות ולשנות את רמות הגישה של משתמשים אחרים. חשוב: התפקיד `owner` שונה מבעלי הנתונים ביומן. ליומן יש בעלים אחד של הנתונים, אבל יכולים להיות לו כמה משתמשים עם `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 שבהמשך כדי להפעיל את השיטה הזו על נתונים פעילים ולראות את התגובה.