Обработчики 1С (разработчику)
В статье рассмотрены переменные и методы, доступные в контексте выполнения для разных типов обработчиков 1С, а также инструменты Платформы для создания и отладки кода.
Общие переменные и методы
Переменные и методы, которые доступны в обоих направлениях интеграции (Из Platform и В Platform).
Переменная СостояниеСообщения
Для управления жизненным циклом сообщения в контексте выполнения обработчиков Из Platform и В Platform доступна переменная СостояниеСообщения. Чтобы присвоить переменной значение, необходимо указать в коде полный путь к нему – например, Перечисления.сшпСтатусыСообщений.ОжиданиеОбработки.
Доступны следующие состояния:
Обработано:
Устанавливается автоматически. Система регистрирует сообщение с событием Receive, если сообщение отправлялось из 1С, и с событием Send, если сообщение приходило в 1С. Уровень логирования событий – Info.
ОшибкаОбработки:
Устанавливается автоматически в случае исключения при выполнении кода обработчика. Система помещает сообщение в архив с событием Receive, если сообщение отправлялось из 1С, и с событием Send, если сообщение приходило в 1С. Уровень логирования событий – Info.
НеВалидно:
Устанавливается автоматически в случае некорректного формата сообщения, либо программно в теле обработчика. Система помещает сообщение в архив с событием Receive, если сообщение отправлялось из 1С, и с событием Send, если сообщение приходило в 1С. Уровень логирования событий – Info.
ОтсутствуетОбработчик:
Устанавливается автоматически, если система не смогла подобрать обработчик для сообщения. Система помещает сообщение в архив с событием Receive, если сообщение отправлялось из 1С, и с событием Send, если сообщение приходило в 1С.
ОбработкаОтменена:
Устанавливается программно в теле обработчика. Позволяет отменить обработку текущего сообщения. Будет ли система регистрировать событие и сохранять сообщение в архив – зависит от значения параметра Регистрировать квитанцию об отмене обработки из 1C в конфигурации Внешней системы 1С.
ОжиданиеОбработки:
Устанавливается программно в теле обработчика. Позволяет отложить обработку текущего сообщения на интервал, указанный в переменной Задержка. Сообщение помещается в очередь, а не в архив. Система возвращает сообщение в обработку через интервал, указанный в переменной Задержка. Каждый раз, когда сообщение попадает в обработку, система регистрирует событие Delay. Уровень логирования событий – Info.
Пример использования переменной СостояниеСообщения:
Если ОбъектОбработки.РеквизитБулево тогда
СостояниеСообщения = Перечисления.сшпСтатусыСообщений.ОбработкаОтменена;
КонецЕсли;
Методы для логирования
Методы логирования дают возможность отправлять пользовательские сообщения в Журнал Внешней системы. Также сообщения будут записываться в Журнал 1С – при условии, что уровень логирования во Внешней системе такой же или выше.
Для логирования доступны следующие процедуры (тип входного параметра Текст – Cтрока):
СобытиеФатальнаяОшибка(Текст)
СобытиеОшибка(Текст)
СобытиеПредупреждение(Текст)
СобытиеИнформация(Текст)
СобытиеОтладка(Текст)
СобытиеПодробности(Текст)
Методы для управления задержкой
Для управления задержкой доступны следующие процедуры:
Ожидание(Задержка)
ОжиданиеМСек(Задержка)
Внимание
Не рекомендуется использовать устаревшие методы сшпОбщегоНазначения.Ожидание() и сшпОбщегоНазначения.ОжиданиеМСек(). При их вызове фактическое время ожидания может превысить значение, переданное в параметре Задержка.
Вызов обработчика-функции
В коде обработчиков доступен вызов функций 1С – еще одного типа обработчиков.
Чтобы вызвать функцию из обработчика или другой функции, необходимо прописать следующий код:
ВыполнитьФункцию(ИмяФункции, параметры через запятую)
В случае вызова функции из бизнес-процесса необходимо передать в переменную Результат тело ответного сообщения:
Результат =
сшпОбщегоНазначения.ПреобразоватьСтруктуруПоФормату(Перечисления.сшпФорматыСообщений.JSON, Данные);
Обработчики Из Platform
Примечание
Кроме перечисленных ниже методов для обработчиков Из Platform доступны общие методы: Логирование, Управление задержкой, Вызов обработчика-функции и переменная СостояниеСообщения.
Переменные (Из Platform)
Для обработчиков направления интеграции Из Platform в контексте выполнения доступны следующие переменные:
Идентификатор: идентификатор передаваемого сообщения. Соответствует Идентификатору в очереди входящих сообщений.
ДатаРегистрации: дата регистрации объекта в очереди входящих сообщений, тип Дата.
Задержка: количество секунд, на которое откладывается обработка сообщения, тип Число. Позволяет отложить обработку сообщения на указанный период. Для корректной работы необходимо присвоить переменной СостояниеСообщения значение ОжиданиеОбработки.
ТелоСообщения: тело пакета.
КоличествоПопытокОжидания: счетчик количества переходов сообщения в статус ожидания. Увеличивается на единицу каждый раз, когда переменной СостояниеСообщения присваивается значение ОжиданиеОбработки.
Методы для получения свойств сообщения
Для получения свойств сообщения в контексте выполнения обработчиков Из Platform доступен набор функций, которые возвращают служебные метаданные и параметры сообщения:
Для части методов можно использовать как русское, так и английское наименование.
СвойствоСообщения(ИмяСвойства): возвращает значение конкретного свойства сообщения по имени свойства.
ПолучитьПараметрыСообщенияСтруктурой(): возвращает свойства и параметры сообщения в виде объекта 1С Структура.
ПолучитьПараметрыСообщенияСоответствием(): возвращает свойства и параметры сообщения в виде объекта 1С Соответствие.
РазмерСообщения() / GetMessageSize(): возвращает объем сообщения в байтах.
ИсточникСообщения() / GetSource(): возвращает имя внешней системы, которая отправила это сообщение (InitialSource).
ИдентификаторКорреляцииСообщения() / GetCorrelationId(): возвращает идентификатор корреляции сообщения CorrelationId.
ИдентификаторКорреляцииПлатформыСообщения() / GetPlatformCorrelationId(): возвращает внутренний идентификатор корреляции PlatformCorrelationId.
ТипДанныхСообщения() / GetDataType(): возвращает свойство сообщения OriginalSystemDataType.
КоличествоПопытокОжидания() / GetDelayCount(): возвращает количество повторных попыток обработки сообщения.
ИдентификаторСообщения() / GetId(): возвращает идентификатор сообщения, которое обрабатывается в текущий момент.
ТипСообщения() / GetType(): возвращает значение MessageDatagram. Доступен также для обработчиков В Platform.
ВремяСозданияСообщения() / GetCreationTime(): возвращает дату и время создания сообщения.
Доступные методы для работы с телом из компоненты
Входные параметры для этих методов одинаковые:
jsonPath (string): путь, по которому необходимо выполнить проверку.
isFail (integer): требуется ли выводить сообщение при возникновении ошибки. Возможные значения:
1: выводить сообщение об ошибке.
0: не выводить сообщение об ошибке.
Для работы с телом в контексте выполнения обработчиков Из Platform доступны следующие методы:
int result = Компонента.GetJSONPathExists(string jsonPath, int isFail, out int isExist) – возвращает 0 или 1; указывает, существует ли указанный путь в теле принятого сообщения.
int result = Компонента.GetJSONPathIsArray(string jsonPath, int isFail, out int pathIsArray) – возвращает 0 или 1; указывает, является ли значение по указанному пути в теле сообщения массивом.
int result = Компонента.GetJSONArraySize(string jsonPath, int isFail, out int size) – возвращает 0 или 1; возвращает размер массива по указанному пути в теле принятого сообщения.
var result = Компонента.GetJSONElementValue(string jsonPath, int isFail) – возвращает значение из тела принятого сообщения по указанному пути. При использовании этого метода необходимо указывать путь до простых элементов – строк, чисел, булевых значений, пустых значений (не поддерживается работа с объектами и массивами).
Метод получения реквизита из структуры сообщения
Для получения значения реквизита из структуры сообщения используется метод GetJSONElementValue, доступный при обращении к Компоненте.
Пример:
Допустим, что записи в системе ищутся по коду, для этого в коде обработчика создается переменная, в которую записывается значение реквизита Код из JSON структуры сообщения, которое необходимо передать из Platform в систему-получатель.
ЗначениеДляПоиска = Компонента.GetJSONElementValue("Код", 1);
Затем по данному значению ищется элемент в справочнике:
новыйОбъект = Справочники.ИмяСправочника.НайтиПоКоду(ЗначениеДляПоиска);
Это необходимо, чтобы присвоить значения реквизитам найденного элемента либо создать новый элемент с такими значениями. Для этого также можно использовать метод GetJSONElementValue:
Присвоение значения реквизиту Наименование
новыйОбъект.Наименование = Компонента.GetJSONElementValue("Наименование", 1);
Метод для добавления объекта в очередь исходящих сообщений
Для добавления объекта в очередь исходящих сообщений доступен метод:
сшпПользовательскиеМетоды.ПоместитьВОчередьИсходящих
Функция сшпПользовательскиеМетоды.ПоместитьВОчередьИсходящих(
Знач ТипОбъекта,
Знач Объект,
Знач ЭтоУдаление = Ложь
) Экспорт
Где:
ТипОбъекта – наименование типа объекта, помещаемого в очередь.
Объект – сущность для выполнения кода обработчика.
ЭтоУдаление – признак удаления объекта.
Возвращаемое значение:
Boolean – результат выполнения метода.
Если параметр ЭтоУдаление установлен в Истина, то объект сериализуется при помещении в очередь и десериализуется в ОбъектОбработки при выполнении обработчика.
Пример использования:
Если НЕ сшпПользовательскиеМетоды.ПоместитьВОчередьИсходящих(
"Справочник.Контрагенты",
Справочники.Контрагенты.НайтиПоНаименованию("ООО Прогресс"),
Истина
) Тогда
ВызватьИсключение "Не удалось поместить объект в очередь исходящих сообщений";
КонецЕсли;
Обработчики В Platform
Примечание
Кроме перечисленных ниже методов для обработчиков В Platform доступны общие методы: Логирование, Управление задержкой, Вызов обработчика-функции и переменная СостояниеСообщения.
Переменные (В Platform)
Для обработчиков направления интеграции В Platform в контексте выполнения доступны следующие переменные:
ОбъектОбработки: исходный объект 1С, который выгружается в текущий момент. Используется в качестве источника данных для формирования тела исходящего сообщения. Тип данных переменной ОбъектОбработки зависит от настроек в информационной базе 1С (метода хранения, события регистрации, типа объекта метаданных):
Если в настройках 1С выбран метод хранения По ссылке и произошло событие ПриЗаписи:
В Регистрах у переменной будет тип Отбор.
В Ссылочных типах (Справочники, Документы) у переменной будет тип Ссылка.
Если в настройках 1С выбран метод хранения Сериализация и произошло событие ПриЗаписи:
У переменной будет тип Объект XDTO.
Если в настройках 1С выбран метод хранения Сериализация и произошло событие ПередУдалением:
В Регистрах событие не регистрируется.
В Ссылочных типах (Справочники, Документы) у переменной будет тип Объект XDTO.
Идентификатор: идентификатор передаваемого сообщения. Соответствует Идентификатору в очереди исходящих сообщений.
ИдентификаторСобытия: идентификатор события.
ТипОбъекта: наименование типа объекта 1С, для которого выполняется обработчик. Например,
Справочник.Контрагенты.ФорматСообщения: формат отправляемого сообщения. Доступны форматы JSON и XML. Чтобы присвоить переменной значение, необходимо указать в коде полный путь к нему – например,
Перечисления.сшпФорматыСообщений.JSON.МетодХранения: метод хранения сообщения. Доступны методы ПоСсылке и Сериализация. Чтобы присвоить переменной значение, необходимо указать в коде полный путь к нему – например,
Перечисления.МетодХранения.ПоСсылке.ОбъектСобытия: переменная, в которой может храниться любое значение (структура или сериализованный объект). Используется в коде обработчика в качестве источника дополнительных данных о событии, если необходимых сведений нет внутри переменной ОбъектОбработки.
ДатаРегистрации: дата регистрации объекта в очереди исходящих сообщений, тип Дата.
Задержка: количество секунд, на которое откладывается обработка сообщения, тип Число. Позволяет отложить обработку сообщения на указанный период. Для корректной работы необходимо присвоить переменной СостояниеСообщения значение ОжиданиеОбработки.
ЭтоУдаление: признак полного удаления объекта интеграции, тип Булево.
СсылкаНаОбъект: ссылка на объект метаданных, для которого в текущий момент выполняется код обработчика.
РезультатОбработки: структура пакета, который будет выгружен из 1С. В ее свойство Body записывается сформированное тело сообщения.
Преобразование данных из системы в структуру сообщения для отправки
При написании кода обработчика В Platform необходимо получать данные из системы и преобразовывать их в структуру сообщения для отправки. Реализуется следующими способами:
Через объектную модель
Через запрос
В первом случае используется переменная ОбъектОбработки, значения которой инициализируются подсистемой Datareon при выгрузке из 1С. Для составления структуры сообщения используется переменная РезультатОбработки, в которую записываются данные в нужном формате. Для этого используется переменная ФорматСообщения:
ФорматСообщения = Перечисления.сшпФорматыСообщений.JSON;
Затем создается структура, в которую записываются данные из системы с использованием переменной ОбъектОбработки:
Данные = Новый Структура;
Данные.Вставить("Наименование", ОбъектОбработки.Наименование);
Данные.Вставить("РазрешенаПродажа", ОбъектОбработки.РазрешенаПродажа);
Данные.Вставить(... ...
Далее эта структура записывается в РезультатОбработки для задания тела сообщения:
РезультатОбработки.Body = сшпОбщегоНазначения.ПреобразоватьСтруктуруПоФормату(ФорматСообщения, Данные);
где Данные – это структура, а ФорматСообщения – это значение перечисления сшпФорматыСообщений.
Метод сшпОбщегоНазначения.ПреобразоватьСтруктуруПоФормату(Формат, Данные) – используется для преобразования структуры данных к указанному формату. Например, если ФорматСообщения JSON, структура будет преобразована в JSON-представление объекта.
Итоговый текст кода обработчика:
ФорматСообщения = Перечисления.сшпФорматыСообщений.JSON;
Данные = Новый Структура;
Данные.Вставить("Наименование", ОбъектОбработки.Наименование);
Данные.Вставить("Код", ОбъектОбработки.Код);
Данные.Вставить("РазрешенаПродажа", ОбъектОбработки.РазрешенаПродажа);
Данные.Вставить("ТестовыйОбщийРеквизит1",
ОбъектОбработки.ТестовыйОбщийРеквизит1);
РезультатОбработки.Body =
сшпОбщегоНазначения.ПреобразоватьСтруктуруПоФормату(ФорматСообщения, Данные);
Аналог объектной модели через запрос в коде обработчика. Пример кода:
Запрос = Новый Запрос; Запрос.Текст =
"ВЫБРАТЬ
| Продукты.Наименование КАК Наименование,
| Продукты.Код КАК Код,
| Продукты.РазрешенаПродажа КАК РазрешенаПродажа,
| Продукты.ТестовыйОбщийРеквизит1 КАК ТестовыйОбщийРеквизит1
|ИЗ
| Справочник.Продукты КАК Продукты
| ГДЕ
| Продукты.Ссылка = &Ссылка";
Запрос.УстановитьПараметр("Ссылка", ОбъектОбработки.Ссылка);
РезультатЗапроса = Запрос.Выполнить();
ВыборкаДетальныеЗаписи = РезультатЗапроса.Выбрать();
ВыборкаДетальныеЗаписи.Следующий();
Данные = Новый Структура;
Данные.Вставить("Наименование", ВыборкаДетальныеЗаписи.Наименование);
Данные.Вставить("Код", ВыборкаДетальныеЗаписи.Код);
Данные.Вставить("РазрешенаПродажа",
ВыборкаДетальныеЗаписи.РазрешенаПродажа);
Данные.Вставить("ТестовыйОбщийРеквизит1",
ВыборкаДетальныеЗаписи.ТестовыйОбщийРеквизит1);
РезультатОбработки.Body =
сшпОбщегоНазначения.ПреобразоватьСтруктуруПоФормату(ФорматСообщения, Данные);
Вместо переменной ОбъектОбработки в коде объявляется переменная ВыборкаДетальныеЗаписи, в которую записываются результаты запроса к базе. Последняя часть кода практически идентична объектной модели.
Метод для получения свойств сообщения
Для получения свойств сообщения в контексте выполнения обработчиков В Platform доступен метод:
ТипСообщения() / GetType(): возвращает значение MessageDatagram. Доступен также для обработчиков Из Platform.
Метод для установки свойств сообщения
Для установки свойств сообщения в контексте выполнения обработчиков В Platform доступен метод:
УстановитьСвойствоСообщения(ИмяСвойства, ЗначениеСвойства)
Обработчики-функции
Для обработчиков-функций доступны общие методы: Логирование, Управление задержкой, Вызов обработчика-функции.
Интерфейс работы с кодом обработчиков
Отображение изменений кода
При редактировании кода можно отслеживать изменения в сравнении с оригинальным кодом обработчика (до их сохранения). Для этого установите флаг Показать изменения. В результате в левой части рабочей области отобразится оригинал кода, в правой части – отредактированный код.
Отладка кода
Режим отладки кода обработчиков 1С представляет собой имитацию пошаговой обработки и позволяет найти ошибки в коде без использования инструментов разработки 1С. В настоящее время режим отладки доступен для обработчиков Из Platform и В Platform. Поддержка для обработчиков-функций планируется в следующих версиях.
После включения режима отладки система не останавливается на первой строчке кода, как это бывает при обычной отладке. Процесс происходит следующим образом:
Платформа отправляет пакет в 1С. 1С выполняет код в фоновом режиме.
Пока код выполняется в 1С, модуль Datareon отслеживает и фиксирует изменения: как только переменной присваивается значение, модуль записывает это событие как отдельный шаг.
Платформа получает от 1С результат выполнения кода и открывает окно отладки.
В окне отладки доступно переключение между шагами. При переключении на следующий или предыдущий шаг в окне переменных отображаются те значения, которые были актуальны на этом шаге в момент фонового выполнения кода.
В процессе отладки во внешнюю систему 1С отправляются следующие данные:
Для направления Из Platform: сообщение с кодом обработчика и JSON-тело отладочного сообщения.
Для направления В Platform: сообщение с кодом обработчика, параметры обмена и специальный поисковый запрос 1С для выбора необходимого объекта из базы 1С.
Чтобы перейти в режим отладки, нажмите на кнопку Войти в режим отладки либо горячую клавишу F5.
Чтобы установить точки останова, нажмите на номера выбранных строк кода. Затем нажмите кнопку Начать отладку либо горячую клавишу F5.
Для перемещения по коду в режиме отладки используйте клавиши-стрелки либо горячие клавиши:
F10: следующий шаг.
F9: предыдущий шаг.
F5: продолжить – дойти до следующей точки останова или до конца кода, если точек останова нет.
В нижней части рабочей области будут отображаться данные, которые заполняются во время отладки.
Для завершения отладки нажмите кнопку X (выйти из режима отладки).
Особенности отладки кода обработчиков Из Platform
Для отладки обработчиков Из Platform доступно использование отладочного сообщения. Чтобы его настроить, нажмите кнопку Отладочное сообщение. Откроется окно с настройками отладочного сообщения.
Процесс отладки зависит от наличия добавленного в обработчик типа данных (или внешнего типа данных).
Если в обработчике на вкладке Из Platform добавлен тип данных (или внешний тип данных), то структура этого типа данных определяет структуру отладочного сообщения. В таком случае значение каждого поля отладочного сообщения возможно указать в таблице в режиме Структура.
Для перехода в этот режим активируйте переключатель в правом верхнем углу окна Отладочное сообщение:
Если в обработчике на вкладке Из Platform не добавлен тип данных, то отладочное сообщение возможно отредактировать только в режиме Произвольное тело сообщения в формате JSON. Для перехода в этот режим деактивируйте переключатель в правом верхнем углу окна Отладочное сообщение:
Внимание
При переключении между режимами внесенные изменения не сохраняются – значения по умолчанию пустые.
Особенности отладки кода обработчиков В Platform
Обработчики В Platform реагируют на изменение элементов объекта конфигурации базы 1С, который указан в поле Имя таблицы. Этот объект доступен в коде обработчика В Platform через переменную ОбъектОбработки (cм. раздел Обработчики В Platform).
Для осуществления отладки кода необходимо выбрать элемент объекта конфигурации базы 1С, который будет использоваться в качестве переменной ОбъектОбработки. Для этого нажмите кнопку Выбор значения для переменной:
Откроется окно выбора значения:
Варианты выбора объекта:
Первый элемент из: будет выбран элемент запросом 1С (subscriptionObject – объект в поле Имя таблицы обработчика):
ВЫБРАТЬ ПЕРВЫЕ 1 Ссылка ИЗ subscriptionObject
С помощью запроса 1С: откроется форма редактирования запроса 1С.
С помощью произвольного кода 1С: откроется форма редактирования произвольного кода 1С.
Примечание
Если элемент объекта конфигурации не указан в качестве переменной ОбъектОбработки, то при запуске отладки будет выбран вариант Первый элемент из.
Результат выполнения кода обработчика будет отображен в первой строке панели результатов и переменных отладки. Переменные ОбъектОбработки и РезультатОбработки будут отображены в первых строках списка переменных отладки.