Если вы не слышали ранее об Открытом Пакете Интеграций (что вполне вероятно), то небольшая вводная часть ниже, под катом. Для тех, кто уже знаком с ОПИ, данный раздел можно пропустить.
Открытый Пакет Интеграций (ОПИ) - это набор open-source библиотек для интеграции с некоторыми популярными API для 1С:Предприятие и OneScript. Он представляет из себя расширение (а для OneScript - пакет), состоящее из общих модулей, каждый из которых отвечает за свой собственный сервис для работы.
- ОПИ бесплатен и имеет открытый исходный код на GitHub. Вы всегда можете получить последнюю версию библиотеки на странице репозитория, а подписавшись - узнавать о выходе обновлений. Все релизы сопровождаются статьями на Инфостарт и разделами единой документации. На Инфостарт вы можете подписаться уже хоть сейчас, а про документацию я расскажу далее.
- Удобная единая документация. Она расположена на сайте opi.neocities.org и содержит в себе всю информацию, необходимую для работы: инструкции по предварительным действиям для начала интеграции, описания всех методов с параметрами и возвращаемыми значениями, примеры кода и т.д. Каждый API имеет там свой раздел.
- Простая установка. ОПИ распространяется сразу в 3-х вариантах для 1С: как XML файлы расширения, как EDT проект расширения и как файл расширения формата .cfe (версия 1С 8.3.9), а также как файл пакета для OneScript. Однако, помимо этого, вы даже можете просто скопировать код ОПИ руками! Весь проект состоит из модулей, которые можно перенести в аналогичные, созданные самостоятельно в конфгураторе/проекте.
На момент последнего обновления данной статьи, доступны следующие API:
Наиболее актуальную информацию можно посмотреть в репозитории или на вводной странице документации.
Что такое Notion?
Notion - это сервис облачных таблиц и заметок. Ближайшие аналоги - Evernote и OneNote. С его помощью вы можете легко создавать текстовые документы, календари, списки дел, а так же объединять страницы с одинаковыми наборами полей в базы данных. Это помогает как просто структурировать полезную информацию, разделяя ее на категории, так и создавать целые системы визуализации с отборами/сортировками по признакам или даже связями по ключам между разными базами данных.
Любая заметка или база данных, при этом, может быть опубликована в открытый доступ в два щелчка. Это будет отдельная страница со своим адресом: подобное вы могли уже встречать, например, как подборку телеграм каналов по 1С от SeiOkami или в моей недавней статье про Github с топом репозиториев
В целом, помимо отсутствия русского языка, работа в Notion через веб-интерфейс достаточно интуитивна: нажимаем создать страницу, выбираем заголовок страницы и тот формат, который нам наиболее удобен. В случае необходимости можно добавлять на страницу несколько блоков с информацией: календари, списки с чекбоксами, текст, картинки, таблицы, таймлайны и пр. Страницы могут как создаваться в корне рабочей области, так и быть дочерними для других страниц или баз.
Нас же будет сейчас интересовать другое: как устроена структура и иерархия при работе с Notion и как наиболее просто и удобно визуализировать там информацию, вытягивая ее из 1С. А развернуться есть где: согласитесь, достаточно удобно иметь возможность очень легко и быстро создать, скажем, интерактивное табло, обновляемое из 1С по регламентному заданию или после ввода данных в систему. Но обо всем по-порядку.
Иерархия элементов
Основным принципом работы с Notion является иерархия. Каждый элемент является дочерним какому-нибудь другому и, в свою очередь, может являться родителем для любого количества новых. Всего есть два основных вида иерархии:
Как мы видим, они отличаются первыми элементами: страницы могут наследоваться от баз данных, а могут и от других страниц.
В случае со страницами все довольно просто: две и более любые, ничем не связанные между собой, страницы могут быть просто "вложены" друг в друга внутри дерева иерархии. Это позволяет объединять группы без какой-либо дополнительной структуризации - так, как вам захочется.
Однако, куда интереснее вариант с базой данных, на котором мы сейчас остановимся.
Что такое база данных?
База данных в Notion - это таблица, поля которой определяют набор свойств всех её дочерних страниц. Если в случае наследования "страница -> страница" никаких свойств у дочерней страницы нет - мы просто выбираем ей заголовок, а потом добавляем блоки, то в случае с БД - каждая созданная дочерняя страница имеет тот набор полей, который определен в её родителе. То есть, дочерние страницы - это просто записи, как в любой другой реляционной базе данных.
В веб-интерфейсе база данных выглядит вот так:
Функционал её довольно широк: можно создавать поля разных типов, создавать представления (view) с разными сортировками и фильтрами, добавлять свойства на саму базу, а также создавать зависимости одной базы от другой. Для лучшего понимания принципа, добавим в базу новую страницу. Сделать это можно в виде добавления строки:
Данная запись ничем не отличается от страницы, созданной отдельно, за тем лишь исключением, что поля, наследованные из базы, удалить нельзя.
Мы все так же можем добавлять сюда блоки, подгружать шаблоны и даже добавлять дочерние страницы. Последние, при этом, к базе уже не привязаны: не наследуют ее свойства и в таблице не отображаются
Объединять страницы в базу имеет смысл во множестве случаев, когда их информация - не просто набор текста или картинок, но требует отбора и сортировки по определенным критериям. Впрочем, в этом она не отличается от любой другой таблицы: будь то таблица в Excel или таблица настоящей большой БД.
Что такое страница?
Следующий уровень иерархии - страница.
Страница (будь то строка базы или обычная страница в рабочей области) - это документ, объединяющий определенный набор полей и блоков. В случае с БД, поля определяются, в первую очередь, схемой самой БД, но, в любом случае, какая угодно страница может быть дополнена и своей уникальной информацией.
В этом страницы Notion похожи на таковые в разных текстовых процессорах - например в Word, но со своими особенностями:
1. Notion облачный и имеет систему прав и доступов для пользователей. Это дает возможность разрешить доступ к странице участникам своей команды, что позволит каждому из них в любой момент времени обладать актуальной информацией и редактировать её.
Если же вам нужна страница не для внутреннего использования, а для представления информации в публичный доступ, то с этим тем более не будет никаких проблем - базы данных и страницы легко публикуются в сеть прямо из Notion.
2. В то время, как мы можем интегрироваться с Notion, Notion сам умеет интегрироваться со сторонними сервисами. Делать это при помощи API, к сожалению, пока нельзя, но зато можно вообще исключить собственную интеграцию напрямую, а просто подключить страницу сразу, скажем, к Google Drive или Jira
3. В Notion есть большое количество блоков, которыми можно дополнять содержимое страницы. Причем многие из них способны обращаться за данными в базы. Т.е. визуализировать на странице информацию из баз-источников. Использовать их можно как отдельно, так и в составе шаблонов, которых есть огромное количество. Подробнее об этом мы поговорим далее.
Что такое блок?
Блок - это атомарная единица представления информации. В первую очередь именно "представления", так как хранимого значения внутри блока может и не быть - во многих из них информация подтягивается от внешних источников. Но вот за то, как информация будет отображена, блок отвечает всегда.
Больше про них, в общем-то, сказать и нечего, разве что разнообразие - достаточно велико. Не говоря уже про шаблоны на их основе, о которых было сказано выше.
Причем тут 1С?
Все это длинное вступление действительно необходимо - с его помощью было убито сразу 2 зайца. Во-первых, узнавая о принципах работы сервиса, вы уже вполне могли прикинуть возможное его применение - вариаций масса. Во-вторых, без объяснения основы было бы трудно раскрыть смысл методов, реализованных в библиотеке уже непосредственно для 1С.
Мы рассмотрели основную тройку объектов: база данных, страница и блок. Собственно, за них и отвечают 3 главные части библиотеки - Работа с базами данных, Работа со страницами и Работа с блоками. Плюс, дополнительно один, небольшой, для получения данных пользователей.
На текущий момент реализованы следующие действия:
- Работа с базами данных
- Создание базы данных
- Получение информации о базе данных
- Изменение свойств базы данных
- Работа со страницами
- Создание страниц: дочерних другой странице и в базу данных
- Получение информации о странице
- Изменение свойств страницы
- Работа с блоками
- Создание блока
- Удаление блока
- Получение блока
- Получение списка дочерних блоков
- Работа с пользователями
- Получение списка пользователей рабочего пространства
- Получение информации о пользователе по ID
Как и у других библиотек ОПИ, у Notion есть свой раздел в общей документации на opi.neocities.org. Там можно найти инструкцию по получению данных, необходимых для начала работы, а также описание всех методов с примерами кода, параметрами и возвращаемыми значениями
Здесь бы хотелось отметить лишь несколько отдельных моментов, которые могут вызвать вопросы в процессе работы:
- У Notion нет механизма загрузки файлов. Все файлы, необходимые для использования при работе с Notion API, должны быть доступны по какому-нибудь URL и в виде URL передаваться.
- У любой базы должно быть поле с типом Title. Т.е. минимальный набор полей у БД - одно поле с типом Title. Список типов и способ описания полей можно найти в документации.
- Самый простой способ использования блоков через API - создание их руками в веб-интерфейсе и получение по ID уже в 1С. В Notion API достаточно сложная структура описания блоков, так как они представлены в большом разнообразии и при этом каждый - со своей схемой. Чем описывать их в 1С через структуры и массивы, куда более удобно создать блок обычным способом, после чего получить функцией ВернутьБлок(), передав туда ID. В ответ вернется готовая структура блока, данными которой можно манипулировать. После правки, данную структуру можно применять на любых других страницах при помощи функции СоздатьБлок(). Пример кода есть в документации
Заключение
На мой взгляд, Notion - отличный способ визуализации информации и информации из 1С в частности. Будь то некое публичное табло с информацией для пользователей/заказчиков/покупателей или же данные для внутреннего использования, с необходимостью в постоянной актуализации - инструментария хватит на любую задачу. Не говоря уже о том, что Notion и как самостоятельный продукт - отличный менеджер для записок и управления проектами. Так что советую попробовать
Спасибо за внимание!
Репозиторий ОПИ: github.com/Bayselonarrend/OpenIntegrations
Последний релиз: github.com/Bayselonarrend/OpenIntegrations/releases/latest
Другие статьи про Открытый пакет интеграций на Инфостарт:
Открытый пакет интеграций для OneScript
Мой GitHub: https://gitub.com/Bayselonarrend Лицензия MIT: https://mit-license.org
