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

27.04.24

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

Новая библиотека в составе Открытого пакета Интеграций - Notion API. В этой статье мы рассмотрим, что такое Notion, для чего он нужен и как с ним работать из 1С при помощи ОПИ.

 

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

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

 

Открытый Пакет Интеграций (ОПИ) - это набор 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

 

 

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

 

 

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

web интеграция notion сервисы api http open-source github

См. также

Интеграция Альфа Авто 5 / Альфа Авто 6 и AUTOCRM / Инфотек

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

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

36000 руб.

03.08.2020    16273    14    18    

14

Интеграция 1С и Битрикс 24 — модуль синхронизации для обмена задачами

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

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

5040 руб.

04.05.2021    18461    10    15    

16

Модуль для обмена "1С:Предприятие 8. УАТ. ПРОФ" с FortMonitor

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

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

22656 руб.

25.05.2021    13115    34    8    

13

Автоматическая загрузка файлов (например, прайс-листов) из электронной почты, FTP, HTTP, их обработка и выгрузка на FTP (на сайт) и для других целей

Прайсы WEB-интеграция Ценообразование, анализ цен Файловый обмен (TXT, XML, DBF), FTP Системный администратор Программист Автомобили, автосервисы Оптовая торговля, дистрибуция, логистика Управленческий учет Платные (руб)

Программа с заданным интервалом времени (или по ручной команде) скачивает файлы (например, прайс-листы поставщиков) из различных источников: письма электронной почты, FTP или HTTP-адреса, и сохраняет их в каталог упорядоченной структуры. При этом извлекает файлы из архивов, может переименовывать файлы и менять их формат (csv, xls, txt). Можно настроить выгрузку обработанных файлов на сайт (через FTP-подключение). Программа будет полезна компаниям, у которых есть большое количество поставщиков и/или прайс-листы поставщиков обновляются часто (необязательно прайс-листы, файлы могут быть любого назначения). Собранные таким образом актуальные версии прайс-листов можно выгрузить с помощью программы себе на сайт (или на любой FTP-сервер) или выполнить другие необходимые задачи.

25200 руб.

28.05.2015    85804    26    51    

50
Комментарии
Подписаться на ответы Инфостарт бот Сортировка: Древо развёрнутое
Свернуть все
1. JohnyDeath 301 29.01.24 13:38 Сейчас в теме
В сторону Appflowy не смотрели? Это вроде как опенсор аналог Notion.
Я сам сижу на Notion, но понимаю, что могу проснуться одним прекрасным утром, а мне туда просто закруют доступ без возможности сдампить уже существующее. Поэтому периодически посматриваю на Appflowy, но дальше чтения дело пока не дошло.
R8s; nagimo; +2 Ответить
2. bayselonarrend 1409 29.01.24 13:49 Сейчас в теме
(1)Нет, честно говоря не смотрел. Пользовался только OneNote-ом из офиса до этого
3. yermak 51 31.01.24 02:24 Сейчас в теме
прошел путь
evernote -> notion -> synology notes (вроде так называется) -> obsidian

последние 3 за первую половину 23 года. Обсидиан пока самый удобный
Оставьте свое сообщение