Подключить Google Calendar

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

Подключение аккаунта

Откройте Календарь на боковой панели.
Нажмите Добавить аккаунт календаря на боковой панели календаря. (Тот же раздел есть в Настройки → Рабочее пространство → Профиль и идентичность, в блоке Google Calendar.)
Выберите способ авторизации:
- Использовать приложение Google от Control Center — настраивать ничего не нужно. Это вариант по умолчанию, если ваша сборка поставляется с таким приложением.
- Использовать свой клиент Google Cloud — вставьте идентификатор клиента и секрет из своего проекта (см. Свой клиент Google).
Нажмите Подключить Google Calendar. В диалоге появятся короткий код и ссылка на страницу подтверждения Google.
Откройте эту страницу на любом устройстве, введите код и подтвердите запрошенный доступ. Диалог закроется сам, и события начнут синхронизироваться.

Обмен выполняет сервер, а не ваше устройство, и он же хранит полученный токен обновления — поэтому код подтверждают на «любом устройстве», а не именно в этом приложении.

Аккаунт подключается только к активному рабочему пространству. Переключите рабочее пространство — и увидите календари уже другого пространства.

При подключении запрашиваются область calendar.readonly и ваш адрес электронной почты — одни и те же области и для встроенного приложения, и для клиента, который вы вставляете. Control Center читает события; он не создаёт, не изменяет и не удаляет их и не отвечает на приглашения в Google.

Как работает синхронизация

Расписание принадлежит серверу: он обходит подключённые аккаунты всех рабочих пространств каждые две минуты и записывает события в базу данных рабочего пространства. Клиенты никогда не обращаются к Google — они читают то, что записал сервер.

Обход инкрементальный. Первый проход по каждому календарю загружает скользящее окно (60 дней назад, 90 дней вперёд) и сохраняет токен синхронизации Google; последующие проходы предъявляют этот токен и получают только изменения — именно это делает двухминутный цикл приемлемым по затратам. Каждые 24 часа, а также всякий раз, когда Google признаёт токен недействительным, окно переустанавливается полной синхронизацией.

Токены обновления хранятся на стороне сервера в secrets.json в каталоге данных сервера и записываются с правами только для владельца (0600) — не в связке ключей ОС и никогда не на клиентском устройстве.

Подключение нескольких аккаунтов

Рабочее пространство может подключить несколько аккаунтов Google (например, рабочий и личный). Повторите подключение для каждого; их события объединяются в одних и тех же представлениях «Месяц», «Неделя» и «Расписание». Каждый аккаунт синхронизируется и обновляется независимо, и каждый можно отключить отдельно.

Повторное подключение аккаунта с истёкшим токеном

Если Google окончательно признаёт токен аккаунта недействительным (отозванный или давно истёкший сеанс), синхронизация останавливается, и Control Center показывает в календаре баннер Подключить снова, а также системное уведомление. Нажмите Подключить снова и подтвердите новый код; баннер исчезнет при следующей успешной синхронизации.

Отключение аккаунта

На боковой панели календаря (или в Настройки → Рабочее пространство → Профиль и идентичность) нажмите Отключить у аккаунта. Это удалит его синхронизированные события и очистит сохранённые токены на сервере.

Подключение с headless-сервера

Сервер без графического интерфейса подключает тот же аккаунт из собственного терминала:

GOOGLE_OAUTH_CLIENT_ID=<id> GOOGLE_OAUTH_CLIENT_SECRET=<secret> \
  cc_server calendar connect --data-dir <dir> --workspace <workspace-id>

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

Сборка из исходного кода не содержит клиента Google, поэтому идентификатор и секрет обязательны — задайте GOOGLE_OAUTH_CLIENT_ID и GOOGLE_OAUTH_CLIENT_SECRET. Флага --google-client-id нет (неизвестные флаги игнорируются). Без этой пары переменных окружения команда завершается ошибкой об отсутствующем клиенте.

Свой клиент Google (форки и самостоятельный хостинг)

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

В консоли Google Cloud включите Google Calendar API и настройте экран согласия OAuth, добавив области calendar.readonly, openid и email. Пока приложение не проверено, добавьте себя как тестового пользователя. Добавление calendar.events на экране согласия не включает ответы на приглашения — Control Center никогда не запрашивает эту область.
Создайте идентификатор клиента OAuth с типом приложения TVs and limited input devices и скопируйте и идентификатор клиента, и секрет клиента.
Укажите их либо при подключении (выберите в диалоге Использовать свой клиент Google Cloud), либо для всего сервера с помощью GOOGLE_OAUTH_CLIENT_ID и GOOGLE_OAUTH_CLIENT_SECRET.

Пара, заданная для всего сервера, заменяет встроенную везде, в том числе за вариантом «использовать приложение Google от Control Center», — так что на вашем собственном сервере этот вариант означает ваше приложение.

Секрет клиента никогда не покидает сервер: ни один ответ RPC его не несёт, а аккаунт, подключённый через собственный клиент сервера, хранит маркер, а не копию пары, — поэтому для смены секрета достаточно перезапуска с новым значением.

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

Симптом	Вероятная причина
В диалоге нет встроенного варианта	В этой сборке нет клиента Google (сборка из исходного кода), либо сервер запущен только с половиной пары. Нужны и идентификатор, и секрет
`invalid_scope` при запуске потока	Calendar не разрешён для клиента с кодом устройства в этом проекте Cloud. Используйте проект с клиентом loopback или веб-клиентом
`invalid_client` от Google	Клиент не относится к типу TVs and limited input devices, либо идентификатор и секрет взяты от разных клиентов
Подтверждение проходит, но синхронизация пуста	Ваш аккаунт не добавлен как тестовый пользователь на экране согласия, либо область `calendar.readonly` не предоставлена
Код истекает до подтверждения	Коды устройства недолговечны. Запустите подключение заново, чтобы получить новый
«Не удалось обновить ответ» при ответе на приглашение	Так и должно быть: при подключении область `calendar.events` никогда не запрашивается
Синхронизация останавливается с предупреждением об обновлении в журнале сервера	Аккаунт подключён клиентом, который больше не настроен. Подключите аккаунт снова или восстановите идентификатор и секрет того клиента

Связанные руководства

Записать и резюмировать встречу: превратите событие в запись
Запустить headless-сервер: где живут токены и расписание синхронизации
Настроить интеграцию GitHub

Связанные понятия

Календарь и планирование