ניהול אירועים מסוג 'זמן לעצמי', 'לא בעבודה' ו'מיקום עבודה'

בדף הזה מוסבר איך להשתמש ב-Google Calendar API כדי ליצור אירועים שבהם מוצג הסטטוס של משתמשי Google Calendar. אירועי סטטוס מתארים איפה המשתמשים נמצאים או מה הם עושים, כולל אם הם בזמן לעצמם, לא בעבודה או עובדים ממיקום מסוים.

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

לפרטים נוספים, אפשר לעבור אל שימוש בפיצ'ר 'זמן לעצמי' ביומן Google והפעלה או השבתה של מיקום העבודה למשתמשים.

קריאה של אירועים ביומן ורישום שלהם

אפשר לקרוא ולרשום אירועים של סטטוס ביומן במשאב Events של Calendar API.

כדי לקרוא אירוע סטטוס, משתמשים בשיטה events.get ומציינים את eventId של האירוע.

כדי להציג רשימה של אירועי סטטוס, משתמשים בשיטה events.list ומציינים ערך אחד או יותר מהערכים הבאים בשדה eventTypes:

• 'focusTime'
• 'outOfOffice'
• 'workingLocation'

לאחר מכן, באובייקטים Event שמוחזרים, בודקים שהשדה eventType מכיל את הערך המבוקש, ומתייחסים לשדה המתאים כדי לקבל פרטים על הסטטוס שנוצר על ידי המשתמש ביומן Google:

• focusTimeProperties
• outOfOfficeProperties
• workingLocationProperties

הרשמה לקבלת עדכונים על שינויים באירועי סטטוס

אפשר להירשם לשינויים באירועי סטטוס במשאב Events של Calendar API.

משתמשים בשיטה events.watch ומציינים את calendarId של היומן שאליו רוצים להירשם ואחד או יותר מהערכים הבאים בשדה eventTypes:

• 'focusTime'
• 'outOfOffice'
• 'workingLocation'

יצירה ועדכון של אירועים ביומן שקשורים לסטטוס

כדי ליצור אירוע סטטוס, יוצרים מופע של המשאב Events באמצעות ה-method‏ events.insert, ומגדירים את השדות הנדרשים לסוג האירוע.

אם מעדכנים את אירוע הסטטוס באמצעות השיטה events.update, צריך לוודא ששדות החובה של האירוע נשמרים.

יצירת זמן לעצמי

כדי ליצור אירוע מסוג 'זמן לעצמי':

• מגדירים את eventType לערך 'focusTime'.
• כוללים את השדה focusTimeProperties.
• מגדירים את השדה transparency לערך 'opaque'.
• מגדירים את השדות start וend של האירוע כך שיהיה אירוע מתוזמן (עם שעת התחלה ושעת סיום ספציפיות).
  אי אפשר להגדיר אירועים מסוג 'זמן לעצמי' כאירועים שנמשכים כל היום.

פרטים על התכונה זמינים במאמר בנושא שימוש בפיצ'ר 'זמן לעצמי' ביומן Google

יצירת סטטוס 'לא בעבודה'

כדי ליצור אירוע מסוג 'לא בעבודה':

• מגדירים את eventType לערך 'outOfOffice'.
• כוללים את השדה outOfOfficeProperties.
• מגדירים את השדה transparency לערך 'opaque'.
• מגדירים את השדות start וend של האירוע כך שיהיה אירוע מתוזמן (עם שעת התחלה ושעת סיום ספציפיות).
  אירועים של יציאה לחופשה לא יכולים להיות אירועים שנמשכים כל היום.

פרטים על התכונה זמינים במאמר הפעלת הסטטוס 'לא במשרד'

יצירת מיקום עבודה

כדי ליצור אירוע של מיקום עבודה:

• מגדירים את eventType לערך 'workingLocation'.
• כוללים את השדה workingLocationProperties.
• מגדירים את השדה visibility לערך 'public'.
• מגדירים את השדה transparency לערך 'transparent'.

• מגדירים את השדות start ו-end של האירוע לאחת מהאפשרויות הבאות:

  • אירוע עם שעות התחלה וסיום ספציפיות.
  • אירוע שנמשך יום שלם (עם תאריכי התחלה וסיום שצוינו) שנמשך בדיוק יום אחד.

  אירועים של מיקום עבודה ליום שלם לא יכולים להימשך יותר מיום אחד, אבל אירועים עם שעות יכולים.

