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

توضّح هذه الصفحة كيفية استخدام Google Calendar API لإنشاء أحداث تعرض حالة مستخدمي "تقويم 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'

إنشاء أحداث حالة في "تقويم 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 Calendar API.

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

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

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

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

يرتبط كل مشروع في برمجة تطبيقات Google بمشروع على السحابة الإلكترونية في 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. في المرة الأولى التي يتم فيها تنفيذ البرنامج النصي، سيُطلب منك منح الإذن بالوصول. راجِع إذن وصول برمجة تطبيقات إلى تقويمك وامنحه.
3. يمكنك فحص نتائج تنفيذ النص البرمجي في سجلّ التنفيذ الذي يظهر في أسفل النافذة.