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

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

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

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

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

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

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

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

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

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

الاشتراك في خدمة تلقّي تغييرات بشأن أحداث الحالة

يمكنك الاشتراك في التغييرات التي تطرأ على أحداث الحالة من خلال المورد 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". للحصول على قائمة كاملة بموارد وطرق واجهة برمجة التطبيقات Google Calendar API، يمكنك الاطّلاع على المستندات المرجعية.

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

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

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

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

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

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

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

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