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

בדף הזה מוסבר איך להשתמש בממשק ה-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'

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

כדי ליצור אירוע סטטוס, יוצרים מכונה של המשאב 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 ללקוחות באינטרנט ובנייד. אפשר לאחזר מזהי בניינים ותוויות בניין באמצעות השיטה resources.buildings.list.

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

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

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

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

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

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

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

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

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

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

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

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

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