Перейти к основному содержимому

Добро пожаловать!

OPI

Открытый пакет интеграций - набор инструментов для интеграции с некоторыми популярными 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"

О работе с текущей документацией​

Некоторые особенности данной документации, знание которых поможет использовать ее более эффективно и избежать недопониманий:

  1. Каждый метод имеет свою страницу-описание. Как правило, заголовок страницы-описания совпадает с именем метода (с добавлением пробелов) и находится в подразделе, имя которого совпадает с именем области программного модуля. Если вы не можете найти страницу для конкретной интересующей вас функции, то попробуйте воспользоваться встроенным полнотекстовым поиском в правом верхнем углу

  2. Параметры типа ДвоичныеДанные могут быть определены как пути к файлам или URL. Зачастую, для параметров с типом данных ДвоичныеДанные, в примерах кода документации используются URL или пути к файлам на диске. Это допустимое поведение, так как в начале всех функций входящие параметры преобразуются (по возможности) к необходимым типам. В случае с двоичными данными, например, при передаче строки, будет выполнена попытка найти файл на диске, получить его из интернета или преобразовать из Base64

  3. Примеры результатов функций приведены в формате JSON, но в 1С и OS это будут Соответствия. Если в примере результата на странице-описании функции приведен JSON, то в 1С и OneScript это будет Соответствие - т.е. ответ будет сериализован. JSON строкой возвращается только в CLI версии

Структура модулей​

Общие модули проекта бывают двух видов:

  • Служебные
    • OPI_Инструменты
    • OPI_Криптография
  • Модули непосредственной работы с API
    • OPI_Telegram, OPI_VK...
warning

Не рекомендуется использовать методы служебных модулей в других местах вашей конфигурации (если вы собираетесь обновляться до новых версий в дальнейшем). Для сохранения обратной совместимости, количество/назначение параметров и типы возвращаемых значений для методов работы с API не изменяются, но это не применимо к служебным модулям, которые могут изменяться как угодно для оптимизации и дополнения под новые нужды. Если вам необходим функционал из служебных модулей, рекомендуется скопировать его себе отдельно.