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

На этой странице объясняется, как использовать 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'

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

Чтобы создать статусное событие, вы создаете экземпляр ресурса 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

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

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

Создадим и настроим скрипт

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

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

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

  1. В левой части редактора нажмите параметров проекта».
  2. В разделе «Проект Google Cloud Platform (GCP)» нажмите «Изменить проект» .
  3. Введите номер проекта Google Cloud, который входит в программу Developer Preview, и нажмите «Задать проект» .
  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. При первом выполнении вам будет предложено авторизовать доступ. Проверьте и разрешите Apps Script доступ к вашему календарю.
  3. Результаты выполнения скрипта вы можете просмотреть в журнале выполнения , который появляется в нижней части окна.