Freebusy: query

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

שליחת בקשה

בקשת HTTP

POST https://www.googleapis.com/calendar/v3/freeBusy

הרשאה

הבקשה הזו מאפשרת הרשאה עם היקף הרשאות אחד לפחות מתוך אלה:

היקף ההרשאות
https://www.googleapis.com/auth/calendar.readonly
https://www.googleapis.com/auth/calendar

למידע נוסף, עיינו בדף אימות והרשאה.

גוף הבקשה

בגוף הבקשה, צריך לספק את הנתונים במבנה הבא:

{
  "timeMin": datetime,
  "timeMax": datetime,
  "timeZone": string,
  "groupExpansionMax": integer,
  "calendarExpansionMax": integer,
  "items": [
    {
      "id": string
    }
  ]
}
שם הנכס ערך תיאור הערות
timeMin datetime תחילת המרווח עבור השאילתה בפורמט המתאים ל-RFC3339.
timeMax datetime סיום המרווח לשאילתה כפי שהוא בפורמט RFC3339.
timeZone string אזור הזמן של התגובה. אופציונלי. ברירת המחדל היא שעון UTC.
groupExpansionMax integer מספר מקסימלי של מזהי יומנים שיסופקו לקבוצה אחת. אופציונלי. מוחזרת שגיאה לקבוצה עם יותר חברים מהערך הזה. הערך המקסימלי הוא 100.
calendarExpansionMax integer המספר המקסימלי של יומנים שעבורם יש לספק מידע על FreeBusy. אופציונלי. הערך המקסימלי הוא 50.
items[] list רשימת היומנים ו/או הקבוצות שיש להריץ בהם שאילתות.
items[].id string המזהה של יומן או של קבוצה.

תשובה

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

{
  "kind": "calendar#freeBusy",
  "timeMin": datetime,
  "timeMax": datetime,
  "groups": {
    (key): {
      "errors": [
        {
          "domain": string,
          "reason": string
        }
      ],
      "calendars": [
        string
      ]
    }
  },
  "calendars": {
    (key): {
      "errors": [
        {
          "domain": string,
          "reason": string
        }
      ],
      "busy": [
        {
          "start": datetime,
          "end": datetime
        }
      ]
    }
  }
}
שם הנכס ערך תיאור הערות
kind string סוג המשאב ("calendar#freeBusy").
timeMin datetime תחילת המרווח.
timeMax datetime סוף המרווח.
groups object הרחבה של קבוצות.
groups.(key) nested object רשימת היומנים שחברים בקבוצה הזו.
groups.(key).errors[] list שגיאות אופציונליות (אם החישוב של הקבוצה נכשל).
groups.(key).errors[].domain string הדומיין, או הקטגוריה הרחבה של השגיאה.
groups.(key).errors[].reason string הסיבה הספציפית לשגיאה. דוגמאות לערכים האפשריים:
  • "groupTooBig" - קבוצת המשתמשים שביקשת גדולה מדי לשאילתה יחידה.
  • "tooManyCalendarsRequested" - מספר היומנים המבוקשים גדול מדי לשאילתה יחידה.
  • "notFound" – המשאב המבוקש לא נמצא.
  • "internalError" - שירות ה-API נתקל בשגיאה פנימית.
בעתיד ייתכן שנוסיף עוד סוגי שגיאות, ולכן הלקוחות צריכים לטפל בסטטוסים נוספים של שגיאות שאינם כלולים ברשימה.
groups.(key).calendars[] list רשימה של מזהי יומנים בתוך קבוצה.
calendars object רשימת מידע פנוי/עסוק של יומנים.
calendars.(key) nested object הרחבה פנויה/לא פנויה עבור יומן יחיד.
calendars.(key).errors[] list שגיאות אופציונליות (אם החישוב של היומן נכשל).
calendars.(key).errors[].domain string הדומיין, או הקטגוריה הרחבה של השגיאה.
calendars.(key).errors[].reason string הסיבה הספציפית לשגיאה. דוגמאות לערכים האפשריים:
  • "groupTooBig" - קבוצת המשתמשים שביקשת גדולה מדי לשאילתה יחידה.
  • "tooManyCalendarsRequested" - מספר היומנים המבוקשים גדול מדי לשאילתה יחידה.
  • "notFound" – המשאב המבוקש לא נמצא.
  • "internalError" - שירות ה-API נתקל בשגיאה פנימית.
בעתיד ייתכן שנוסיף עוד סוגי שגיאות, ולכן הלקוחות צריכים לטפל בסטטוסים נוספים של שגיאות שאינם כלולים ברשימה.
calendars.(key).busy[] list רשימת טווחי הזמן שבמהלכם היומן הזה צריך להיות עמוס.
calendars.(key).busy[].start datetime תאריך ההתחלה (הכולל) של תקופת הזמן.
calendars.(key).busy[].end datetime סיום (לא כולל) של תקופת הזמן.

רוצה לנסות?

כדי לקרוא לשיטה הזו על נתונים בזמן אמת ולראות את התגובה, צריך להשתמש ב-APIs Explorer בהמשך.