Rest 1с создать документ
Обновлено: 04.07.2024
Начиная с версии 8.3.5 1С Предприятие умеет генерировать REST интерфейс для всей конфигурации, используя протокол OData. Это значит, что стороннее приложение может получить доступ ко всей базе 1С буквально за пару кликов.
Базы данных, которые размещаются на Платформе42, поддерживаются автоматическим REST-сервисом по протоколу OData версии 3.0. И мы подготовили для вас большую инструкцию – знакомство с OData. Чтобы не пугать вас «простыней», мы разбили ее на 11 блоков. В этой статье вы найдете краткие обзоры блоков и ссылки на подробную информацию.
Возможности и настройка
Из этой инструкции вы получите общее представление об интерфейсе OData. Тут мы рассказываем об основных возможностях протокола и о том, как настроить автоматический REST-сервис для запроса и обновления данных. Если хотите познакомиться и узнать, какие задачи можно решить при помощи OData – вам сюда.
Общие принципы работы
Здесь мы разбираем специальную терминологию OData. Рассмотрим в отдельности каждый термин из тех, которыми будем оперировать в дальнейшем, узнаем, как выполнить обращение к стандартному интерфейсу OData и подробно разберем верный URL-запрос.
Представление данных
В этой инструкции посмотрим, в каком виде стандартный интерфейс OData возвращает данные, и взглянем на соответствие между типом данных «1С:Предприятия» и типом OData. И отдельно разберем различные суффиксы, на которые могут оканчиваться имена свойств.
Правила формирования имени ресурса
Из этого текста вы узнаете, по какому принципу формируется идентификатор имени ресурса, к каким объектам можно получить доступ при помощи стандартного интерфейса OData и как уточняется имя ресурса при помощи суффикса. Возможные виды суффиксов тоже разберем.
Правила формирования условия отбора
В данном разделе мы приводим информации по различным способам формирования отбора получаемых данных, которые используются в стандартном интерфейсе OData системы «1С:Предприятие». Инструкция большая и детальная, советуем ознакомиться «с чувством, с толком, с расстановкой».
Параметры запроса
Здесь рассматриваем четыре основных параметра запроса: $count, $inlinecount, $orderby и $expand. Узнаем, что они позволяют сделать, как их правильно использовать и какие подводные камни могут встретиться на пути погружения в тему.
Способы получения описания стандартного интерфейса OData
Рассказываем при помощи каких GET-запросов можно получить сокращенное и полное описания стандартного интерфейса OData. Расскажем, каким образом формировать параметр $format при выполнении запроса, если данные получены в формате json.
Способы получения данных
А в этой инструкции расскажем, как получать и списки сущностей, и сами сущности. Эти способы получения данных отличаются URL, по которому происходит обращение к данным. Вы узнаете, чем отличается URL набора сущностей от канонического URL экземпляра сущности.
Выполнение функций и действий
Посмотрим, как формируется URL ресурса, если с сущностью или с набором сущностей связана функция (например, работа с виртуальными таблицами регистров выполняется именно через функции).
Ошибочные ситуации
Вот мы и подошли к самому интересному – к кодам ошибок, их описанию. Посмотрим, как происходит информирование об ошибках со стороны клиентского приложения и об ошибках со стороны сервера, какие коды назначаются и что с этим делать.
Примеры типовых операций
И немного практики напоследок. Рассмотрим несколько типовых операций в их практическом применении. Пошагово разберем работу с одним объектом, работу с планами обмена и другие вещи, с которыми вам наверняка придется столкнуться.
Чтобы иметь полное представление о стандартном интерфейсе OData, ознакомьтесь со всеми представленными выше инструкциями. Или сохраняйте в закладки, чтобы обращаться к этому тексту по мере необходимости.
oData одним из последних появился в инструментах интеграции поддерживаемых платформой 1С. В данной статье хотел бы показать пример его использования. О преимуществах и недостатках oData предлагаю поделиться в комментариях исходя из реального опыта использования.
Цель публикации. Дать разработчикам простой инструментарий обмена между идентичными конфигурациями.
Что делает обработка простым языком.
Итак, задача в которой я решил использовать REST-сервис (oData) был обмен документами идентичных конфигураций. В решении есть обработка реквизитов присущих только документам, с которыми мне пришлось работать, но большая часть реквизитов заполняется по универсальным правилам.
Обмен состоит из двух частей:
- Часть. Получение с сервера из регистра сведений документов, запись их на клиенте, очистка записей регистра сведений сервера.
- Часть. Отправка с клиента на сервер документов. Регистр присутствует и здесь, но т.к. oData никак не участвует в его обработке, то описывать его не буду.
Резюмируя, методы работы с oData в нашем решении, мы рассмотрим:
А) Получение данных из регистра по отбору измерений.
Б) Обработка полученного JSON и запись документов.
В) Удаление записи регистра сведений по ключевым измерениям.
Г) Формирование тела запроса для записи документов на сервере.
Д) Перезапись документа, если он уже есть на сервере.
Что делает обработка (ближе к коду):
Небольшая вводная перед кодом.
Про установку Интернет-сервера (Apache, или IIS) есть много статей. Публикация базы делается через одну кнопку в меню Администрирование:
И установкой флага «Публиковать стандартный интерфейс OData»:
Если у вас не пионерская платформа по использованию интерфейса oData, то нужно включить доступ на объекты базы-сервера.
Так же можно просмотреть объекты, на которые открыт доступ:
Получение данных
Первая процедура «Обработать Регистр» (Листинг 1.) получает уникальные идентификаторы нужных нам объектов.
В Адресе запроса регистр пишем, как он называется в конфигураторе, например «ЦеныВалют» после слова «InformationRegister_», это будет выглядеть так: InformationRegister_ЦеныВалют. Обращение на чтение регистра происходит с помощью Get-запроса, поэтому все передается в параметрах и может быть записано одной строкой в браузере. В частности, наш запрос можно записать строкой:
localhost/server_odata/odata/standard.odata/InformationRegister_<Ваш регистр>?$filter=<Измерение регистра> eq '<Значение>'&$format=json
В данном примере мы используем фильтр по измерению регистра, оно записывается как в конфигураторе, со значением, указанном в апострофах, это такие запятые 'сверху'. Если тип измерения – перечисление, то записываем его как в конфигураторе. Например, «filter=СтавкаНДС eq 'БезНДС'». Слово «eq» обозначает равенство.
Далее преобразуем его в массив соответствий и обращением к нужному нам измерению (Объект), получаем УИД объекта, который необходимо получить.
Далее идет процедура «ПолучитьИОбработатьСсылку(СсылкаУИД)», которая с помощью УИД получает все данные нашего объекта бит_ЗаявкаНаРасходованиеСредств. В данном случае мы используем канонический запрос с использованием GUID, который получает конкретный объект. Запрос такой:
Обращаю ваше внимание на то, что в процедуре «Обработать Регистр» мы использовали функцию «ПрочитатьJSON» без параметров «"ФункцияВостановленияЧтения",ЭтаФорма,,Реквизиты». Связано это с тем, что в первой функции мы не преобразовывали данные из JSON и получали УИД в виде строки. В процедуре «ПолучитьИОбработатьСсылку(СсылкаУИД)» мы уже работаем с ссылкой.
Далее идет создание и заполнение документа. Для удобства преобразовал полученное из JSON соответствие в структуру, предварительно удалив из него строку с ключом "odata.metadata". Код процедуры преобразования «ПолучитьСтруктуруИзСоответствия» взял из Статьи не меняя.
Отправка данных
Для отправки данных используется процедура «ЗаписатьСписаниеНаСервере». (Листинг 2)
Суть процедуры состоит в том, что мы пытаемся создать новый документ на сервере, если этого не удается, пытаемся перезаписать имеющийся.
Для начала нам нужно подготовить данные, которые мы будем передавать на сервер. Формат тот же JSON. Процедура формирования данных для отправки обратно их получению. Сначала создаем соответствие из необходимых реквизитов с нужными значениями. Откуда же взять имена ключей соответствия? Да оттуда же. Из прямого обращения к oData, например из строки браузера. Хоть мы и условились, что базы идентичны, все-таки, рекомендую получать структуру данных из базы сервера. Запрос нам уже знаком: «localhost/server_odata/odata/standard.odata/Document_СписаниеСРасчетногоСчета(guid'<СсылкаУИД>')?$format=application/json» Подставляем какой-нибудь из имеющихся УИДов базы сервера и видим имена. Секрет в том, что большая часть из них совпадают с именами реквизитов в конфигураторе. То есть, придумывать ключи и прописывать их в большинстве случаев не предется. В этом большой плюс и универсальность данных механизмов. Все описанные процедуры могут быть использованы для других объектов базы с небольшими изменениями. Но изменения все же есть.
Рассмотрим процедуру «ПолучитьСоответсвиеДокумента».
Первое, что опишем «в рукопашную» - это реквизит «Контрагент». Дело в том, что контрагент имеет составной тип, поэтому необходимо передавать информацию о типе. Так как в нашем случае Контрагент всегда имеет тип контрагент, то тип его «захардкодим»:
, значение этого параметра можно взять все из того же результата запроса к элементу справочника базы сервера.
Само значение контрагента так же передается УИДом, но в ключе не пишем префикс «_Key».
Заполнение стандартных реквизитов происходит в функции «СоздатьОписанияОбязательнихРеквизитовДокумента» взятой из Статьи без изменений.
Далее создаются три списка значений для дальнейшей обработки:
- СписокСсылок. Из него будут обрабатываться реквизиты ссылочного типа.
- СписокПеречисленией. Из него будут обрабатываться перечисления.
- СписокИсключений. Те реквизиты, которые не будут обрабатываться.
Примечание. Эти списки заполняются как для реквизитов документа, так и для реквизитов табличных частей.
Далее в процедуре «СоздатьОписанияДополнительнихРеквизитов» мы заполняем все оставшиеся реквизиты документа.
В процедуре в цикле обходятся метаданные документа. В отдельные процедуры вынесено заполнение перечислений, хотя, если сделать с ними несколько «приседаний», то, можно и их сделать универсальными.
Процедура «СоздатьОписанияТабличныхЧастей» чуть посложнее, тем, что надо обходить табличные части по отдельности и не забывать про номер строки, но принцип тот же.
Примечание. Метод Записать (Put) отрабатывает, но он не записывает реквизиты, которые были пустыми. Узнал об этом опытным путем. На сервере ставил точки останова в процедурах ПриЗаписи и ПередЗаписью. В процедуре ПередЗаписью данные были, а в процедуре ПриЗаписи – уже нет.
Обращаю внимание на строку заголовка «Заголовки.Вставить("1C_OData-DataLoadMode", Истина);». Это строка переводит флаг «ОбменДанными.Загрузка» в значение «Истина»
Вместо заключения. В чем преимущества oData. В чем недостатки (мое незнание возможностей, или ограничения сервиса)
Недостатки. Нельзя организовать сложные запросы на стороне сервера. Можно получать выборку одной таблицы с разными отборами. Нельзя написать в одном запросе имитацию соединения таблиц. Но есть вариант получить из одной таблицы по заданным отборам нужные записи и уже используя их в качестве отбора получить выборку из другой таблицы. Что на мой взгляд выглядит несколько громоздко и неоправданно. Но как вариант имеет место быть, если, например, нельзя менять конфигурацию сервера.
P.S. В качестве примера прикрепил обработку скачивания заявки с сервера и создания документа на клиенте по УИДу. Переделал под типовую файловую демо-базу.
То же самое с создание документа на стороне сервера не удалось. Ошибка на сервере в процедуре "ОбработкаЗаполнения" без расшифровки. К отладке подключиться на сервере не смог. Возможно из-за того, что база файловая. Поэтому выкладываю как есть. Если нужен строительный материал, берите.
Тестировал на: 1С:Предприятие 8.3 (8.3.16.1148)
Бухгалтерия предприятия КОРП + БИТ.ФИНАНС 3.0 (3.0.43.240/3.1.26.5)
Исходник работал на измененной: Бухгалтерия предприятия КОРП + БИТ.ФИНАНС 3.0 (3.0.69.35/3.1.41.3)
Итак, начнем сначала.
Что такое REST и зачем он нужен
REST (REpresentation State Transfer) подход является одним из наиболее популярных подходов, использующихся для реализации web-сервисов в Интернете. REST web-сервисы являются более легковесными альтернативами SOAP веб-сервисам.
REST с технической точки зрения не является ни технологией, ни стандартом. Это всего лишь подход, если можно так сказать, набор принципов, которые помогают реализовать "правильный" web-сервис. Под "правильным" здесь понимается масштабируемый, безопасный, надежный, легкий в использовании и т. д.
REST определяет следующие принципы построения web-сервисов:
Преимуществами REST подхода являются:
Недостатки REST'а являются продолжением его достоинств:
Протокол, который основывается на принципах REST, является RESTful протоколом. Два наиболее популярных типа RESTful протоколов - это JSON (JavaScript Object Notation) и POX (Plain Old XML). JSON использует для кодирования данных JavaScript и в основном применяется в Ajax (Asynchronous JavaScript and XML) клиентах для обмена данными с сервером. Поскольку Ajax клиенты работают в браузере, который понимает JavaScript, то использование JavaScript позволяет сэкономить как на объеме передаваемых данных, так и на времени разбора данных. Однако использование JSON в других клиентах проблематично, т. к. клиенты, как правило, не поддерживают JavaScript.
POX использует для кодирования данных XML и поэтому может использоваться практически везде.
REST в 1С
Использовать стандартный интерфейс OData прикладного решения просто:
По умолчанию после публикации объекты конфигурации не доступны. Прежде чем обращаться к ним, необходимо разрешить доступ, например с помощью типовой обработки "Настройка автоматического REST сервиса". В обработке можно задать отдельного пользователя REST сервиса:
и указать доступные объекты конфигурации:
"odata/standard.odata" - "магическое" слово, означающее доступ через odata интерфейс
"Catalog_Контрагенты" - состоит из указания на тип объекта "Catalog" - справочник и типа справочника
"select" - оператор чтения данных, после него через "=" идет описание считываемых данных, в данном случае это "Ref_Key" - уникальный идентификатор
"format=json" - задает формат представления считываемых данных JSON
"odata=nometadata" - заклинание, указывающее не передавать в ответе описание метаданных.
и отправляем его:
Если все хорошо, в ОтветСтрокой находится что-то вроде:
Разобрать ответ можно например так:
Если Ответ.КодСостояния > 299 Тогда ТекстОшибки = "Error, код ошибки: " + Ответ.КодСостояния + " |" + ОтветСтрокой; Иначе КолСтрок = СтрЧислоСтрок(ОтветСтрокой); Для НомерСтроки=1 По КолСтрок Цикл СтрокаАнализа = СтрПолучитьСтроку(ОтветСтрокой, НомерСтроки); Если СтрНайти(СтрокаАнализа,"Ref_Key") > 0 Тогда ПозицияДо = СтрНайти(СтрокаАнализа, """",НаправлениеПоиска.СКонца); ПозицияС = СтрНайти(СтрокаАнализа, """Ref_Key"": """); Если (ПозицияС > 0) И (ПозицияДо = (ПозицияС + 48)) Тогда НачалоID = ПозицияС + 12; GUID = Сред(СтрокаАнализа, НачалоID, 36); РезультатМассив.Добавить(GUID); КонецЕсли; КонецЕсли; КонецЦикла; БулевРезФун = Истина; ТекстОшибки = "OK. Считано элементов: " + Формат(РезультатМассив.Количество(), "ЧН=0; ЧГ &$filter=Ref_Key eq guid'" + KeyID + "'";
где в KeyID строковое представление УИД
Наименование реквизитов как видите порой неочевидно. Необходимо запомнить:
DeletionMark - пометка удаления,
IsFolder - признак группы,
Если реквизит ссылочного типа, к его имени следует добавить суффикс _Key, например Организация_Key.
Для документов используется схожий синтаксис:
/Base1C/odata/standard.odata/Document_СчетНаОплатуПокупателю?$select=Ref_Key, Number, Date&$format=json;odata=nometadata
Number - номер документа,
Date - дата документа.
Создание и изменения объектов через REST будет в следующей части.
Специальные предложения
Вызов Web-сервиса происходит следующим образом:
? из пула соединений выбирается подходящее соединение с информационной базой; при отсутствии необходимого соединения соединение создается;
? создается новый сеанс и для созданного сеанса вызывается событие УстановкаПараметровСеанса (в модуле сеанса);
? выполняется вызов затребованного метода Web-сервиса, при этом происходит вызов обработчика УстановкаПараметровСеанса() (в модуле сеанса) каждый раз, когда происходит обращение к неинициализированному параметру сеанса.
Если в пуле нет соединений, то создается новое соединение с загрузкой метаданных, что аналогично запуску 1С с нужной конфигурацией.
В новых версиях, программа может выбирать нужный сеанс из пула при этом УстановкаПараметровСеанса производиться не будет.
(22) В (24) подробно описано. Первое обращение к сервису вызывает загрузку и инициализацию используемых библиотек. Оно всегда долгое и учитывать его в замере производительности неверно. Риник; kolya85; Strannik777; Gendelf; Elvina; Drivingblind; binex; purgin; bow; + 9 – Ответить Эх, не дошли до самого интересного - до записи. Будете продолжать? Почему-то когда я читаю из базы документ, меняю в ответе один реквизит и пытаюсь записать, то в ответ возвращается всякая ерунда (обычно что не заполнена дата). (8) Я скорее практик чем теоретик. Состояние реализуется элементарно, на глобальных переменных или РС. Если выполнение кода сервиса зависит от значения глобальной переменной, эта переменная хранит состояние сервиса. (9)Глобальные переменные не подойдут - при работе с REST-Сервисом их нет. А хранение состояния в регистре сведений возможно - указано мной в (14), но это не то состояние, которое закладывается в определении REST-СервисаДо не давних пор WEB-Сервисы в 1С не имели возможности хранить состояния сеанса (теперь могут) + необходимость их предварительно кодить на 1С, чтобы использовать - это их главное отличи от REST-Сервисов (но зато WEB-Сервисы более универсальны (ведь в их реализации можно написать любой алгоритм); а области данных, доступ к которым можно получить в ИБ через REST-сейчас очень ограничены, например управлять пользователями нельзя).
(10) можете раскрыть смысл термина "состояние"? что вы в него вкладываете?(13)В простейшем виде. Состояние - любая управляемая (на которую клиент может целенаправленно влиять) информация, которая сохраняется на сервере после выполнения последней команды, и может быть получена (учтена) при выполнении следующей команды (при этом, при параллельном выполнении множества команд, в т.ч. от разных клиентов) нужная информация (созданная первой командой) будет автоматически (не важно как) сопоставляться со второй командой и соотноситься с исходным клиентом (когда это требуется).
За исключением тривиального примера: когда целем выполнения первой команды есть ТОЛЬКО создание этой информации. А второй команды - только её получение!
Путь будет так, простите, коли запутанно или не точно раскрыл термин. Я не профессор. Понятн, что за уши к этму определению можно приникнуть многое, но делать это не стоит.
(8)Дополнительно поясняю: описанный вам пример является требует наличия состояния на сервере, но не соответствует определению REST-сервиса. Насколько я понимаю, REST-Сервисы вообще не предназначены для запуска выполнения таких фоновых процессов. Но если они уже запущены, или запускаются косвенно после внесения изменений в данные, то формально, можно организовтаь что вы хотите, например так (как уже было предложено в (9)):
1. Допустим на сервере 1С есть регл. задание - которое выполняет какую-либо фоновую обработку (возможно через запуск отдельных фоновых заданий - это не принципиально).
2. Это регл задание, например, мониторит рег. сведений - на наличе записи с запросом на выполнение регл задачи (например произвольного алгоритма из строкового ресурса)
3. Тогда REST запросом - можно внести в этот регистр эту запись + некий ключ
4. Регл. задание это увидит и запусит фоновое выполнение этой задачи, передав ей этот ключ
5. Фоновое задание выполнит переданный алгоритм, например, некоторую часть (как это определяется к сути данного вопроса не относится) и запишет в тот же или другой рег. сведений по имеющемуся ключу результат (окончательный или промежуточный)
6. Внешний процесс через REST-Сервис будет опрашивать этот регистр по тому же ключу на наличие результата.
7. При необходимости через REST-сервис можно внести запись в регистр сведений, что выполнение нужно прервать (или внести изменения)
8. Эту запись то же регл задание может увидеть и прервать выполнение фонового задания с соответствующим ключём (или это может сделать само фоновое задание, тогда оно может внести любое изменения в ход своего выполнения).
Формально говоря, REST-Сервисы можно использовать и для выполнения каких-то фоновых процессов и опроса их результатов. И даже состояние в этом случае сохраняется в информационной базе. Но это лишь обходные уловки, реализация которых требует внесения изменений в конфигурацию. А сами данные состояния клиента, просто хранятся в базе данных. Но тем не менее, описанный мной выше алгоритм взаимодействия вполне может быть использован в рабочих системах.
По-другому запустить выполнение алгоритма через REST-Сервис в 1С (это ограничение текущей реализации 1С 8.3.9) пока нельзя. Но, думаю, со временем это изменится. И тогда, запустить, скажем фоновое выполнение задания можно будет и через REST. Но хранить состояния всё равно нужно будет в ИБ во вспомогательных хранилищах. И это не будет текущим состоянием сеанса. Это буду данные в базе данных.
Варианты хранения такого состояния ограничены лишь тем, что можно сохранить в БД. Например, не удастся так хранить состояние COM -Соединения, или иного сетевого соединения с другим ресурсом (в сети, интернете, или файлом); или оборудованием (подключенном через компоненту). Для многих задач хавтит и описанного способа, но не для всех.
(14) Вспомнил, что у ряда объектов метаданных (связанных с хранением данных) есть события изменения данных (в самих объектах и в приписках на события). В описании REST-Сервисов про них не сказано, но надо полагать они буду срабатывать, при изменении данных через REST. Соответственно, в предложенном мной примере запуска фонового процесса через REST-сервис регл. задании лишнее - если, скажем в модуле набора записей указанного в (14) регистра сведений в событии "ПриЗаписи" разместить алгоритм, который сам будет запускать фоновые задания, то фоновый процесс будет сразу же запускаться после окончания записи в регистр сведений через REST-вызов. Далее достаточно лишь опрашивать через REST регистр сведений с результатом (по тому же ключу).Формально, состояние клиента есть, и оно хранится в базе данных (получается по ключу, который сформировал клиент в первом обращении), как и есть возможность периодически опрашивать сервер, для получения промежуточных или итоговых данных.
Там не только подписки, но и выполнение на сервере итд.
И делать проверку модулей с галками внешнее соединение, сервер
Реализация REST-интерфейса от 1С – песня долгая, унылая, про борьбу нещадную и Пирровы победы… Но всё же применение ему есть, и в некоторых случаях он не просто производительнее и выгоднее в реализации других технологий обмена, но и просто незаменим.
При этом, до сих пор порядка 50% специалистов или вообще об oData не слышали или «что-то слышали», но «нужен обмен – COM forever», при том что более тормозной технологии обмена, по-моему, вообще на текущий момент не существует.
Описание теории в этой статье давать не буду, как и описание публикации базы данных на web-сервере, на все необходимые (и весьма интересные) для прочтения статьи ссылки приведу в конце статьи, сейчас займемся жёсткой практикой, и поймем, что «полдня» - это вполне реально)
Решение задач на получение данных (например получение остатков по банковским счетам) вообще делается «на лету», поэтому разберем случай с выгрузкой данных в приемник.
Итак, имеем две БД «управленческая» сильно переписаная КА 1.1 и самописная БД для учета контрагентов и банковских счетов «юрбаза», в которой работают юристы и финансовый отдел. Первичный ввод информации о контрагенте производится в юрбазе, нам же нужно оперативно выгрузить из нее информацию в управленческую. В данном случае весь код отрабатывается в юрбазе посредством GET и POST запросов в управленческую.
Оговорюсь, код не претендует на безукоризненность и соответствие стандартам, т.к. писалось «на скорую руку», надеюсь что сильно пинать за это меня не будут)
Для начала добавляем регистр сведений, скажем «Измененные объекты» для регистрации объектов при их записи, пишем процедуры регистрации, в модулях выгрузки будем обращаться к данным регистра. Ессно добавляем рег.задание для запуска выгрузки, оставляем за собой возможность интерактивной обработки данных из обработки. Для хранения данных для соединения с управленческой базой добавляем регистр сведений «Серверы oData». Описание действий дано, дабы код запросов был более читабелен.
Процедуры трассировки и обработки ошибок:
Процедуру ОписаниеВнутреннегоКодаОшибкиOData сдернул откуда-то из просторов Интернет, к сожалению не помню автора, но спасибо выражаю.
Для получения теоретического базиса и информации по публикации базы на web-сервере категорически рекомендуется прочесть:
Благодарю авторов данных статей, значительную часть моих познаний в данном вопросе я подчерпнул у них.
Читайте также: