Типы событий

На этой странице объясняется свойство eventType и описываются типы событий, доступные в API Google Календаря.

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

Тип события можно определить в следующих местах API:

  • Все события возвращаются с указанием eventType .
  • eventType необходимо задать при создании или обновлении ресурса события. Если он не задан, будет использоваться тип 'default' .
  • В вызове Events:list можно указать eventTypes для вывода списка событий определенных типов. Если тип не указан, будут возвращены все типы событий.
  • В вызове Events:watch можно указать eventTypes для подписки на обновления событий определенных типов. Если тип не указан, запрос приведет к подписке на все типы событий.

Событие по умолчанию

События с типом default создаются и используются в качестве одного из основных ресурсов API Google Календаря. Они поддерживают широкий спектр свойств , которые можно использовать для дальнейшей настройки события.

Для начала работы с событиями Google Календаря см. раздел «Создание событий» .

День рождения

Дни рождения — это особые события, длящиеся целый день, и они повторяются ежегодно.

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

API Google Календаря поддерживает методы get , instances и list для чтения событий, связанных с днями рождения. eventTypes можно установить в значение 'birthday' , чтобы отображались только события, связанные с днями рождения. Если тип не указан, дни рождения будут отображаться вместе со всеми другими типами событий.

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

  • type : Вид данного особого события, будь то день рождения, годовщина или другая знаменательная дата.
  • customTypeName : Заданная пользователем метка для этого специального события. Это поле заполняется, если для type установлено значение 'custom' .
  • contact : Имя ресурса контакта, к которому привязано это специальное событие, если таковое имеется. Оно имеет формат 'people/c12345' и может использоваться для получения сведений о контакте из API People .

API позволяет создавать события, связанные с днем ​​рождения, используя метод insert со следующими параметрами:

  • eventType установлен на 'birthday' .
  • Поля start и end должны определять событие, охватывающее весь день и длящееся ровно один день.
  • Значение поля visibility должно быть 'private' .
  • Значение поля transparency должно быть 'transparent' .
  • Необходимо установить ежегодное повторение, то есть поле recurrence должно иметь значение 'RRULE:FREQ=YEARLY' . Для событий, приходящихся на 29 февраля, должно действовать следующее правило повторения: 'RRULE:FREQ=YEARLY;BYMONTH=2;BYMONTHDAY=-1' .
  • Может содержать colorId , summary и reminders .
  • Может содержать birthdayProperties . Если указано, type должен быть 'birthday' , а поля customTypeName и contact должны быть пустыми.
  • Не может содержать никаких других свойств события.

API позволяет обновлять colorId , summary и reminders для событий дня рождения с помощью методов update и patch . Поля start и end также можно обновлять для изменения даты события. В этом случае новые значения должны определять событие на весь день, которое длится ровно один день. Детали времени события дня рождения нельзя обновить, если событие связано с contact или его type — 'self' .

Google Calendar API doesn't allow creating birthday events with custom birthdayProperties , or updating these properties. Significant dates can be edited with the People API , and the changes are synced with Google Calendar. Similarly, users can edit their own birthday on their Google Account profile , and it syncs with Google Calendar.

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

API поддерживает import событий, связанных с днем ​​рождения; однако событие будет импортировано как событие по умолчанию. Другими словами, eventType будет иметь значение 'default' .

API поддерживает метод watch для подписки на изменения событий, связанных с днями рождения, в Google Календаре. eventTypes можно установить в значение 'birthday' для подписки на обновления событий, связанных с днями рождения. Если тип не указан, будет оформлена подписка на все типы событий, включая дни рождения.

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

Изменение организатора мероприятия, посвященного дню рождения, с помощью методов move или update не поддерживается.

События из Gmail

События, автоматически генерируемые из Gmail, имеют тип события 'fromGmail' .

API Google Календаря не позволяет создавать события этого типа с помощью метода insert .

