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

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

ביומן 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'

יצירת אירועים ביומן Google לעדכון סטטוס

כדי ליצור אירוע סטטוס, יוצרים מופע של המשאב 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 באמצעות מילת המפתח Calendar בכלי העריכה.

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

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