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

توضّح هذه الصفحة كيفية استخدام واجهة برمجة التطبيقات 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 ضمن مكتبة برمجة التطبيقات 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 Apps Script هي لغة برمجة نصية لخدمات السحابة الإلكترونية تستند إلى JavaScript، وتتيح لك إنشاء تطبيقات تجارية تتكامل مع Google Workspace. يتم تطوير النصوص البرمجية في محرِّر رموز برمجية مستند إلى المتصفّح، ويتم تخزينها وتنفيذها على خوادم Google. اطّلِع أيضًا على البدء السريع لـ Google Apps Script لبدء استخدام برمجة تطبيقات Google لإرسال طلبات إلى Google Calendar API.

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

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

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