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

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

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

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

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

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

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

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

'focusTime'
'outOfOffice'
'workingLocation'

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

الاشتراك في إشعارات التغييرات على أحداث الحالة

يمكنك الاشتراك لتلقّي إشعارات بالتغييرات التي تطرأ على أحداث الحالة في مورد Events ضمن Calendar API.

استخدِم طريقة events.watch، مع تحديد calendarId للتقويم الذي تريد الاشتراك فيه وقيمة واحدة أو أكثر من القيم التالية في الحقل eventTypes:

'focusTime'
'outOfOffice'
'workingLocation'

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

لإنشاء حدث حالة، عليك إنشاء مثيل لمورد 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، يُرجى الرجوع إلى المستندات المرجعية.

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

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

(اختياري) تعديل مشروع على السحابة الإلكترونية

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

على يمين المحرّر، انقر على رمز إعدادات المشروع .
ضمن مشروع Google Cloud Platform (GCP)، انقر على تغيير المشروع.
أدخِل رقم مشروع Google Cloud الذي يندرج ضمن "برنامج الاستخدام المبكر للمطوّرين"، ثم انقر على ضبط المشروع.
على الجانب الأيسر، حدد أداة التعديل للانتقال مرة أخرى إلى أداة تعديل الرموز.

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

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

ألصِق ما يلي في أداة تعديل الرموز.

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}`;
}

تشغيل عيّنة التعليمات البرمجية

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

إدارة أحداث وقت التركيز وخارج المكتب ومكان العمل تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.