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

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

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

Календари

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

События

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

Типы событий

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

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

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

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

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

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

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

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

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

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

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

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

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

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: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"
],
…

Мероприятие, продолжающееся целый день, которое начинается 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 события).

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

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

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

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

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