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

Моей целью является поделиться наработками, поиск которых оказался на данный момент не тривиальным. Бизнес ценность решений я оставлю за рамками данной статьи.

Как получить доступы для работы с календарем

Для этого идем в настройки Yandex аккаунта, Безопасность, Пароли приложений и выбираем Календарь CalDAV, внутри которого создаем приложение и сохраняем от него пароль. Данный пароль вместе с вашей почтой будет использоваться в API для управлением встречами.

Как создать встречу в Yandex Calendar

Для работы с календарем мне потребовалось ознакомиться с сетевым протоколом CalDAV (Calendaring Extensions to WebDAV), который предназначен для управления встречами в календаре и синхронизации их между устройствами. Данный протокол позволяет работать с календарем по HTTP, передавая в запросе особый формат данный iCalendar, где можно разместить все параметры создаваемой или редактируемой вами встречи. Пример таких настроек:

val uid = UUID.randomUUID().toString()

val ics = """
		BEGIN:VCALENDAR
		VERSION:2.0
		PRODID:-//ProjectName//EN
		CALSCALE:GREGORIAN
		BEGIN:VEVENT
		UID:$uid
		DTSTAMP:$startUtc
		DTSTART:$startUtc
		DTEND:$endUtc
		LOCATION:$location
		SUMMARY:$title
		DESCRIPTION:$description
		ORGANIZER;CN="Pavel":mailto:$username
		ATTENDEE;CN="Attendee 1";RSVP=TRUE:mailto:$attendeeEmail
		END:VEVENT
		END:VCALENDAR
""".trimIndent()

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

Дату встречи вы можете передать через формат

DateTimeFormatter.ofPattern("yyyyMMdd'T'HHmmss'Z'")

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

Далее нам нужно выполнить PUT запрос для создания встречи

val eventUrl = "<https://caldav.yandex.ru/calendars/$username/events-default/$uid.ics>"
val request = HttpPut(eventUrl)
request.addHeader("Content-Type", "text/calendar; charset=utf-8")
request.entity = StringEntity(ics, StandardCharsets.UTF_8)
request.addHeader("Authorization", basicAuth(username, appPassword))

closeableHttpClient.execute(request).use { response ->
		val statusCode = response.statusLine.statusCode
		val body = response.entity?.content?.bufferedReader()?.use { it.readText() }
		if (statusCode !in 200..299) {
				throw RuntimeException("Failed to create event. Status: $statusCode. Body: $body")
		}
}

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

private fun basicAuth(user: String, password: String): String {
		val auth = "$user:$password"
		val encoded = Base64.getEncoder().encodeToString(auth.toByteArray(StandardCharsets.UTF_8))
		return "Basic $encoded"
}

fun poolingHttpClient(): CloseableHttpClient {
    val connectionManager = PoolingHttpClientConnectionManager().apply {
        maxTotal = 50
        defaultMaxPerRoute = 20
    }

    val requestConfig = RequestConfig.custom()
        .setConnectTimeout(5000)
        .setSocketTimeout(10000)
        .setConnectionRequestTimeout(2000)
        .setCookieSpec(CookieSpecs.IGNORE_COOKIES)
        .build()

    return HttpClients.custom()
        .setConnectionManager(connectionManager)
        .setDefaultRequestConfig(requestConfig)
        .setKeepAliveStrategy(DefaultConnectionKeepAliveStrategy.INSTANCE)
        .build()
}

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

Для удаления события необходимо выполнить запрос с передачей uid события, которое вы хотите удалить:

fun deleteEvent(uid: String) {
    val eventUrl = "<https://caldav.yandex.ru/calendars/$username/events-default/$uid.ics>"
    val request = HttpDelete(eventUrl)
    request.addHeader("Authorization", basicAuth(username, appPassword))

    return closeableHttpClient.execute(request).use { response ->
        val statusCode = response.statusLine.statusCode
        val body = response.entity?.content?.bufferedReader()?.use { it.readText() }
        if (statusCode !in 200..299) {
            throw RuntimeException("Failed to create event. Status: $statusCode. Body: $body")
        }
    }
}

Давайте теперь разберемся, как добавить во встречу ссылку на Telemost.

Создаем креды для доступа к Telemost

Для создания OAuth токена для работы с Telomost API нужно в https://oauth.yandex.ru/ создать приложение для доступа к API, после чего сохранить полученный token. Давайте теперь для примера создадим ссылку на будущую встречу в Telemost

Создание встречи

Подробное описание по работе с Telemost API находится в документации. Я лишь рассмотрю один интересующий меня кейс - создание встречи, а для разнообразия буду использовать использовать WebClient .

val monoMeetingResponse = webClient.post()
    .uri("<https://cloud-api.yandex.net/v1/telemost-api/conferences>")
    .bodyValue(meetingSettings)
    .accept(MediaType.APPLICATION_JSON)
    .header("Authorization", "OAuth $YANDEX_TOKEN")
    .retrieve()
    .bodyToMono(MeetingResponse::class.java)
    .doOnError { e ->
        logger.error("Telemost service error: ${e.message}")
    }
    .retryWhen(
        Retry.backoff(3, Duration.ofSeconds(2))
            .doBeforeRetry { signal ->
                logger.warn("Retrying Yandex API call. Attempt: ${signal.totalRetries() + 1}")
            }
    )

Настройка встречи достаточно простая

val meetingSettings = MeetingSettings(
		waitingRoomLevel = "PUBLIC",
		cohosts = listOf(Cohost("login@yandex.ru"))
)

После выполнения запроса мы получим join_url , который можно будет использовать внутри location нашего объекта для создания встречи.

Итоги

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

Обзор управления встречами в Yandex Calendar и интеграция с Telemost