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

בדף הזה מוסבר איך משתמשים ב-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 באמצעות השיטה 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 Calendar API זמינה במאמרי העזרה.

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

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

(אופציונלי) מעדכנים את הפרויקט ב-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/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/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/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/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. מעל עורך הקוד, בוחרים מהתפריט הנפתח את הפונקציה שרוצים להריץ ולוחצים על Run.
2. בהפעלה הראשונה תתבקשו לאשר את הגישה. בודקים ומאשרים ל-Apps Script גישה ליומן.
3. אפשר לבדוק את התוצאות של ביצוע הסקריפט ביומן הביצוע שמופיע בחלק התחתון של החלון.