إدارة أحداث وقت التركيز وخارج المكتب ومكان العمل

توضّح هذه الصفحة كيفية استخدام Google Calendar API لإنشاء أحداث تعرض حالة مستخدمي "تقويم Google". تصف أحداث الحالة مكان تواجد المستخدمين أو نشاطهم، بما في ذلك ما إذا كانوا في وقت التركيز أو خارج المكتب أو يعملون من موقع جغرافي معيّن.

في "تقويم Google"، يمكن للمستخدمين إنشاء أحداث "وقت التركيز" و"خارج المكتب" و"الموقع الجغرافي للعمل" للإشارة إلى حالتهم المخصّصة وموقعهم الجغرافي. لا تتوفّر هذه الميزات إلا في التقاويم الأساسية ولبعض مستخدمي "تقويم Google".

لمزيد من التفاصيل، انتقِل إلى مقالتَي استخدام ميزة "وقت التركيز" في "تقويم Google" وتفعيل ميزة "مكان العمل" أو إيقافها للمستخدمين.

قراءة أحداث حالة "تقويم Google" وعرضها

يمكنك قراءة أحداث حالة "تقويم Google" وعرضها في مورد Events ضمن واجهة برمجة التطبيقات Calendar API.

لقراءة حدث حالة، استخدِم الطريقة events.get مع تحديد eventId الحدث.

لعرض أحداث الحالة، استخدِم الأسلوب events.list، مع تحديد قيمة واحدة أو أكثر من القيم التالية في حقل eventTypes:

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

بعد ذلك، في عناصر Event التي تم عرضها، تحقّق من أنّ الحقل eventType يحتوي على القيمة المطلوبة، ثمّ راجِع الحقل المقابل للحصول على تفاصيل عن الحالة التي أنشأها المستخدم في "تقويم Google":

• focusTimeProperties
• outOfOfficeProperties
• workingLocationProperties

الاشتراك في التغييرات على أحداث الحالة

يمكنك الاشتراك في التغييرات التي تطرأ على أحداث الحالة من خلال المورد Events في واجهة برمجة تطبيقات "تقويم Google".

استخدِم طريقة events.watch لتحديد calendarId من "تقويم Google" للاشتراك فيها، وقيمة واحدة أو أكثر من القيم التالية في الحقل 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" على الويب وعملاء الأجهزة الجوّالة. يمكنك جلب أرقام تعريف المباني وتصنيفاتها باستخدام الأسلوب resources.buildings.list.

لا يمكن إنشاء أحداث مكان العمل وتعديلها من خلال نقاط نهاية الحِزم.

للاطّلاع على تفاصيل الميزة، انتقِل إلى مقالتَي ضبط ساعات العمل والموقع الجغرافي وتفعيل ميزة "مكان العمل" أو إيقافها للمستخدمين.

كيفية عرض الأحداث المتداخلة في مكان العمل

يمكن أن يكون لدى المستخدم أحداث متعددة لمكان العمل في تقويمه في الوقت نفسه وتتداخل مع بعضها، ما يعني أنّه يمكن ضبط عدة أماكن عمل في أي وقت معيّن. في الحالات التي يمكن فيها عرض موقع جغرافي واحد فقط على المستخدم، يجب عرض هذا الموقع الجغرافي بشكلٍ متسق على عدة تطبيقات. عند إجراء ذلك، استخدِم الإرشادات التالية لاختيار الحدث الذي تريد عرضه:

• تُمنَح الأحداث الموقّتة أولاً الأولوية على الأحداث التي تستمر طوال اليوم.
• تُمنَح الأحداث الفردية الأولوية على الأحداث المتكررة و استثناءاتها.
• وتحظى الأحداث التي تبدأ لاحقًا بالأولوية على الأحداث التي تبدأ في وقت سابق.
• تُعطى الأولوية للأحداث ذات المدّة الأقصر على تلك التي تبلغ مدّتها أطول.
• وتحظى الأحداث التي تم إنشاؤها مؤخرًا بالأولوية على الأحداث التي تم إنشاؤها سابقًا.
• يجب عرض الأحداث المتداخلة جزئيًا كحدثَين مختلفَين لكلٍّ منهما موقع عمل خاص به.

إنشاء أحداث الحالة في برمجة تطبيقات Google

برمجة تطبيقات Google هي لغة برمجة نصية تستند إلى JavaScript على السحابة الإلكترونية، وتتيح لك إنشاء تطبيقات للأنشطة التجارية تتكامل مع Google Workspace. يتم تطوير النصوص البرمجية في محرر رموز يستند إلى المتصفح، ويتم تخزينها وتشغيلها على خوادم Google. يمكنك أيضًا الاطّلاع على البدء السريع لبرمجة تطبيقات Google لبدء استخدام "برمجة تطبيقات Google" لإرسال الطلبات إلى واجهة برمجة تطبيقات "تقويم Google".

توضّح التعليمات التالية كيفية إدارة أحداث الحالة باستخدام Google Calendar API كخدمة متقدّمة في Google Apps Script. للحصول على قائمة كاملة بموارد وطرق واجهة برمجة التطبيقات Google Calendar API، يمكنك الاطّلاع على المستندات المرجعية.

إنشاء النص البرمجي وإعداده

1. أنشئ نصًا برمجيًا من خلال الانتقال إلى script.google.com/create.
2. في اللوحة اليمنى بجانب الخدمات، انقر على إضافة خدمة add .
3. اختَر Google Calendar API وانقر على إضافة.
4. بعد تفعيل واجهة برمجة التطبيقات، ستظهر في اللوحة اليمنى. يمكن إدراج الطرق والفئات المتاحة في واجهة برمجة التطبيقات باستخدام الكلمة الرئيسية تقويم في المحرِّر.

(اختياري) تعديل مشروع Google Cloud

يرتبط كل مشروع على "برمجة تطبيقات Google" بمشروع على Google Cloud. يمكن أن يستخدم النص البرمجي المشروع التلقائي الذي تنشئه أداة "برمجة تطبيقات Google" تلقائيًا. إذا كنت تريد استخدام مشروع مخصّص على Google Cloud، اتّبِع الخطوات التالية لتعديل المشروع المرتبط بنصك البرمجي.

1. على الجانب الأيمن من المحرر، انقر على رمز إعدادات المشروع settings.
2. ضمن مشروع Google Cloud Platform (GCP)، انقر على تغيير المشروع.
3. أدخِل رقم مشروع Google Cloud المدرَج في "برنامج معاينة المطوّرين"، ثم انقر على ضبط المشروع.
4. على يمين الصفحة، انقر على رمز المحرِّر code للتوغّل مرة أخرى في محرِّر الرموز.

إضافة رمز إلى النص البرمجي

يوضّح نموذج الرمز البرمجي التالي كيفية إنشاء أحداث الحالة وقراءتها وإدراجها في تقويمك الأساسي.

1. ألصِق ما يلي في أداة تعديل الرموز.

   /** 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. يمكنك فحص نتائج تنفيذ النص البرمجي في ملف سجلّ التنفيذ الذي يظهر في أسفل النافذة.