زمان تمرکز، خارج از دفتر، و رویدادهای محل کار را مدیریت کنید

این صفحه نحوه استفاده از Google Calendar API را برای ایجاد رویدادهایی که وضعیت کاربران Google Calendar را نشان می دهد، توضیح می دهد. رویدادهای وضعیت توصیف می کنند که کاربران کجا هستند یا چه کاری انجام می دهند، از جمله اینکه آیا در زمان تمرکز هستند، خارج از دفتر هستند یا از یک مکان خاص کار می کنند.

در Google Calendar، کاربران می‌توانند زمان تمرکز، خارج از دفتر و رویدادهای محل کار را برای نشان دادن وضعیت و مکان سفارشی خود ایجاد کنند. این ویژگی‌ها فقط در تقویم‌های اصلی و برای برخی از کاربران تقویم Google در دسترس هستند.

برای جزئیات بیشتر، به استفاده از زمان تمرکز در Google Calendar بروید و مکان کاری را برای کاربران روشن یا خاموش کنید .

رویدادهای وضعیت تقویم را بخوانید و فهرست کنید

می‌توانید رویدادهای وضعیت تقویم را در منبع Events API تقویم بخوانید و فهرست کنید.

برای خواندن یک رویداد وضعیت، از متد events.get استفاده کنید و eventId رویداد را مشخص کنید.

برای فهرست کردن رویدادهای وضعیت، از متد events.list استفاده کنید و یک یا چند مورد از مقادیر زیر را در قسمت eventTypes مشخص کنید:

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

سپس، در اشیاء Event بازگشتی، بررسی کنید که فیلد eventType مقدار درخواستی را دارد و برای جزئیات در مورد وضعیت ایجاد شده توسط کاربر در Google Calendar به فیلد مربوطه مراجعه کنید:

• focusTimeProperties
• outOfOfficeProperties
• workingLocationProperties

در تغییرات رویدادهای وضعیت مشترک شوید

می‌توانید برای تغییرات رویدادهای وضعیت در منبع Events تقویم API مشترک شوید.

از متد events.watch استفاده کنید و calendarId Calendar را برای اشتراک و یک یا چند مقدار زیر را در قسمت eventTypes مشخص کنید:

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

رویدادهای وضعیت تقویم را ایجاد و به روز کنید

برای ایجاد یک رویداد وضعیت، یک نمونه از منبع Events را با استفاده از روش events.insert ایجاد می‌کنید و فیلدهای مورد نیاز را برای نوع رویداد تنظیم می‌کنید.

اگر رویداد وضعیت را با استفاده از روش events.update به روز کنید، رویداد باید فیلدهای لازم را حفظ کند.

زمان تمرکز ایجاد کنید

برای ایجاد یک رویداد زمان تمرکز:

• eventType روی 'focusTime' تنظیم کنید.
• فیلد focusTimeProperties را وارد کنید.
• فیلد transparency را روی 'opaque' تنظیم کنید.
• فیلدهای start و end رویداد را به عنوان یک رویداد زمان بندی شده تنظیم کنید (با تعیین زمان شروع و پایان).
  زمان تمرکز نمی تواند رویدادهای تمام روز باشد.

برای جزئیات ویژگی، به استفاده از زمان تمرکز در Google Calendar بروید

خارج از دفتر ایجاد کنید

برای ایجاد یک رویداد خارج از دفتر:

• eventType روی 'outOfOffice' تنظیم کنید.
• فیلد outOfOfficeProperties را وارد کنید.
• فیلد transparency را روی 'opaque' تنظیم کنید.
• فیلدهای start و end رویداد را به عنوان یک رویداد زمان بندی شده تنظیم کنید (با تعیین زمان شروع و پایان).
  رویدادهای خارج از دفتر نمی توانند رویدادهای تمام روز باشند.

برای جزئیات ویژگی، به نمایش زمانی که خارج از دفتر هستید بروید

ایجاد محل کار

برای ایجاد یک رویداد مکان کاری:

• eventType روی 'workingLocation' تنظیم کنید.
• فیلد workingLocationProperties را وارد کنید.
• فیلد visibility را روی 'public' تنظیم کنید.
• فیلد transparency را روی 'transparent' تنظیم کنید.

• فیلدهای start و end رویداد را به صورت زیر تنظیم کنید:

  • یک رویداد زمان بندی شده (با زمان شروع و پایان مشخص شده)؛
  • یک رویداد تمام روز (با تعیین تاریخ شروع و پایان) که دقیقاً یک روز را در بر می گیرد.

  رویدادهای مکان کاری تمام روز نمی توانند چندین روز طول بکشند، اما رویدادهای زمان بندی شده می توانند.

