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

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

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

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

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

Прочитать и просмотреть список событий статуса календаря.

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

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

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

'focusTime'
'outOfOffice'
'workingLocation'

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

Подписаться на уведомления об изменениях статуса

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

Используйте метод events.watch , указав calendarId календаря, на который нужно подписаться, и одно или несколько из следующих значений в поле eventTypes :

'focusTime'
'outOfOffice'
'workingLocation'

Создание и обновление событий статуса календаря.

To create a status event, you create an instance of the Events resource using the events.insert method, setting the required fields for the event type.

Если вы обновляете статус события с помощью метода 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 Calendar.

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

Создайте и настройте скрипт.

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

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

Каждый проект Google Apps Script связан с проектом Google Cloud. Ваш скрипт может использовать проект по умолчанию, который Google Apps Script создает автоматически. Если вы хотите использовать собственный проект 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}`;
}

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

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