Календари и события

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

Календари

Календарь — это набор связанных событий вместе с дополнительными метаданными, такими как сводка, часовой пояс по умолчанию, местоположение и т. д. Каждый календарь идентифицируется идентификатором, который является адресом электронной почты. У календарей может быть несколько владельцев.

События

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

Типы событий

Календарь Google поддерживает одиночные и повторяющиеся события:

  • Одно событие представляет собой уникальное явление.
  • Повторяющееся событие определяет несколько вхождений.

Мероприятия также могут быть рассчитаны по времени или на целый день :

  • Временное событие происходит между двумя конкретными моментами времени. Временные события используют start.dateTime и end.dateTime , чтобы указать, когда они происходят.
  • Событие на весь день охватывает весь день или последовательную серию дней. События на весь день используют поля start.date и end.date , чтобы указать, когда они происходят. Обратите внимание, что поле часового пояса не имеет значения для событий, происходящих в течение всего дня.

Организаторы

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

На следующей диаграмме показаны концептуальные отношения между календарями, событиями и другими связанными элементами:

Основные календари и другие календари

Основной календарь — это особый тип календаря, связанный с одной учетной записью пользователя. Этот календарь создается автоматически для каждой новой учетной записи пользователя, и его идентификатор обычно совпадает с основным адресом электронной почты пользователя. Пока существует учетная запись, ее основной календарь никогда не может быть удален или «лишен» пользователя. Однако им по-прежнему можно поделиться с другими пользователями.

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

Календарь и список календарей

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

CalendarList — это коллекция всех записей календаря, которые пользователь добавил в свой список (показан на левой панели веб-интерфейса). Вы можете использовать его для добавления и удаления существующих календарей в/из списка пользователей. Вы также используете его для извлечения и установки значений свойств календаря, специфичных для пользователя, таких как напоминания по умолчанию. Другим примером является цвет переднего плана, так как разные пользователи могут установить разные цвета для одного и того же календаря.

В следующей таблице сравнивается значение операций для двух коллекций:

Операция Календари КалендарьСписок
insert Создает новый дополнительный календарь. По умолчанию этот календарь также добавляется в список календарей создателя. Вставляет существующий календарь в список пользователя.
delete Удаляет дополнительный календарь. Удаляет календарь из списка пользователя.
get Извлекает метаданные календаря, например название, часовой пояс. Получает метаданные, а также индивидуальные настройки пользователя, такие как цвет или переопределение напоминаний.
patch / update Изменяет метаданные календаря. Изменяет пользовательские свойства календаря.

Повторяющиеся события

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

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

Правило повторения

Расписание повторяющегося события состоит из двух частей:

  • Его начальное и конечное поля (которые определяют первое вхождение, как если бы это было просто отдельное одиночное событие) и

  • Его поле повторения (которое определяет, как событие должно повторяться с течением времени).

Поле повторения содержит массив строк, представляющих одно или несколько RRULE , RDATE или EXDATE , как определено в RFC 5545 .

Свойство RRULE является наиболее важным, так как оно определяет регулярное правило повторения события. Он состоит из нескольких компонентов. Некоторые из них:

  • FREQ — частота, с которой должно повторяться событие (например, DAILY или WEEKLY ). Необходимый.

  • INTERVAL — Работает вместе с FREQ , чтобы указать, как часто должно повторяться событие. Например, FREQ=DAILY;INTERVAL=2 означает один раз в два дня.

  • COUNT — количество повторений этого события.

  • UNTIL — Дата или дата-время, до которых должно повторяться событие (включительно).

  • BYDAY — дни недели, в которые должно повторяться событие ( SU , MO , TU и т. д.). Другие аналогичные компоненты включают BYMONTH , BYYEARDAY и BYHOUR .

Свойство RDATE указывает дополнительные даты или дату-время, когда должно произойти событие. Например, RDATE;VALUE=DATE:19970101,19970120 . Используйте это, чтобы добавить дополнительные вхождения, не охватываемые RRULE .

