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

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

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

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

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

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

للاطّلاع على حدث حالة، استخدِم السمة events.get، لتحديد eventId للحدث.

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

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

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

• focusTimeProperties
• outOfOfficeProperties
• workingLocationProperties

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

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

يمكنك استخدام events.watch، لتحديد calendarId من التقويم للاشتراك في إحدى القيم التالية أو أكثر في الحقل eventTypes:

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

إنشاء أحداث الحالة في "تقويم Google" وتعديلها

لإنشاء حدث حالة، يمكنك إنشاء مثيل مورد Events باستخدام events.insert، بإعداد الحقول المطلوبة لنوع الحدث.

في حال تحديث حدث الحالة باستخدام events.update، الحدث أن يحافظ على الحقول المطلوبة.

إنشاء وقت التركيز

لإنشاء حدث لوقت التركيز:

• ضبط السمة eventType على 'focusTime'
• تضمين focusTimeProperties .
• ضبط transparency إلى 'opaque'.
• اضبط start للحدث و حقول end لتكون حدثًا محدَّدًا زمنيًا (مع تحديد وقتَي البدء والانتهاء).
  لا يمكن أن تكون أوقات التركيز أحداثًا طوال اليوم.

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

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

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

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

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

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