API позволяет обновлять свойства colorId , reminders , visibility , transparency , status , attendees , а также private и shared расширенные свойства с помощью методов update и patch .

The API supports get and list methods for reading events from Gmail. eventTypes can be set to 'fromGmail' to list only events generated from Gmail. If no type is specified, events from Gmail will be listed alongside all other event types.

API поддерживает метод watch для подписки на изменения событий из Gmail в Google Календаре. Если тип не указан, будет оформлена подписка на все типы событий, включая 'fromGmail' .

События из Gmail можно удалить, используя метод delete в API Google Календаря.

Изменение организатора мероприятия из Gmail с помощью методов move или update не поддерживается.

Время сосредоточенной работы, отсутствие на рабочем месте и рабочее место

API Google Календаря можно использовать для создания и управления событиями, отображающими статус пользователей Google Календаря.

Эти функции доступны только в основных календарях и некоторым пользователям Google Календаря. Подробнее см. в разделе «Управление временем сосредоточенной работы, сообщениями об отсутствии на рабочем месте и событиями, связанными с рабочим местом» .

Изучите типы событий в 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 Календаря см. в справочной документации .

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

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

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

Каждый проект Google Apps Script связан с проектом Google Cloud. Ваш скрипт может использовать проект по умолчанию, который Google Apps Script создает автоматически. Если вы хотите использовать собственный проект Google Cloud, см. раздел «Переключение на другой стандартный проект Cloud» . После настройки проекта Google Cloud выберите «Редактор в левой части экрана, чтобы вернуться в редактор кода.

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

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

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

    const CALENDAR_ID = 'CALENDAR_ID' || 'primary';

/** Lists default events. */
function listDefaultEvents() {
  listEvents('default');
}

/** Lists birthday events. */
function listBirthdays() {
  listEvents('birthday');
}

/** Lists events from Gmail. */
function listEventsFromGmail() {
  listEvents('fromGmail');
}

/**
  * Lists events with the given event type. If no type is specified, lists all events.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/list
  */
function listEvents(eventType = undefined) {
  // Query parameters for the list request.
  const optionalArgs = {
    eventTypes: eventType ? [eventType] : undefined,
    singleEvents: true,
    timeMax: '2024-07-30T00:00:00+01:00',
    timeMin: '2024-07-29T00:00:00+01:00',
  }
  try {
    var response = Calendar.Events.list(CALENDAR_ID, optionalArgs);
    response.items.forEach(event => 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() {
  try {
    var response = Calendar.Events.get(CALENDAR_ID, 'EVENT_ID');
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

/** Creates a default event. */
function createDefaultEvent() {
  const event = {
    start: { dateTime: '2024-07-30T10:30:00+01:00'},
    end: { dateTime: '2024-07-30T12:30:00+01:00'},
    description: 'Created from Apps Script.',
    eventType: 'default',
    summary: 'Sample event',
  }
  createEvent(event);
}

/** Creates a birthday event. */
function createBirthday() {
  const event = {
    start: { date: '2024-01-29' },
    end: { date: '2024-01-30' },
    eventType: 'birthday',
    recurrence: ["RRULE:FREQ=YEARLY"],
    summary: "My friend's birthday",
    transparency: "transparent",
    visibility: "private",
  }
  createEvent(event);
}

/**
  * Creates a Calendar event.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/insert
  */
function createEvent(event) {

  try {
    var response = Calendar.Events.insert(event, CALENDAR_ID);
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

    Замените следующее:

    • CALENDAR_ID : Адрес электронной почты календаря, для которого нужно получать и создавать события. Изначально эта константа установлена ​​на 'primary' , которое является ключевым словом для доступа к основному календарю вошедшего в систему пользователя. Изменение этого значения позволяет читать события в календарях других пользователей, к которым у вас есть доступ.
    • EVENT_ID : Идентификатор события. Вы можете вызвать Events:list , чтобы получить идентификаторы событий.

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

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