Библиотека для работы с Google Calendar API (open-source)

Если вы не слышали ранее об Открытом Пакете Интеграций (что вполне вероятно), то небольшая вводная часть ниже, под катом. Для тех, кто уже знаком с ОПИ, данный раздел можно пропустить.

Google Calendar - популярный онлайн сервис планирования и управления напоминаниями, один из множества сервисов Google Workspase.

Наравне с Sheets и Meet, Календарь от Google достаточно популярен в офисной среде как простой и удобный планировщик, сохраняющий данные в облаке. Однако, кроме привычного управления событиями при помощи веб-интерфейса, нам также доступен и REST API, с помощью которого новые календари и события можно создавать по средством http-запросов. Что и реализовано в новом обновлении Открытого пакета интеграций.

Реализованные методы:

• Работа с метаданными календарей
  • Создание календаря
  • Изменения метаданных календаря
  • Получение метаданных календаря
  • Удаление календаря
  • Очиститка основного календаря
• Работа с персональным списком календарей
  • Получения списка календарей
  • Получение календаря из списка
  • Добавление существующего календаря в список
  • Изменение календаря списка
  • Удаление календаря из списка
• Работа с событиями
  • Получение описания события
  • Получение списка событий
  • Получение события
  • Создание события
  • Перемещение события в другой календарь
  • Изменение события
  • Удаление события

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

Зачем интегрировать Календарь в 1С?

В первую очередь данный сервис интересен а)доступностью онлайн с любого устройства б)push-уведомлениями о событиях. Т.е. его, как минимум, можно использовать (если мы говорим про интеграцию с 1С) для автоматического создания некого "распорядка дня" работника на основе возникающих в системе событий

• Можно создавать события по датам доставки Заказов клиентам в календарях курьеров
• Можно отмечать даты привоза для работников склада
• Можно создавать таймлайны сроков различных учетных документов

*Красивая гифка от самого Google*

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

Про авторизацию и разделение пользователей

Инструкция по первоначальной настройке, как и всегда, есть в документации. Она подразумевает под собой создание аккаунта Google Workspase и настройку авторизации через OAuth. Вопрос состоит в том, что организовать работу можно как используя 1 аккаунт и, соответственно, 1 токен доступа для всех пользователей, так и получая токены для каждого пользователя под его аккаунтом отдельно. Если вкратце, то обе схемы будут выглядеть так:

Для одного аккаунта:

• Нужно просто сделать все как в инструкции

Для нескольких аккаунтов:

• Нужно выполнить настройку до пункта инструкции Получение Токена
• Передать ссылку из п.1 Получения токена каждому пользователю и обработать полученные от них коды отдельно

Данные токены всегда привязаны к конкретным пользователям. Если вы вызовете, например, функцию СоздатьКалендарь(Токен, Имя), то календарь появится у того пользователя, токен которого вы используете.

Однако, данный токен - временный. Как правило, срок его жизни равен 1 часу, по истечении которого необходимо выполнить обновление. Вам, конечно, не надо будет проворачивать действия из инструкции каждый раз для этого - в составе библиотеки есть функция OPI_GoogleWorkspace.ОбновитьТокен(), которая использует refresh_token для получения нового токена доступа. Refresh_token приходит вместе с первым токеном при авторизации по инструкции - его необходимо сохранить.

Ответ запроса из финального шага инструкции начальной настройки. 
access_token используется для работы,
refresh_token - для обновления access_token, со временем не изменяется

{
 "token_type": "Bearer",
 "refresh_token": "1//09au6OES3JN9oCgYIARAAGAkSNwF-L9Ir1B7uawfwafT1wE0FKO519Xj6JxawfawfyjMyJ_QlUZYLHZqw",
 "scope": "https://www.googleapis.com/auth/calendar",
 "expires_in": 3599,
 "access_token": "ya29.a0AfB_byA344tXkIawdawdwadadhyZQV8bSZn_snNXtY2HLb7l71awdawdawdad-ASgpzyOSWIvEmPruhUa_1yCCq6jvoD0r_q-fNEsARrH8zpJ3c6LNGWvwdg8CXsSxYaCgYKAWkSawfwafawfrCK0EP5kZY_A0171"
}

Он не обновляется и его можно использовать сколько угодно раз для получения нового токена доступа. Вполне допустимо вызывать функцию ОбновитьТокен() перед вызовом основных функций библиотеки, если они, конечно, не вызываются слишком часто - будет съедаться слишком много квоты запросов на бесполезное действие обновления и так рабочего токена

Подытожим: вам необходимо иметь как минимум 2 константы для работы через одного пользователя - это токен и рефреш токен, где рефреш токен изменяться не будет, но будет служить для обновления токена обычного, или справочник с 3 полями: пользователь, токен и рефреш токен, где последние два - по той же схеме. Ничего, кроме функции ОбновитьТокен(), после первичной настройки, вам для работы с авторизационными данными использовать будет не нужно

Кроме как здесь, это, более подробно, описано и в документации

Работа с календарями

Поговорим немного про функции для непосредственной работы с сервисом. Во-первых, вы конечно же можете создавать, изменять и удалять календари. Создается календарь только с наименованием функцией OPI_GoogleCalendar.СоздатьКалендарь(Токен, Наименование)

Наименование = "Тестовый календарь";
Результат    = OPI_GoogleCalendar.СоздатьКалендарь(Токен, Наименование); 

При изменении функцией ИзменитьМетаданныеКалендаря также можно добавить описание, если это необходимо. Но в данном случаем мы работаем с метаданными календаря, а не с конкретным экземпляром - это важно понимать. Для большей понятности на примере - вот результат функции ПолучитьМетаданныеКалендаря

