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

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

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

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

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

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