השדות הבאים הם אופציונליים, אבל מומלץ להשתמש בהם כדי לספק את חוויית המשתמש הטובה ביותר כשמוסיפים officeLocation:

• ‫workingLocationProperties.officeLocation.buildingId: הערך הזה צריך להיות זהה לערך buildingId במסד הנתונים של המשאבים של הארגון. כך המשתמשים יכולים ליהנות מכל התכונות של היומן, למשל מהצעות לחדרים.
• ‫workingLocationProperties.officeLocation.label: זו התווית שמוצגת ביומן Google בדפדפן ובאפליקציה לנייד. אפשר לאחזר מזהי בניינים ותוויות בניינים באמצעות ה-method‏ resources.buildings.list.

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

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

איך מציגים אירועים חופפים של מיקום עבודה

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

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

יצירת אירועי סטטוס ב-Google Apps Script

‫Google Apps Script היא שפת סקריפטים מבוססת-JavaScript בענן, שמאפשרת לכם ליצור אפליקציות עסקיות שמשתלבות עם Google Workspace. תסריטים מפותחים בכלי לעריכת קוד שמבוסס על דפדפן, והם מאוחסנים ומופעלים בשרתים של Google. אפשר גם לעיין במדריך לתחילת העבודה עם Google Apps Script כדי להתחיל להשתמש ב-Apps Script לשליחת בקשות ל-Google Calendar API.

בהוראות הבאות מוסבר איך לנהל אירועים של סטטוס באמצעות Google Calendar API כשירות מתקדם ב-Google Apps Script. רשימה מלאה של משאבים ושיטות ב-Google Calendar API זמינה במאמרי העזרה.

יצירה והגדרה של הסקריפט

1. כדי ליצור סקריפט, עוברים אל script.google.com/create.
2. בחלונית הימנית, ליד שירותים, לוחצים על סמל הוספת השירות .
3. בוחרים באפשרות Google Calendar API ולוחצים על הוספה.
4. אחרי ההפעלה, ה-API יופיע בחלונית הימנית. אפשר להשתמש במילת המפתח Calendar בעורך כדי לראות את השיטות והמחלקות שזמינות ב-API.

(אופציונלי) עדכון הפרויקט ב-Google Cloud

לכל פרויקט Google Apps Script יש פרויקט Google Cloud משויך. הסקריפט יכול להשתמש בפרויקט ברירת המחדל שנוצר אוטומטית על ידי סקריפט של Google Apps. אם רוצים להשתמש בפרויקט מותאם אישית ב-Google Cloud, צריך לבצע את השלבים הבאים כדי לעדכן את הפרויקט שמשויך לסקריפט.

1. בצד ימין של הכלי לעריכה, לוחצים על סמל הגדרות הפרויקט .
2. בקטע פרויקט Google Cloud Platform (GCP)‎, לוחצים על שינוי הפרויקט.
3. מזינים את מספר הפרויקט ב-Google Cloud שמשתתף בתוכנית Developer Preview ולוחצים על Set project.
4. בצד ימין, לוחצים על סמל העורך כדי לחזור לעורך הקוד.

הוספת קוד לסקריפט

בדוגמת הקוד הבאה אפשר לראות איך ליצור אירועי סטטוס, לקרוא אותם ולרשום אותם ביומן הראשי.

