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

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

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

Календари

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

События

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

Типы событий

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

FREQ — Частота повторения события (например, DAILY или WEEKLY ). Обязательно.
INTERVAL — используется совместно с FREQ для указания частоты повторения события. Например, FREQ=DAILY;INTERVAL=2 означает один раз в два дня.
COUNT — Количество раз, которое следует повторить это событие.
Для указания даты окончания повторения события можно использовать либо COUNT, либо UNTIL. Не используйте оба параметра в одном правиле.
UNTIL — Дата или дата и время, до которых событие должно быть повторено (включительно).
BYDAY — Days of the week on which the event should be repeated ( SU , MO , TU , etc.). Other similar components include BYMONTH , BYYEARDAY , and 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 события).

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

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

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

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