Я довольно часто пишу про Открытый пакет интеграций, и большинству данный проект известен как расширение для работы с облачными сервисами на базе платформы 1С:Предприятие. Однако, это лишь одна сторона проекта - самая известная, но не единственная. Поэтому, сегодня я хочу уделить больше внимания другой его части, моей любимой, если быть откровенным - приложению для командной строки OInt CLI, области его применения, решаемым задачам и принципу работы
Зачем нужен OInt CLI ?
Как уже было отмечено ранее, OInt CLI - это программа, приложение для командной строки. Но что оно умеет? Да, собственно, ровно все то же самое, что и оригинальный Открытый пакет интеграций - работать с облачными сервисами по Http. Набор методов OInt CLI и 1С расширения ОПИ практический полностью идентичен: сохранены имена функций и наборы параметров. Просто это работает из консоли и без 1С благодаря OneScript!
В каких ситуациях OInt CLI может быть полезен:
- Когда нужно быстро выполнить какую-либо манипуляцию с облачным сервисом без доступа к 1С
- При тестировании и настройке сервиса для быстрой проверки результатов выполнения различных действий
- Для подбора нужных методов и параметров под работу с 1С расширением ОПИ в дальнейшем
- При автоматизации различных процессов, начиная с одиночных .bat файлов, заканчивая сложным CI/CD
Далее мы перейдем к конкретным примерам, но сначала пару слов про установку OInt CLI
Установка
OInt CLI доступен как на Windows, так и на Linux системах. Для его установки в каждом релизе ОПИ есть набор файлов, состоящий из двух .exe - Windows установщика и универсального исполняемого файла, .rpm пакета для Fedora/CentOS дистрибутивов и .deb пакета для дистрибутивов, основанных на Debian.
Вы можете просто скачать файл, подходящий для используемой вами системы
Как показывает статистика, чаще всего используется Windows версия OInt CLI - она же является самой простой в установке благодаря файлу установщика: Скачал -> Далее...Далее -> Готово
Приложение написано на OneScript, который, в свою очередь, требует .Net Framework 4.8. На всех более-менее современных версиях Windows он будет и так, а на Linux работает через Mono - прописан как зависимость внутри RPM и Deb-пакетов
Также, если вы пользуетесь OneScript и знаете, что такое OPM, то получить OInt CLI даже еще проще: он есть как пакет в OPM под именем oint-cli
opm install oint-cli
После установки одним из доступных способов, OInt CLI должен стать доступен для вызова в командной строке через команду oint (для Windows установщика может потребоваться перезагрузка)
Примеры работы
После установки можно начинать работу. Здесь я приведу несколько примеров решения задач, которые мне кажутся наиболее очевидными
Начнем с простого - отправка отчета о выполнении какого-либо процесса в Telegram. Работать я буду просто в командной строке, но организовать вызов из других инструментов, думаю, не должно вызвать никаких дополнительных трудностей
Так как это первый пример, для начала, просто запустим oint и посмотрим, какой вывод мы на это получим
Это главная страница. На ней есть некоторая информация о программе, а именно версия, структура вызова, список всех доступных библиотеки и универсальные опции, который могут быть использованы для любого другого вызова во время работы. В списке библиотек же мы можем видеть названия всех тех сервисов, что реализованы и в основном расширении ОПИ
Выберем самую первую библиотеку - telegram. Для этого напишем oint telegram и посмотрим на результат
Вызов библиотеки без указания метода возвращает список доступных функций. Для удобства, они дополнительно разделены по видам решаемых задач, которые равны областям в коде ОПИ и разделам документации
Теперь мы можем перейти непосредственно к отправке сообщения в Telegram. Если необходим только текст - выбираем функцию ОтправитьТекстовоеСообщение
При вызове функции без опций, выводится справка по методу и его параметрам. Набор параметров, опять же, соответствует таковым в 1С. Теперь уже отправим сообщение
В переменную %token% я заранее, за кадром, установил токен бота, а переменные %date% и %time% - это стандартные переменные в CMD, содержащие текущую дату и время системы
В качестве идентификатора чата тут выступает имя канала через @, но и числовые ID для отправки в чаты и личные сообщения пользователям также сюда подходят
Если же кроме текста необходимо отправлять еще и некоторый файл (например, какой-нибудь лог), то это будет ненамного сложнее: вместо функции ОтправитьТекстовоеСообщение просто вызывается функция ОтправитьДокумент с дополнительным параметром пути к файлу
В итоге мы получаем такое же сообщение, но уже с файлом. Слишком большой документ таким образом не пошлешь, но это уже ограничение API Telegram, а не самого OInt. Для отправки логов и текстовых файлов с результатами какого-либо процесса вполне подойдет
Теперь посмотрим более комплексный пример - отправка файла в облако
В наборе методов ОПИ есть решения для работы с тремя облачными сервисами: Google Drive, Yandex.Disk и Dropbox. Сразу стоит оговориться, что если подразумевается отправлять небольшие файлы (до 2 ГБ), то подойдет любое из них. При необходимости отправки больших файлов здесь отпадает Yandex.Disk, так как его API не имеет функционала для загрузки частями (т.н. Chunked Uploads)
В качестве примера я выбрал Google Drive, работа с которым позволит нам не только взглянуть на отправку файла, но и разобрать такой момент, как обновление временного токена доступа - с него и начнем
Если в случае с Telegram, который мы рассматривали первым, токен для бота выдается раз и навсегда, то большинство других сервисов токены выдает лишь на определенное время - их необходимо периодически обновлять
Для обновления токена сервиса Google Drive в данном примере, необходимо вызвать функцию ОбновитьТокен из общего набора (библиотеки) google
oint google ОбновитьТокен --id %clientid% --secret %clientsecret% --refresh %refresh%
В нее передается ClientID, ClientSecret и RefreshToken - секретные данные для обновления. Далее, в рамках этого этапа, полученный в ответе JSON необходимо будет сохранить в файл. Для этого в OInt CLI есть универсальный для всех функций параметр --out (его описание можно увидеть на главной странице при вызове oint), в котором указывается путь к файлу для сохранения. Также можно воспользоваться и стандартной конструкцией ">", но тогда файл будет сохранен в кодировке оболочки, а не в UTF-8, как в случае с --out. Это может вызвать проблемы с использованием таких файлов из oint и других утилит на OneScript в дальнейшем
Но JSON ответа - это не чистое значение токена, которое нам необходимо. Для обработки подобных случаев, когда требуется разбор JSON в конечные значения, в составе OInt есть функция РазложитьJSON из набора tools
Вызвать функцию РазложитьJSON можно двумя способами: без указания имени поля JSON - тогда будет выведен весь список доступных полей и значений, где можно найти необходимые, и с указанием имени поля - тогда уже вернется конкретное его значение, которое можно будет куда-нибудь записать и использовать. Вот как это выглядит в нашем примере с ответом сервера по обновлению токена, записанным в newtoken.json
Теперь мы можем использовать новый токен из параметра %token%. Осталось лишь отправить файл на диск
Как вы могли заметить, само описание файла здесь передается в формате JSON: это может быть как непосредственно текст, так и путь к JSON файлу. В случае с прямой передачей текста используются одиночные кавычки, а не двойные
Полный набор команд:
oint google ОбновитьТокен --id %clientid% --secret %clientsecret% --refresh %refresh% --out C:/newtoken.json
oint tools РазложитьJSON --json C:/newtoken.json --enc CP866 --name access_token > token.tmp
set /p token=<token.tmp
oint gdrive ЗагрузитьФайл --token %token% --file C:/log.txt --props "{'MIME':'text/plain','Имя':'log.txt','Родитель':'root'}"
Подытожив
Мы рассмотрели простой случай с отправкой данных в Telegram, а также обновление токена, разбор JSON и передачу JSON параметра в случае с отправкой файла на облачный диск Google Drive. Ничего больше экстраординарного в других методах на данный момент встретить нельзя - принцип схож, просто выбирайте функции под свои конкретные нужды
Информацию по всем методам, также как и в случае с расширением для 1С, можно найти в документации: там есть и примеры вызываемых команд, и соотношение CLI опций с параметрами для 1С и OneScript
Скачать OInt CLI и расширение ОПИ для 1С можно на Github по ссылкам ниже
Также не забывайте ставить звездочку этому и другим открытым репозиториям, если они вам понравилась! Проектам это помогает в развитии, а вам - в отслеживании новостей о выходе новых версий
Спасибо за внимание!
Репозиторий ОПИ: github.com/Bayselonarrend/OpenIntegrations
Последний релиз: github.com/Bayselonarrend/OpenIntegrations/releases/latest
Другие статьи про Открытый пакет интеграций на Инфостарт:
Открытый пакет интеграций для популярных API: Telegram, VK, Viber, Twitter
Работа с Notion API | Обновление Открытого пакета интеграций
Библиотека работы с Яндекс Диском (Open-source)
Открываем свою лавку на платформе VK Market
Библиотека для работы с Google Calendar API (open-source)
Telegram в режиме форума: делаем чаты комфортными
Открытый пакет интеграций для OneScript
Мой GitHub: https://gitub.com/Bayselonarrend OpenYellow: https://openyellow.notion.site Лицензия MIT: https://mit-license.org