1. מדביקים את הקוד הבא בעורך הקוד.

   primary היא מילת מפתח לגישה ליומן הראשי של המשתמש המחובר. כדי לאחזר אירועים ביומן אחר, מגדירים את הפרמטר calendarId לכתובת אימייל. כך תוכלו לקרוא אירועי סטטוס ביומנים של משתמשים אחרים שיש לכם גישה ללו"ז שלהם לפחות. אי אפשר להוסיף אירועים של סטטוס ליומנים משניים.

   /** Creates a focus time event. */
   function createFocusTime() {
     const event = {
       start: { dateTime: '2023-11-14T10:00:00+01:00' },
       end: { dateTime: '2023-11-14T12:00:00+01:00' },
       eventType: 'focusTime',
       focusTimeProperties: {
         chatStatus: 'doNotDisturb',
         autoDeclineMode: 'declineOnlyNewConflictingInvitations',
         declineMessage: 'Declined because I am in focus time.',
       }
     }
     createEvent(event);
   }
   
   /** Creates an out of office event. */
   function createOutOfOffice() {
     const event = {
       start: { dateTime: '2023-11-15T10:00:00+01:00' },
       end: { dateTime: '2023-11-15T18:00:00+01:00' },
       eventType: 'outOfOffice',
       outOfOfficeProperties: {
         autoDeclineMode: 'declineOnlyNewConflictingInvitations',
         declineMessage: 'Declined because I am on vacation.',
       }
     }
     createEvent(event);
   }
   
   /** Creates a working location event. */
   function createWorkingLocation() {
     const event = {
       start: { date: "2023-06-01" },
       end: { date: "2023-06-02" },
       eventType: "workingLocation",
       visibility: "public",
       transparency: "transparent",
       workingLocationProperties: {
         type: 'customLocation',
         customLocation: { label: "a custom location" },
       }
     }
     createEvent(event);
   }
   
   /**
     * Creates a Calendar event.
     * See https://developers.google.com/workspace/calendar/api/v3/reference/events/insert
     */
   function createEvent(event) {
     const calendarId = 'primary';
   
     try {
       var response = Calendar.Events.insert(event, calendarId);
       var event = (response.eventType === 'workingLocation') ? parseWorkingLocation(response) : response;
       console.log(event);
     } catch (exception) {
       console.log(exception.message);
     }
   }
   
   /**
     * Reads the event with the given eventId.
     * See https://developers.google.com/workspace/calendar/api/v3/reference/events/get
     */
   function readEvent() {
     const calendarId = 'primary';
   
     // Replace with a valid eventId.
     const eventId = "sample-event-id";
   
     try {
       var response = Calendar.Events.get(calendarId, eventId);
       var event = (response.eventType === 'workingLocation') ? parseWorkingLocation(response) : response;
       console.log(event);
     } catch (exception) {
       console.log(exception.message);
     }
   }
   
   /** Lists focus time events. */
   function listFocusTimes() {
     listEvents('focusTime');
   }
   
   /** Lists out of office events. */
   function listOutOfOffices() {
     listEvents('outOfOffice');
   }
   
   /** Lists working location events. */
   function listWorkingLocations() {
     listEvents('workingLocation');
   }
   
   /**
     * Lists events with the given event type.
     * See https://developers.google.com/workspace/calendar/api/v3/reference/events/list
     */
   function listEvents(eventType = 'default') {
     const calendarId = 'primary'
   
     // Query parameters for the list request.
     const optionalArgs = {
       eventTypes: [eventType],
       showDeleted: false,
       singleEvents: true,
       timeMax: '2023-04-01T00:00:00+01:00',
       timeMin: '2023-03-27T00:00:00+01:00',
     }
     try {
       var response = Calendar.Events.list(calendarId, optionalArgs);
       response.items.forEach(event =>
         console.log(eventType === 'workingLocation' ? parseWorkingLocation(event) : event));
     } catch (exception) {
       console.log(exception.message);
     }
   }
   
   /**
     * Parses working location properties of an event into a string.
     * See https://developers.google.com/workspace/calendar/api/v3/reference/events#resource
     */
   function parseWorkingLocation(event) {
     if (event.eventType != "workingLocation") {
       throw new Error("'" + event.summary + "' is not a working location event.");
     }
   
     var location = 'No Location';
     const workingLocation = event.workingLocationProperties;
     if (workingLocation) {
       if (workingLocation.type === 'homeOffice') {
         location = 'Home';
       }
       if (workingLocation.type === 'officeLocation') {
         location = workingLocation.officeLocation.label;
       }
       if (workingLocation.type === 'customLocation') {
         location = workingLocation.customLocation.label;
       }
     }
     return `${event.start.date}: ${location}`;
   }
   

הרצת דוגמת הקוד

1. מעל עורך הקוד, בוחרים את הפונקציה להפעלה מהתפריט הנפתח ולוחצים על הפעלה.
2. בהרצה הראשונה, תתבקשו לאשר את הגישה. בודקים ומאשרים לאפליקציית Apps Script לגשת ליומן.
3. אפשר לבדוק את תוצאות ההרצה של הסקריפט ביומן ההרצה שמופיע בתחתית החלון.