Свойство EXDATE похоже на RDATE, но указывает даты или дату и время, когда событие не должно происходить. То есть такие случаи должны быть исключены. Это должно указывать на действительный экземпляр, сгенерированный правилом повторения.

EXDATE и RDATE могут иметь часовой пояс и должны быть датами (а не датой-временем) для событий на весь день.

Каждое из свойств может встречаться в поле повторения несколько раз. Повторение определяется как объединение всех RRULE и RDATE за вычетом исключенных всеми правилами EXDATE .

Вот несколько примеров повторяющихся событий:

  1. Событие, которое происходит с 6:00 до 7:00 каждый вторник и пятницу, начиная с 15 сентября 2015 года и заканчивающееся после пятого события 29 сентября:

    ...
    "start": {
     "dateTime": "2015-09-15T06:00:00+02:00",
     "timeZone": "Europe/Zurich"
    },
    "end": {
     "dateTime": "2015-09-15T07:00:00+02:00",
     "timeZone": "Europe/Zurich"
    },
    "recurrence": [
     "RRULE:FREQ=WEEKLY;COUNT=5;BYDAY=TU,FR"
    ],
    …
    
  2. Мероприятие, которое длится весь день и начинается 1 июня 2015 года и повторяется каждые 3 дня в течение месяца, кроме 10 июня, но включая 9 и 11 июня:

    ...
    "start": {
     "date": "2015-06-01"
    },
    "end": {
     "date": "2015-06-02"
    },
    "recurrence": [
     "EXDATE;VALUE=DATE:20150610",
     "RDATE;VALUE=DATE:20150609,20150611",
     "RRULE:FREQ=DAILY;UNTIL=20150628;INTERVAL=3"
    ],
    …
    

Экземпляры и исключения

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

Модификации повторяющихся событий могут влиять либо на все повторяющееся событие (и все его экземпляры), либо только на отдельные экземпляры. Экземпляры, которые отличаются от своего родительского повторяющегося события, называются исключениями .

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

Примеры работы с повторяющимися событиями и экземплярами через API календаря можно найти здесь .

Часовые пояса

Часовой пояс определяет регион, в котором соблюдается единое стандартное время. В API календаря вы указываете часовые пояса, используя идентификаторы часовых поясов IANA .

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

Часовой пояс календаря

Часовой пояс календаря также известен как часовой пояс по умолчанию из-за его влияния на результаты запроса. Часовой пояс календаря влияет на то, как значения времени интерпретируются или представляются методами events.get() , events.list() и events.instances() .

Преобразование часового пояса результата запроса
Результаты методов get() , list() и instances() возвращаются в часовом поясе, указанном в параметре timeZone . Если вы опустите этот параметр, все эти методы будут использовать часовой пояс календаря по умолчанию.
Сопоставление событий в течение всего дня с запросами с временными скобками
Методы list() и instances() позволяют указать фильтры времени начала и окончания, при этом метод возвращает экземпляры, попадающие в указанный диапазон. Часовой пояс календаря используется для расчета времени начала и окончания событий в течение всего дня, чтобы определить, соответствуют ли они спецификации фильтра.

Часовой пояс события

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

  • Укажите смещение часового пояса в поле dateTime , например 2017-01-25T09:00:00-0500 .
  • Укажите время без смещения, например 2017-01-25T09:00:00 , оставив поле timeZone пустым (при этом неявно используется часовой пояс по умолчанию).
  • Укажите время без смещения, например 2017-01-25T09:00:00 , но используйте поле timeZone для указания часового пояса.

Вы также можете указать время события в формате UTC, если хотите:

  • Укажите время в формате UTC: 2017-01-25T14:00:00Z или используйте смещение нуля 2017-01-25T14:00:00+0000 .

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

Фрагмент скриншота, показывающий часовой пояс события

Часовой пояс повторяющегося события

Для повторяющихся событий всегда должен быть указан один часовой пояс. Он нужен для того, чтобы расширить повторы события.