Добро пожаловать!
Открытый пакет интеграций - набор инструментов для интеграции с некоторыми популярными API посредством CLI, 1C:Enterprise или OneScript. Он состоит из общих модулей, каждый из которых отвечает за свой API, а также нескольких модулей-инструментов, общих для всех.
Реализованные методы выполняют конечные задачи (вроде ОтправитьСообщение() или СоздатьПост()), что позволяет использовать их без углубления в реализацию. Однако, код, при этом, достаточно сильно декомпозирован - методы авторизации, получения данных и пр. по возможности вынесены в отдельные функции. Это позволяет легко добавлять новые методы, даже если они еще не реализованы в самой библиотеке на текущий момент.
Быстрый переход по документации:
Начало работы
Релизы библиотеки выходят в пяти вариантах:
- Как CLI приложение для Windows и Linux (exe, rpm, deb)
- Как XML файлы расширения для загрузки через конфигуратор
- Как EDT проект расширения
- Как отдельный файл расширения формата cfe
- Как OneScript пакет расширения ospx
Вне зависимости от выбранного способа установки, получать файлы необходимо из Release, так как в самих файлах репозитория бывают промежуточные данные и функции, находящиеся в процессе разработки.
Подробнее о каждом варианте релиза в разделе Про варианты релизов
Примеры использования
В качестве расширения 1С и OneScript пакета, Открытый пакет интеграций представляет из себя набор общих модулей с экспортными методами - по одному модулю на каждый из API. Все доступные методы являются функциями, т.е. возвращают значения. Как правило, это Соответствия, описывающие JSON ответа сервера, но также могут быть Двоичные данные (например, в методах скачивания файла) или строки (например в методах получения URL). Типы возвращаемых значений описаны для каждого метода в текущей документации и докумментирующих комментариях в самом коде библиотеки
Простой пример использования ОПИ - отправка картинки в Telegram:
Токен = "6129457865:AAFyzNYOAFbu...";
IDЧата = "461699897";
Текст = "Крутая картинка";
Картинка = "C:/picture.jpg"; // URL, путь на диске или Двоичные данные
Результат = OPI_Telegram.ОтправитьКартинку(Токен, IDЧата, Текст, Картинка);
Реализация ОПИ как CLI приложения, в свою очередь, повторяет функционал расширения и предоставляет доступ ко всем его методам из командной строки. Каждому параметру оригинальной функции соответствует опция, начинающаяся с символов --
, например --token
. Эти соответствия для каждого конкретного метода можно найти в текущей документации, а также в комментариях к функциям 1С/OneScript и встроенной справке приложения (справка по методу отображается при вызове необходимого метода без параметров, подробнее см. Работа с CLI версией)
Пример для CLI:
oint telegram ОтправитьКартинку \
--token "6129457865:AAFyzNYOAFbu..." \
--chat 461699897 \
--text "Крутая картинка" \
--picture "picture.jpg"
О работе с текущей документацией
Некоторые особенности данной документации, знание которых поможет использовать ее более эффективно и избежать недопониманий:
-
Каждый метод имеет свою страницу-описание. Как правило, заголовок страницы-описания совпадает с именем метода (с добавлением пробелов) и находится в подразделе, имя которого совпадает с именем области программного модуля. Если вы не можете найти страницу для конкретной интересующей вас функции, то попробуйте воспользоваться встроенным полнотекстовым поиском в правом верхнем углу
-
Параметры типа ДвоичныеДанные могут быть определены как пути к файлам или URL. Зачастую, для параметров с типом данных ДвоичныеДанные, в примерах кода документации используются URL или пути к файлам на диске. Это допустимое поведение, так как в начале всех функций входящие параметры преобразуются (по возможности) к необходимым типам. В случае с двоичными данными, например, при передаче строки, будет выполнена попытка найти файл на диске, получить его из интернета или преобразовать из Base64
-
Примеры результатов функций приведены в формате JSON, но в 1С и OS это будут Соответствия. Если в примере результата на странице-описании функции приведен JSON, то в 1С и OneScript это будет Соответствие - т.е. ответ будет десериализован. JSON строкой возвращается только в CLI версии