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

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

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

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

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

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

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

لا يمكن إنشاء أحداث الموقع الجغرافي للعمل وتعديلها من خلال نقاط النهاية المجمّعة.

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

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

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

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

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

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. في اللوحة اليمنى بجانب الخدمات، انقر على "إضافة خدمة" .
3. اختَر Google Calendar API وانقر على إضافة.
4. بعد تفعيل واجهة برمجة التطبيقات، ستظهر في اللوحة اليمنى. يمكن إدراج الطرق والفئات المتاحة في واجهة برمجة التطبيقات باستخدام الكلمة الرئيسية Calendar في المحرّر.

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

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

1. على يمين المحرّر، انقر على رمز إعدادات المشروع .
2. ضمن مشروع Google Cloud Platform (GCP)، انقر على تغيير المشروع.
3. أدخِل رقم مشروع Google Cloud الذي يندرج ضمن "برنامج معاينة المطوّرين"، ثم انقر على ضبط المشروع.
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/workspace/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/workspace/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/workspace/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/workspace/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. في عملية التنفيذ الأولى، سيُطلب منك منح الإذن بالوصول. راجِع إذن وصول "برمجة تطبيقات Google" إلى تقويمك وامنحه.
3. يمكنك فحص نتائج تنفيذ النص البرمجي في سجلّ التنفيذ الذي يظهر في أسفل النافذة.