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

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

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

Календари

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

События

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

Типы событий

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

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

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

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

Начало и окончание события должны быть указаны по времени или оба должны охватывать весь день. Например, недопустимо указывать start.date и end.dateTime .

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

FREQ — Частота повторения события (например, DAILY или WEEKLY ). Обязательно.
INTERVAL — совместно с FREQ определяет частоту повторения события. Например, FREQ=DAILY;INTERVAL=2 означает один раз в два дня.
COUNT — Количество раз, которое должно повториться это событие.
Для указания окончания повторения события можно использовать либо COUNT, либо UNTIL. Не используйте оба параметра в одном правиле.
UNTIL — Дата или дата-время, до которых событие должно повторяться (включительно).
BYDAY — дни недели, в которые событие должно повторяться ( SU , MO , TU и т. д.). Другие похожие компоненты включают BYMONTH , BYYEARDAY и BYHOUR .

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

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

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

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

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

Событие, которое происходит с 6 до 7 утра каждый вторник и пятницу, начиная с 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"
],
…
```
Мероприятие на целый день, начинающееся 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 Календаря Google можно найти здесь .

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

Часовой пояс определяет регион, в котором действует единое стандартное время. В API Google Календаря часовые пояса указываются с помощью идентификаторов часовых поясов 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 прикрепляет часовой пояс к событию, так же, как при установке часового пояса события с помощью пользовательского интерфейса календаря :

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

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

Календари и усилители; события Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.