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

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

משתמשים יכולים ליצור ביומן 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 במשאבים של הארגון במסד הנתונים. כך המשתמשים יכולים ליהנות מכל התכונות של יומן Google, למשל הצעות לחדרים.
• ‫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 API זמינה במאמרי העזרה.

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

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

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

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

1. בצד ימין של הכלי לעריכה, לוחצים על סמל הגדרות הפרויקט .
2. בקטע פרויקט Google Cloud Platform (GCP)‎, לוחצים על שינוי הפרויקט.
3. מזינים את מספר הפרויקט בענן של Google Cloud שמשתתף בתוכנית ההפצה המקדימה, ולוחצים על 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. אפשר לבדוק את תוצאות ההפעלה של הסקריפט ביומן ההפעלה שמופיע בתחתית החלון.