{
 "conferenceProperties": {
  "allowedConferenceSolutionTypes": [
   "hangoutsMeet"
  ]
 },
 "description": "Тестовое описание",
 "summary": "Тестовый календарь",
 "timeZone": "UTC",
 "id": "155868c32be26e4c4123a107810d40b929b516935f080e4747261fdc3416227c@group.calendar.google.com",
 "etag": "\"4A10_PI6FFY129ggELzZ8veUU-U\"",
 "kind": "calendar#calendar"
}

А вот результат ПолучитьКалендарьСписка

{
 "conferenceProperties": {
  "allowedConferenceSolutionTypes": [
   "hangoutsMeet"
  ]
 },
 "accessRole": "owner",
 "foregroundColor": "#000000",
 "backgroundColor": "#ffd800",
 "colorId": "6",
 "description": "Тестовое описание",
 "summary": "Тестовый календарь",
 "defaultReminders": [],
 "timeZone": "UTC",
 "id": "f0fad8c7db43ef0adb71cbf035eb08cf80d8f8d51ba31fa86f4d5680dc2e9725@group.calendar.google.com",
 "etag": "\"1708423563386000\"",
 "kind": "calendar#calendarListEntry"
}

Они очень похожи, но, очень близко с тем, как это работает и в 1С, метаданные - это лишь некоторый макет календаря, в то время как календарь списка - уже конкретный экземпляр, с которым работает пользователь-валделец.

Это разделение имеет смысл, так как метаданные могут быть использованы для создания конкретных календарей у разных пользователей или даже у одного, но с разными дополнительными данными. В ОПИ для этого есть функция ДобавитьКалендарьВСписок() 

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

Разделение на метаданные и экземпляры в библиотеке отражено логическим разделением на области

В остальном же, календарь - достаточно простая сущность, а функции работы с ним просто делают то, что написано у них в названии. Подробнее, опять же, можно посмотреть в документации - там и примеры кода есть.

Работа с событиями

События интереснее календарей, комплекснее. Так как полей у события куда больше, то их значения передаются уже не параметрами функции, а соответствием. Его описание можно найти в функции ПолучитьОписаниеСобытия() 

    Час         = 3600;
    Событие     = Новый Соответствие;
    
    Событие.Вставить("Описание"               , "");                          // Описание события
    Событие.Вставить("Заголовок"              , "Новое событие");             // Заголовок события
    Событие.Вставить("МестоПроведения"        , "");                          // Строка описание места проведения
    Событие.Вставить("ДатаНачала"             , ТекущаяДатаСеанса());         // Дата начала события
    Событие.Вставить("ДатаОкончания"          , Событие["ДатаНачала"] + Час); // Дата окончания события
    Событие.Вставить("МассивURLФайловВложений", Новый Соответствие);          // Ключ - название, Значение - URL к файлу
    Событие.Вставить("ОтправлятьУведомления"  , Истина);                      // Признак отправки уведомлений участникам

Вам не обязательно вызывать эту функции, она служит просто как шпаргалка описания объекта события. Такое же соответствие используется и для изменения события созданного ранее.



 

Важно: При изменении события (и календаря тоже) достаточно указывать лишь поля, которые необходимо заменить. Поля, которые указаны не были, сохранят свое значение

   СоответствиеСобытия = Новый Соответствие;
   СоответствиеСобытия.Вставить("Описание"                 , Описание);
   СоответствиеСобытия.Вставить("Заголовок"                , Наименование);
   СоответствиеСобытия.Вставить("МестоПроведения"          , "В офисе");
   СоответствиеСобытия.Вставить("ДатаНачала"               , ТекущаяДатаСеанса());
   СоответствиеСобытия.Вставить("ДатаОкончания"            , СоответствиеСобытия["ДатаНачала"] + Час);
   СоответствиеСобытия.Вставить("МассивURLФайловВложений"  , Вложения);
   СоответствиеСобытия.Вставить("ОтправлятьУведомления"    , Истина);
    
   Результат = OPI_GoogleCalendar.СоздатьСобытие(Токен, Календарь, СоответствиеСобытия);           // Создание события
   Событие   = Результат[UID];
    
     
   СоответствиеСобытия = Новый Соответствие; 
   СоответствиеСобытия.Вставить("Описание", ОписаниеИзм);

   Результат = OPI_GoogleCalendar.ИзменитьСобытие(Токен, Календарь, СоответствиеСобытия, Событие); // Изменение события

Ну, в общем-то, и все

Google Calendar достаточно компактный сервис с таким же компактным API - календари да события. Однако эта простота и минималистичность делает его отличным выбором как на роль ежедневного планировщика, так и на роль инструмента оповещения о событиях из внешних источников. Например 1С 

Спасибо за внимание!

Репозиторий ОПИ: github.com/Bayselonarrend/OpenIntegrations

Последний релиз: github.com/Bayselonarrend/OpenIntegrations/releases/latest

Другие статьи про Открытый пакет интеграций на Инфостарт:

• Открытый пакет интеграций для популярных API: Telegram, VK, Viber, Twitter

• Работа с Notion API | Обновление Открытого пакета интеграций

• Библиотека работы с Яндекс Диском (Open-source) 

• Открываем свою лавку на платформе VK Market

• Библиотека для работы с Google Calendar API (open-source) 

• Telegram в режиме форума: делаем чаты комфортными

• Открытый пакет интеграций для OneScript

• Библиотека для работы с Google Drive API (open-source)

• OInt CLI - приложение Открытого пакета интеграций для командной строки

 

 Мой GitHub:     https://gitub.com/Bayselonarrend 
 Лицензия MIT:   https://mit-license.org