ICS-ленты календарей#

IncidentRelay может генерировать токенизированные подписные ICS-ленты для расписаний дежурств (on-call) команд. Это удобно для календарных клиентов, которые плохо поддерживают CalDAV, особенно Outlook и Google Calendar.

ICS-лента — это секретный URL, оканчивающийся на .ics. Любой, у кого есть этот URL, может читать экспортированный календарь дежурств этой команды, поэтому обращайтесь с URL как с паролем.

Когда использовать ICS-ленты#

Используйте ICS-ленты для клиентов, поддерживающих подписку на URL интернет-календаря.

Клиент	Рекомендуемый способ
Outlook в браузере	Подписка ICS
New Outlook	Подписка ICS
Google Calendar	Подписка ICS
Apple Calendar	Предпочтителен CalDAV
Thunderbird	CalDAV или ICS

Для Apple Calendar, Thunderbird и DAVx5 см. Синхронизацию календарей CalDAV.

Создание ICS-ленты#

Откройте Calendar.
Выберите конкретную команду. Экспорт недоступен для представления «all teams».
Нажмите Export.
Создайте ленту, если она ещё не существует.
Скопируйте сгенерированный URL ленты.

URL ленты выглядит так:

https://incidentrelay.example.com/api/calendar/feeds/<secret-token>.ics

Токен показывается при создании или перегенерации ленты. Ответы со списком существующих лент не должны снова раскрывать токен.

Подписка из Outlook#

В Outlook в браузере или в New Outlook:

Откройте Calendar.
Выберите Add calendar.
Выберите Subscribe from web.
Вставьте URL .ics от IncidentRelay.
Выберите имя и цвет.
Сохраните.

Частота обновления в Outlook управляется самим Outlook и может быть не мгновенной.

Подписка из Google Calendar#

В Google Calendar:

Откройте Other calendars.
Нажмите +.
Выберите From URL.
Вставьте URL .ics от IncidentRelay.
Нажмите Add calendar.

Частота обновления в Google Calendar управляется Google и может занять некоторое время.

Подписка из Apple Calendar по ICS#

Для Apple Calendar рекомендуется CalDAV, но также можно использовать подписку ICS.

На macOS:

Откройте Calendar.
Выберите File → New Calendar Subscription.
Вставьте URL .ics от IncidentRelay.
Настройте автообновление.

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

Управление лентами#

Перегенерация токена#

Перегенерация токена ленты создаёт новый секретный URL и немедленно делает старый URL недействительным.

Используйте это, когда:

URL был передан не тому человеку;
URL мог утечь;
пользователь, у которого был URL, больше не должен иметь возможность его использовать.

После перегенерации обновите подписки календарей новым URL.

Удаление ленты#

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

Неактивная команда или группа#

Если команда или её группа становятся неактивными, лента возвращает 403 Forbidden.

Эндпоинты API#

Эндпоинты управления требуют обычной аутентификации и разрешений API IncidentRelay.

GET    /api/calendar/feeds?team_id=<team_id>
POST   /api/calendar/feeds
POST   /api/calendar/feeds/<feed_id>/token
DELETE /api/calendar/feeds/<feed_id>

Эндпоинт подписки публичный, но защищён секретным токеном в URL:

GET /api/calendar/feeds/<secret-token>.ics

Публичным должен быть только эндпоинт подписки .ics. Не делайте публичными все эндпоинты /api/calendar/feeds/.

Пример использования API#

Создание ленты:

curl -s \
  -X POST \
  -H 'Authorization: Bearer INCIDENTRELAY_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"team_id":1,"name":"Cloud OPS subscription","past_days":7,"future_days":90}' \
  https://incidentrelay.example.com/api/calendar/feeds

Загрузка ленты:

curl -i https://incidentrelay.example.com/api/calendar/feeds/<secret-token>.ics

Успешный ответ должен иметь:

Content-Type: text/calendar
Cache-Control: no-store

Заметки по безопасности#

URL ленты является bearer-секретом.
Любой, у кого есть URL .ics, может читать экспортированный календарь команды.
Используйте HTTPS в production.
Перегенерируйте токен, если URL утёк.
Удалите ленту, чтобы полностью отключить URL.
Не логируйте полные токены лент.
Не публикуйте токенизированные URL в публичных трекерах задач, чатах или на скриншотах.

Устранение неполадок#

Календарный клиент сообщает, что URL недействителен#

Проверьте, что URL оканчивается на .ics и доступен из сети клиента.

https://incidentrelay.example.com/api/calendar/feeds/<secret-token>.ics

Лента возвращает 404#

Токен недействителен, перегенерирован, удалён или скопирован неправильно.

Создайте новую ленту или перегенерируйте токен.

Лента возвращает 403#

Лента существует, но команда или группа неактивны.

Реактивируйте команду/группу или создайте ленту для активной команды.

События не обновляются немедленно#

Outlook и Google Calendar управляют собственными интервалами обновления. IncidentRelay возвращает актуальное содержимое ICS, но внешний сервис может кэшировать подписку.

Лента пустая#

У команды может не быть ротаций или сгенерированных слотов дежурств в настроенном диапазоне экспорта.

Проверьте настройки ленты:

past_days
future_days

Увеличьте future_days, если экспортируемый диапазон слишком короткий.