فیلدهای زیر اختیاری هستند اما برای بهترین تجربه کاربری هنگام درج officeLocation توصیه می‌شود:

• workingLocationProperties.officeLocation.buildingId : این باید با buildingId در پایگاه داده منابع سازمان مطابقت داشته باشد. این به کاربران کمک می کند از همه ویژگی های تقویم، به عنوان مثال پیشنهادات اتاق، بهره مند شوند.
• workingLocationProperties.officeLocation.label : این برچسبی است که در وب تقویم و سرویس گیرندگان تلفن همراه نشان داده می شود. می‌توانید شناسه‌های ساختمان و برچسب‌های ساختمان را با استفاده از روش resources.buildings.list واکشی کنید.

ایجاد و به‌روزرسانی رویدادهای مکان کاری از طریق نقاط پایانی دسته‌ای پشتیبانی نمی‌شود.

برای جزئیات ویژگی، به تنظیم ساعت و مکان کاری خود بروید و مکان کاری را برای کاربران روشن یا خاموش کنید

نحوه نمایش رویدادهای محل کار با هم تداخل دارند

یک کاربر می‌تواند چندین رویداد مکان کاری را به طور همزمان در تقویم خود داشته باشد که همپوشانی دارند، به این معنی که هر زمان معینی می‌تواند چندین مکان کاری برای آن تنظیم کند. در شرایطی که تنها یک مکان می‌تواند به کاربر نشان داده شود، باید آن مکان به طور مداوم در چندین برنامه نشان داده شود. هنگام انجام این کار، از دستورالعمل های زیر برای انتخاب رویداد برای نمایش استفاده کنید:

• رویدادهای زمان بندی شده بر رویدادهای تمام روز اولویت دارند.
• رویدادهای منفرد بر رویدادهای تکرار شونده و استثناهای آنها اولویت دارند.
• رویدادهایی که دیرتر شروع می شوند بر رویدادهایی که زودتر شروع می شوند اولویت دارند.
• رویدادهایی که مدت زمان کمتری دارند بر رویدادهایی که مدت زمان بیشتری دارند اولویت دارند.
• رویدادهایی که اخیراً ایجاد شده‌اند بر رویدادهایی که قبلاً ایجاد شده‌اند اولویت دارند.
• رویدادهایی که تا حدی همپوشانی دارند باید به عنوان دو رویداد مختلف نشان داده شوند که هر کدام مکان کاری خاص خود را دارند.

رویدادهای وضعیت را در Google Apps Script ایجاد کنید

Google Apps Script یک زبان برنامه نویسی ابری مبتنی بر جاوا اسکریپت است که به شما امکان می دهد برنامه های تجاری ایجاد کنید که با Google Workspace یکپارچه شوند. اسکریپت ها در یک ویرایشگر کد مبتنی بر مرورگر توسعه داده می شوند و در سرورهای Google ذخیره و اجرا می شوند. برای شروع استفاده از Apps Script برای ارسال درخواست‌ها به Google Calendar API، شروع سریع اسکریپت Google Apps را نیز ببینید.

دستورالعمل‌های زیر نحوه مدیریت رویدادهای وضعیت را با استفاده از Google Calendar API به عنوان یک سرویس پیشرفته در Google Apps Script شرح می‌دهند. برای فهرست کامل منابع و روش‌های Google Calendar API، به مستندات مرجع مراجعه کنید.

اسکریپت را ایجاد و تنظیم کنید

1. با رفتن به script.google.com/create یک اسکریپت ایجاد کنید.
2. در قسمت سمت چپ کنار Services ، روی Add a service کلیک کنید.
3. Google Calendar API را انتخاب کنید و روی Add کلیک کنید.
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 را که در برنامه پیش‌نمایش برنامه‌نویس است وارد کنید و روی تنظیم پروژه کلیک کنید.
4. در سمت چپ، Editor را انتخاب کنید تا به ویرایشگر کد بازگردید.

کد را به اسکریپت اضافه کنید

نمونه کد زیر نحوه ایجاد، خواندن و فهرست کردن رویدادهای وضعیت را در تقویم اصلی خود نشان می دهد.

1. موارد زیر را در ویرایشگر کد قرار دهید.

   اولیه یک کلمه کلیدی برای دسترسی به تقویم اصلی کاربر وارد شده است. برای بازیابی رویدادها در یک تقویم دیگر، پارامتر 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. می توانید نتایج اجرای اسکریپت را در Execution Log که در پایین پنجره ظاهر می شود، بررسی کنید.