Эта страница переведена с помощью Cloud Translation API.

Управляйте событиями, посвященными времени концентрации, вне офиса и рабочему месту.

На этой странице объясняется, как использовать API Google Календаря для создания событий, отображающих статус пользователей Google Календаря. События статуса описывают, где находятся пользователи и чем они занимаются, включая то, сосредоточены ли они на работе, находятся вне офиса или работают из определённого местоположения.

В Google Календаре пользователи могут создавать события, связанные с временем концентрации внимания, отсутствием на рабочем месте и рабочим местоположением, чтобы указать свой статус и местоположение. Эти функции доступны только в основных календарях и некоторым пользователям Google Календаря.

Более подробную информацию можно найти в разделах Использование времени концентрации внимания в Календаре Google и Включение или выключение рабочего местоположения для пользователей .

Чтение и перечисление событий статуса календаря

Вы можете прочитать и составить список событий статуса календаря в ресурсе Events API календаря.

Чтобы прочитать событие статуса, используйте метод events.get , указав eventId события.

Чтобы составить список событий статуса, используйте метод events.list , указав одно или несколько из следующих значений в поле eventTypes :

'focusTime'
'outOfOffice'
'workingLocation'

Затем в возвращенных объектах Event проверьте, что поле eventType имеет запрошенное значение, и обратитесь к соответствующему полю для получения подробной информации о статусе, созданном пользователем в Google Calendar:

Подписаться на изменения статуса событий

Вы можете подписаться на изменения статуса событий в ресурсе « Events » 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 в базе данных ресурсов организации. Это позволяет пользователям использовать все функции Календаря, например, получать предложения по помещениям.
workingLocationProperties.officeLocation.label : эта метка отображается в веб- и мобильных клиентах Календаря. Вы можете получить идентификаторы и метки зданий с помощью метода resources.buildings.list .

Создание и обновление событий рабочего местоположения через конечные точки пакета не поддерживается.

Подробную информацию о функциях см. в разделах «Настройка рабочего времени и местоположения» и «Включение или выключение рабочего местоположения для пользователей».

Как показать перекрывающиеся события в рабочих местах

В календаре пользователя может быть одновременно несколько событий, связанных с рабочими местами, которые перекрываются, то есть для любого момента времени могут быть установлены несколько рабочих мест. Если пользователю может быть показано только одно место, оно должно отображаться единообразно в нескольких приложениях. При этом следуйте следующим рекомендациям для выбора отображаемых событий:

Временные мероприятия имеют приоритет над мероприятиями, рассчитанными на целый день.
Одиночные события имеют приоритет над повторяющимися событиями и их исключениями .
События, которые начинаются позже, имеют приоритет над событиями, которые начинаются раньше.
События с меньшей продолжительностью имеют приоритет над событиями с большей продолжительностью.
Недавно созданные события имеют приоритет над событиями, созданными ранее.
Частично перекрывающиеся события следует отображать как два разных события, каждое из которых имеет свое собственное место проведения.

Создание событий статуса в Google Apps Script

Google Apps Script — это язык облачных скриптов на основе JavaScript, позволяющий создавать бизнес-приложения, интегрируемые с Google Workspace. Скрипты разрабатываются в браузерном редакторе кода и хранятся и запускаются на серверах Google. См. также краткое руководство по Google Apps Script , чтобы начать использовать Apps Script для отправки запросов к API Google Календаря.

Ниже приведены инструкции по управлению статусами событий с помощью API Google Календаря как расширенного сервиса в Google Apps Script. Полный список ресурсов и методов API Google Календаря см. в справочной документации .

Создайте и настройте сценарий

Создайте сценарий, перейдя по ссылке script.google.com/create .
На левой панели рядом с пунктом Услуги нажмите услугу.
Выберите API Календаря Google и нажмите Добавить .
После включения API отображается на левой панели. Доступные методы и классы API можно просмотреть с помощью ключевого слова Calendar в редакторе.

(Необязательно) Обновите проект Google Cloud

С каждым проектом Google Apps Script связан проект Google Cloud. Ваш скрипт может использовать проект по умолчанию, который Google Apps Script автоматически создаёт. Если вы хотите использовать собственный проект Google Cloud, выполните следующие действия для обновления проекта, связанного со скриптом.

В левой части редактора нажмите проекта.
В разделе «Проект Google Cloud Platform (GCP)» нажмите «Изменить проект» .
Введите номер проекта Google Cloud, который участвует в программе Developer Preview, и нажмите «Настроить проект» .
С левой стороны выберите Редактор , чтобы вернуться к редактору кода.

Добавить код в скрипт

В следующем примере кода показано, как создавать, читать и перечислять статусные события в вашем основном календаре.

Вставьте следующий код в редактор кода.

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

Запустить пример кода

Над редактором кода выберите в раскрывающемся меню функцию, которую необходимо запустить, и нажмите кнопку Выполнить .
При первом запуске вам будет предложено разрешить доступ. Проверьте и разрешите Apps Script доступ к вашему календарю.
Результаты выполнения скрипта можно просмотреть в журнале выполнения , который отображается в нижней части окна.