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

11.08.24

Интеграция - WEB-интеграция

Обновление Открытого пакета интеграций - библиотека для работы с Google Calendar. Позволяет создавать календари, события и управлять персональными списками календарей пользователей.

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

 
 Что такое Открытый Пакет Интеграций

 

Открытый Пакет Интеграций (ОПИ) - это open-source набор методов для простой и быстрой интеграции с различными популярными API. Он состоит из аналогичных по функционалу 1С-расширения (CFE), OS-пакета и программы для Windows и Linux, которые предоставляют готовые функции для работы с целым набором различных онлайн-сервисов.


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

 

 

 

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

 

 

 

 

  • Простая установка. ОПИ распространяется во множестве вариантах: как XML файлы расширения, как EDT проект расширения, как файл расширения формата .cfe (версия 1С 8.3.9), как файл пакета для OneScript и еще в целом наборе пакетов и файлов для Windows и Linux. Из этого набора вы всегда сможете выбрать тот способ установки, который лучше подойдет для вашей конкретной задачи

 

На момент последнего обновления данной статьи, доступны следующие API:

Наиболее актуальную информацию можно посмотреть в репозитории или на вводной странице документации.

 

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

 

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

 

 

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

Google Calendar Календарь Google API Интеграция Google Календарь web

См. также

Сайты и интернет-магазины WEB-интеграция Системный администратор Программист Пользователь Платформа 1С v8.3 Конфигурации 1cv8 1С:Управление торговлей 11 Автомобили, автосервисы Россия Управленческий учет Платные (руб)

Интеграционный модуль обмена между конфигурацией Альфа Авто 5 и Альфа Авто 6 и порталом AUTOCRM. Данный модуль универсален. Позволяет работать с несколькими обменами AUTOCRM разных брендов в одной информационной базе в ручном и автоматическом режиме.

36000 руб.

03.08.2020    17983    18    22    

17

Сайты и интернет-магазины Интеграция WEB-интеграция Платформа 1С v8.3 Конфигурации 1cv8 Управленческий учет Платные (руб)

Интеграция 1С и Битрикс 24. Разработка имеет двухстороннюю синхронизацию 1С и Bitrix24 задачами. Решение позволяет создавать пользователя в 1С из Битрикс24 и наоборот. Данная разработка технически подходит под все основные конфигурации линейки продуктов 1С:Предприятие 8.3 (платформа начиная с 8.3.23). При приобретении предоставляется 1 месяц бесплатных обновлений разработки. Доступна демо-версия продукта с подключением Вашего Битрикс24

7200 руб.

04.05.2021    20115    13    19    

18

WEB-интеграция 8.3.8 Конфигурации 1cv8 Автомобили, автосервисы Беларусь Украина Россия Казахстан Управленческий учет Платные (руб)

Расширение предназначено для конфигурации "1С:Предприятие 8. Управление Автотранспортом. ПРОФ". Функционал модуля: 1. Заполнение регистров сведений по подсистеме "Мониторинг", а именно: события по мониторингу, координаты по мониторингу, пробег и расход по мониторингу, текущее местоположение ТС по мониторингу 2. Заполнение путевого листа: пробег по мониторингу, время выезда/заезда, табличная часть ГСМ, места стоянок по геозонам. 3. Отчеты по данным загруженным в регистры сведений. 4. Предусмотрена автоматическая загрузка данных в фоновом режиме (условия работы данной загрузке читайте в описании товара) Модуль работает без включенной константы по настройкам мониторинга. Модуль формы предоставляется с открытым кодом, общий модуль защищен. Любой заинтересованный пользователь, имеет возможность скачать демо-версию расширения.

22656 руб.

25.05.2021    14544    42    8    

18

WEB-интеграция Программист Руководитель проекта Платформа 1С v8.3 Конфигурации 1cv8 1С:Франчайзи, автоматизация бизнеса Платные (руб)

Расширение значительно упрощает написание API на 1С. Веб программисты получают простой и понятный доступ к 1С. Описание API создаётся автоматически и представляется в виде удобном как для человека, так и для программной обработки.

24000 руб.

27.09.2024    1685    1    0    

3
Комментарии
Подписаться на ответы Инфостарт бот Сортировка: Древо развёрнутое
Свернуть все
1. Aleskey_K 35 26.02.24 16:08 Сейчас в теме
хорошая работа проделана, спасибо вам
bayselonarrend; +1 Ответить
2. baracuda 2 27.02.24 09:01 Сейчас в теме
Жаль что гугл календарь не умеет поля как ресурсы.
В своем время рассматривал его для расписаний в клинике, но остановился в итоге на стандартном планировщике от 1с.
3. CherTolik_26rus 16.08.24 16:19 Сейчас в теме
Огромное спасибо! Очень удобный и простой в освоении инструмент. Реализовал для своей группы календарь мероприятий с автоматической выгрузкой данных в гугл календарь.
Оставьте свое сообщение