- Общее описание
- Выгрузка цен и остатков на сайт из АльфаАвто 6 через WooCommerce API
- Загрузка данных из внешнего ресурса
- Выгрузка документов "Заказ клиента" из ЕРП 2.4
Общее описание
Само решение представляет собой расширение с несколькими справочниками и парой служебных объектов. Разработано на платформе 8.3.14. Основная задача разработки заключалась в том, чтобы сократить время на написание обменов. В текущей версии возможно практически без конфигурирования настроить обмен. Изменения состава полей и конечного JSON пакета так же настраивается в пользовательском режиме.
Пример 1. Выгрузка цен и остатков на сайт из АльфаАвто 6 через WooCommerce API
Задача: Выгружать цены и остатки товаров несколько раз в день. Выгрузка должна происходить только при наличии изменений в остатках и ценах.
Перед началом разработки нужно ознакомиться с API. У WooCommerce API есть подробное описание.
Нас интересует разделы "Update a product" и "Batch update products" (позволяет массово изменять объекты).
В правой части - полное описание JSON пакета для обновления записи о товарах. Для изменения данных на сайте можно отправлять только необходимые поля. Мы будем менять поля "price", "regular_price"и "stock_quantity".
Подключаем расширение. Все объекты располагаются в соответствующей подсистеме. Для начала необходимо настроить подключение к удаленному серверу - раздел "Серверы обмена".
Создаем новый элемент справочника. В текущей версии конфигурации поддерживается только базовая авторизация, но можно дополнить заголовки собственными данными. Иногда для авторизации необходимо указывать API ключ в заголовке.
Для WooAPI есть возможность использовать базовую авторизацию. В этом случае в качестве пользователя необходимо указать пользовательский ключ, а в качестве пароля - секретный ключ.
Основное конфигурирование происходит в справочнике "Ресурсы". Создаем новый элемент и указываем способ формирования - "Выгрузка справочника". Для этого способа формирования доступен параметр "Имя справочника". Заполняем его значением "Номенклатура".
На вкладке «Сопоставление/дополнение полей» можем указать любые поля выгружаемого справочника, а так же имя поля в JSON пакете. Для примера укажем код, артикул и тип номенклатуры. Тип формирования указываем "Поле объекта".
На вкладке "Результат" можем увидеть итоговый JSON пакет. Ссылки автоматически преобразуются в строковый guid, иное представление ссылок будет рассмотрено далее в статье.
При такой настройке будет сформирована выгрузка всего справочника.
Настроим фильтрацию справочника. На текущий момент для способа формирования "Выгрузка справочника" доступен единственный способ фильтрации - через план обмена.
Для регистрации в плане обмена нужно сделать следующее:
- Создать узел в плане обмена "Регистрация изменений (REST клиент)" в пользовательском режиме.
- Перенести нужный объект метаданных из основной конфигурации в расширение.
- Включить новый объект в состав плана обмена "ПС_РегистрацияИзменений".
- Указать объект метаданных в качестве источника для подписки на событие «ПС_РегистрацияКОбменуПереопределяемый».
-
Прописать код регистрации в модуле «ПС_РегистрацияКОбменуСобытияПереопределяемый» в процедуре «ПС_РегистрацияКОбменуПереопределяемыйПриЗаписи».
-
В ресурсе со способом формирования "Выгрузка справочника" отметить флаг "По плану обмена".
Для упрощения в примере будет использована простая регистрация при записи элемента справочника. При необходимости можно регистрировать номенклатуру при проведении нужных документов, например "установка цен номенклатуры", "Реализация товаров и услуг" и т.д.
Далее вся последовательность действий представлена в скриншотах.
Запишем несколько элементов и посмотрим на итоговый JSON пакет на вкладке "Результат".
Для выгрузки цен нам понадобится отбор по типу цен. Для этого перенесем в расширение справочник "Типы цен". И дополним тип у поля: Справочник "Запросы"->Табличная часть "Параметры" -> Поле "ЗначенияПараметра".
Для добавления в JSON цен и остатков будем использовать справочник запросы.
Создаем новый элемент справочника "Запросы". Важные моменты при заполнении элемента при выгрузке справочников:
- Результат должен быть помещен во временную таблицу, имя которой нужно указать в поле "Имя временной таблицы".
- Для отбора можно использовать временную таблицу "ВТИсточник", в которой по умолчанию имеется поле "Ссылка". Также в эту таблицу будут добавлены все поля, указанные на вкладке "Сопоставление / дополнение полей" с типом формирования "Поле объекта" (в нашем случае это поля "Код, Артикул, ТипНоменклатуры"). В случае отбора по плану обмена в этой таблице будут только отобранные элементы.
- Необходимо заполнить все поля в шапке. Список полей должен быть указан через запятую.
Запрос выгрузки остатков:
- Результат помещаем во временную таблицу "ВТТовары". В шапке заполняем поле "Имя временной таблицы" значением "ВТТовары".
- Поля временной таблицы: "Номенклатура" и "stock_quantity". В итоговом пакете нам понадобится только "stock_quantity", поэтому в шапке в поле "Список полей" указываем только "stock_quantity".
- В итоговом запросе мы будем соединять таблицы по полю "Номенклатура", поэтому указываем в шапке поле "Номенклатура". В итоговом запросе соединение всех временных таблиц будет происходить с временной таблицей "ВТИсточник" по полю "Ссылка". В нашем примере ВТИсточник.Ссылка = ВТТовары.Номенклатура.
- Нам нужны остатки только по выгружаемой номенклатуре, поэтому делаем фильтр используя системную таблицу "ВТИсточник".
Далее скриншоты запроса выгрузки цен, где дополнительно реализован отбор по типу цены.
Переходим к нашему ресурсу "Выгрузка товаров". На вкладке "Сопоставление / дополнение полей" оставим только код. Для упрощения будем считать, что id на сайте совпадает с кодом номенклатуры. В реальной интеграции хранение id может быть реализовано, например, дополнительным реквизитом, который так же можно будет выбрать запросом.
Добавим две строки. Тип формирования "Запрос", в поле "Значение" указываем наименования ранее созданных запросов.
Переходим на вкладку "Результат" и проверяем итоговый JSON пакет.
Полученный JSON пакет соответствует пакету из документации. Но для массового изменения данных о номенклатуре в документации описан специальный запрос. Его тело необходимо представить в виде словаря с ключами "create", "update" или "delete", где будут находиться массивы номенклатуры для создания, обновления или удаления соответственно.
Для реализации такого запроса создаем еще один элемент справочника ресурсы. Это будет итоговый элемент, который будет отправлять данные на сервер.
Заполняем поля шапки:
- Сервер
- Адрес
- Тип запроса
Способ формирования не важен. На вкладке "Сопоставление/дополнение полей" добавляем строку:
- Имя поля приемника - "update"
- Тип формирования - Ресурс
- Значение - Наш ранее созданный ресурс "Выгрузка товаров"
Проверяем результат:
Таким образом, мы получили словарь массивов с ключом "update".
На текущем этапе уже можно отправлять данные в ручном режиме.
В составе расширения есть обработка "Тест запроса", через которую можно тестировать отправку и получение данных. Пример работы с ней будет рассмотрен далее.
Для реализации задачи по интеграции необходимо сделать еще две вещи:
- Удалять регистрацию номенклатуры в случае успешной отправки данных.
- Запускать обмен в фоновом режиме.
Для удаления регистрации необходимо корректно обработать успешный ответ от сервера. Для того, чтобы происходила подобная обработка в основном ресурсе включаем флаг "Нужна обработка успешного ответа". Далее в появившемся поле "Имя процедуры успешного ответа" необходимо указать имя процедуры из общего модуля "ПС_ОбработкиКлиентскихЗапросовПереопределяемый".
В модуле определена процедура-заглушка "ПримерФункцииОбработкиУспешногоОтвета" с необходимыми входными параметрами.
Управление перейдет к этой процедуре в случае, если код ответа от сервера будет в интервале [200,300).
В текущей версии в процедуре необходимо определить три параметра:
- ОтправляемыеДанные - тело запроса до сериализации.
- Ресурс - отправляемый ресурс (в нашем примере "Обновление номенклатуры").
- СериализованныйОтвет - сериализованный ответ от сервера.
Логику обработки ответа от сервера разработчик определяет сам в зависимости от получаемых данных. Можно удалить регистрацию всех отправляемых данных из параметра "ОтправляемыеДанные ".
Чаще и, как мне кажется, корректнее брать данные из параметра "СериализованныйОтвет", где в общем случае находятся идентификаторы обработанных объектов. И конкретно по этим объектам можно удалять регистрацию в плане обмена.
Для запуска обмена в фоновом режиме необходимо сделать следующее:
- В основном ресурсе включить флаг "Фоновая выгрузка" (логичнее было назвать "фоновый обмен", потому как фоново можно и загружать и выгружать данные, но с неймингом проблемы не только у этого поля).
- В появившемся поле "Ключ фонового задания" указать строковый идентификатор.
- Сохранить обработку "ПС_ФоновыйОбмен", которая входит в состав расширения, как внешнюю обработку.
- В модуле объекта сохраненной обработки в функции "СведенияОВнешнейОбработке" добавить команду с идентификатором из пункта 2.
- Подключить внешнюю обработку и задать расписание стандартным функционалом БСП.
Пример 2. Загрузка данных из внешнего ресурса
Задача: периодическая загрузка данных из внешнего ресурса. Создание элементов справочника на основании полученного JSON пакета.
Структура JSON пакета:
Начинаем с создания настройки подключения к серверу. Настройка точно такая же, как и в первом примере, поэтому сразу же перейдем к созданию ресурса. Для решения этой задачи будут использованы такие же инструменты, как и в первом примере.
Создаем ресурс. Указываем адрес и тип запроса.
Проверяем работоспособность через обработку "Тест запроса".
Если все успешно, можно приступать к описанию логики обработки запроса.
В ресурсе нужно отметить, флаг "необходима обработка успешного ответа" и указать имя функции, которая должна быть определена в модуле «ПС_ОбработкиКлиентскихЗапросовПереопределяемый».
Как и в первом примере, для того, чтобы управление перешло в эту функцию, код ответа должен быть в интервале [200, 300).
В параметре "СериализованныйОтвет" будут нужные нам данные. Останется только описать логику обработки полученных данных. Фоновый запуск реализуется так же, как и в первом примере.
Пример 3. Выгрузка документов "Заказ клиента" из ЕРП 2.4
Задача: Выгружать часть документов "Заказ клиента" по предоставленному формату.
Сама задача несколько мудреная из-за необходимой структуры JSON. Часть ссылок нужно представлять словарями или строковыми представлениями, еще необходимо дополнять каждый документ массивом номенклатуры. Для решения этой задачи будет рассмотрен практически весь функционал данной конфигурации.
Немного упрощенная структура JSON пакета:
Для упрощения регистрации сделаем в документе "Заказ клиента" два реквизита "ГотовКВыгрузке" и "Выгружен". Настройка подключения к серверу такая же, как в первом примере.
Для начала создадим новый запрос. В отличие от выгрузки справочника нам не нужно помещать результат во временную таблицу и заполнять какие-либо дополнительные поля.
Что будет выведено в последнем запросе пакета, то и попадет в итоговый JSON пакет. Но в примере мы намеренно поместим документы во временную таблицу, потому как менеджер временных таблиц везде один, а далее нам пригодится отбор по документам. Так же сделаем пустое поле "products", чуть позже мы его переопределим.
Теперь создаем новый ресурс. Указываем адрес, тип запроса. Способ формирования - "произвольный запрос". В появившемся поле "Запрос" указываем наш ранее созданный запрос - "Выгрузка товаров (запрос)". Проставим признак "Готов к выгрузке" у нескольких документов и посмотрим результат.
В результате получится два гуида и пустая строка. Начнем с представления ссылок словарем.
Сначала переопределим вывод ссылки на документ. Создаем новый ресурс со способом формирования "Переопределение полей".
На вкладке "Сопоставление/дополнение" добавляем поля, которые нам нужны из ссылки (в данном случае из ссылки на документ "Заказ клиента"). Для того, чтобы представить ссылку строковым представлением, указываем тип формирования поля - "Представление поля объекта".
Вернемся к основному ресурсу. Добавляем строку на вкладке "Сопоставление/дополнение полей". В колонке "Имя поля приемника" указываем поле, которое будем переопределять. В данном случае это "external_source". Тип формирования поля - "Переопределение полей", а в качестве значения - наш ранее созданный ресурс. Проверим результат.
Это уже ближе к необходимому результату. Проделаем то же самое для контрагента.
Теперь все ссылки представлены нужным нам образом.
Еще необходимо вывести строковую константу в JSON в пакет. Для этого используем тип формирования поля "Произвольное поле". В качестве значения указывается нужное нам значение, в данном случае "ORDER"
Переходим к формированию поля "products". Для каждого документа нужно вывести товары из его табличной части. Для оптимизации это нужно будет сделать одним запросом по всем документам.
Создаем новый запрос. Потому как ранее мы создали временную таблицу "ВТОтбор" мы можем с ней соединиться. Обязательно нужно указать поле, по которому будет происходить соединение с основной таблицей (в основной таблице у нас три поля: client, external_source, products). Имя поля соединения должно быть таким же как в основном запросе.
Cоздаем новый ресурс. Способ формирования - произвольный запрос. Выбираем ранее созданный запрос. В этом ресурсе не получится сразу проверить результат, так как временная таблица "ВТОтбор "будет создана в момент формирования основного ресурса.
В основном ресурсе добавляем новую строку на вкладке "Сопоставление/Дополнение".
Значения нужно заполнить следующим образом:
- Имя поля источника - "external_source"
- Имя поля приемника - "Дополнение"
- Значение - наш ранее созданный ресурс "Товары заказа"
Как это работает:
Не смотря на то, что мы и представляем ссылки в виде словарей, само представление в виде словарей происходит на самом последнем этапе сериализации. А все остальное время поле "external_source" является ссылкой. Поэтому мы можем соединить (Товары Заказа).external_source = (Выгрузка заказов).external_source
Типы формирования полей: "Переопределение полей" и "Дополнение" - переопределяют итоговое значение поля. Поэтому такое поле должно быть в основном запросе.
Итоговый результат:
Фоновый обмен настраивается аналогично предыдущим примерам.
В процедуре "успешного ответа" можно проставлять значение реквизита "Выгружен" в "Истина", тогда выгруженные заказы не будут выгружаться повторно. Следует иметь в виду, что пример с реквизитами учебный, вряд ли в работающей системе вы будете создавать реквизиты для регистрации.
Вывод:
Может показаться, что разобраться в подобной системе сложнее, чем написать интеграцию с нуля. Тем не менее на текущий момент с использованием этой конфигурации разработано и введено в эксплуатацию несколько обменов. Скорость разработки каждого следующего обмена сокращалась. А также подобную систему гораздо проще поддерживать и адаптироваться под новые задачи.
Возможно местами код в самой конфигурации может показаться не совсем оптимальным, но потому он и открыт, пожелания к доработке приветствуются.
