Первое знакомство с HTTP-сервисами в 1С. Часть 2

В прошлой статье мы разобрали начальное ТЗ и необходимость внедрения данного HTTP-сервиса, познакомились с документацией API, создали HTTP-сервис с необходимыми шаблонами и методами и разработали обработчики для GET-методов, опубликовали HTTP-сервис, познакомились с Postman. Реализовали функции для GET-методов с обработкой параметров запроса и URL, разобрали некоторые нюансы по работе с передаваемыми параметрами и настроили заголовки в HTTP-ответе.

В данной статье разберем реализацию и работу с POST и PUT методами, обработку ошибок, работу с несколькими табличными частями документов (как их обрабатывать и корректно формировать ответ), а также некоторые нюансы по работе с уникальными идентификаторами GUID.

Данная тема актуальна для разработчиков 1С, которые начинают свое знакомство с HTTP-сервисами и REST API.

Перед началом вспомним основные методы протокола HTTP:

1. GET — Получение данных

Основная задача: Запрос данных с сервера без их изменения.

Характеристики:

• Безопасный (Safe) – Не изменяет состояние сервера.

• Идемпотентный – Многократный вызов возвращает одинаковый результат.

• Данные передаются в URL (например, параметры запроса).

• Не имеет тела запроса (данные только в строке URL).

• Кэшируется браузерами и прокси-серверами.

Когда использовать?

• Получение справочников (контрагенты, номенклатура).

• Чтение документов (накладные, счета).

• Запросы отчетов (аналитика продаж).

2. POST — Создание или обработка данных

Основная задача: Отправка данных на сервер для создания ресурса или выполнения операции.

Характеристики:

• Небезопасный – Может изменять данные на сервере.

• Неидемпотентный – Повторный запрос может создать дубликат.

• Тело запроса есть (JSON, XML, форма).

• Не кэшируется по умолчанию.

Когда использовать?

• Создание новых объектов (документы, справочники).

• Вызов сложных операций (проведение документа, расчет зарплаты).

• Загрузка файлов.

3. PUT — Обновление данных

Основная задача: Полная замена существующего ресурса или его создание, если его нет.

Характеристики:

• Небезопасный – Изменяет данные на сервере.

• Идемпотентный – Повторные запросы не меняют результат.

• Тело запроса есть (передаются новые данные).

• Не кэшируется.

Когда использовать?

• Редактирование существующих объектов (изменение реквизитов).

• Замена всего ресурса (например, перезапись документа).

Про метод GET было рассказано в первой части статьи, сегодня уделим внимание методам POST и PUT.

Метод POST

Обратимся к API документации, чтобы понять ЧТО и КАК необходимо реализовать в рамках поставленной задачи. Одной из задач является разработка механизма создания документа «Заявка на ремонт» с определенным набором необходимых реквизитов, а также с 4 табличными частями (Оборудование, необходимые и затраченные материалы, а также работы).

В первой части статьи мы разобрались с параметрами запросов, сейчас необходимо познакомиться с телом запроса, который выглядит следующим образом:

Рис. 1. API Документация к POST методу

Тело запроса

Тело HTTP-запроса — это часть запроса, которая содержит данные, передаваемые на сервер. В отличие от заголовков (headers) и параметров URL, тело используется для передачи структурированной информации, такой как:

• JSON (наиболее популярный формат для REST API),

• XML (используется в SOAP-сервисах),

• Формы (form-data) (например, загрузка файлов),

• Текст/бинарные данные (например, CSV, изображения).

Когда нужно тело запроса?

Тело используется в методах, которые отправляют данные на сервер:

• POST – создание ресурса,

• PUT – полное обновление ресурса,

• PATCH – частичное обновление,

• DELETE (иногда, если нужно передать параметры сложного удаления).

Методы GET, HEAD, OPTIONS не используют тело, так как все параметры передаются в URL.

Как работает тело запроса в 1С?

В 1С для работы с телом HTTP-запроса используются:

• Установка/получение тела из строки (JSON/XML/текст).

• Установка/получение тела из потока (для файлов, бинарных данных).

Обратимся к Postman:

Рис. 2. Postman. Тело POST запроса

На вкладке «Body» установим тело, отправим запрос и обратимся к отладке:

Обратившись в запросу мы не увидим поля «Тело». Необходимо обратиться к методу «ПолучитьТелоКакСтроку(<Кодировка>)» (если кодировка не указана, то она определяется из заголовка «Content-Type»; если кодировка в заголовке не указана, то используется UTF-8).

Рис. 3. Получение тела запроса

Но полученное тело является строкой – как с ней работать?

Для преобразования из JSON строки (XML, двоичных данных или другого формата, в который он был ранее сериализован) в удобную структуру данных (десериализации) используются встроенные методы:

Рис. 4. Преобразование JSON строки в структуру

После преобразования получаем структуру, с которой в дальнейшем можем удобно работать.

Теперь необходимо из полученных данных (в частности строк) преобразовать в необходимые типы (ссылки, даты).

Обработка ошибок

Из первой части статьи вспомним, что все ссылочные типы преобразуются в GUID (уникальный 128-битный идентификатор) для однозначной идентификации объектов. В данном случае получаем GUIDы, которые необходимо обратно преобразовать в ссылочные типы. Однако нужно предусмотреть ситуации, когда передали некорректные идентификаторы, т.к. в случае ошибки нужно не просто отдать пустой ответ, а передать причину возникшей ошибки с соответствующим кодом для ее решения и предотвращения в будущем. Для этого воспользуемся конструкцией «Попытка Исключение»:

Рис. 5 Обработка ошибок (блок «Попытка»)

Рис. 6. Обработка ошибок (блок «Исключение»)

Для проверки корректности GUID используется регулярное выражение следующего формата:

Рис. 7. Регулярное выражение для проверки корректности GUID

Затем подобным образом проверяем табличные части и в случае корректности данных создаем документ, заполняем реквизиты, табличные части, записываем и передаем GUID документа, т.к. в дальнейшем необходимо вернуть данные в ответе, вызвав метод GET.

Рис. 8. Обработка POST запроса

Перейдем в базу и проверим созданный документ:

Рис. 9. Проверка созданного документа в базе 1С

Документ корректно создался и записался.

Рис. 10. Postman. Проверка полученного ответа на корректный POST запрос

Ответ получен.

Теперь проверим, что будет, если передадим некорректные данные (допустим в customer key (контрагент)):

Рис. 11. Postman. Проверка полученного ответа на некорректный POST запрос

В ответе видим код ответа 422 (Bad request), и в теле видим причину некорректного ответа.

Метод PUT

В нашем случае метод PUT будет осуществлять полное обновление существующего объекта (документа). Также для идентификации существующего изменяемого документа необходимо передать его номер (GUID). Возвращаясь к первой части статьи, определим, какой именно параметр необходим: параметры запроса используются для фильтрации и сортировки, а параметры URL используются для идентификации ресурсов. Исходя из этого, будем использовать параметры URL, т.к. нужно понимание, какой именно «ресурс» предстоит изменять.

В теле данного запроса устанавливаем JSON строку с необходимыми полями (реквизитами) документа.

Перейдем в базу и найдем какой-нибудь документ, узнаем его GUID и отправим запрос на изменение полей «Контактное лицо», «Причина вызова» и «Заключение»:

Рис. 12. Изменяемый документ

Рис. 13. Postman. Тело PUT запроса

Рис. 14. Обработчик PUT запроса

Рис. 15. Функция обработки и получения документа по GUID

Далее в полученном объекте по ссылке перезаписываем реквизиты и табличные части, не забывая о проверках GUID’ов.

После удачного выполнения запроса вернемся к документу и проверим, изменились ли реквизиты:

Рис. 16. Измененный документ

Работа с несколькими табличными частями при формировании JSON

Т.к. при формировании ответа с несколькими табличными частями постоянно возникали ошибки, а при поиске информации по данному вопросу, не получилось найти хороших понятных статей, где объясняется, к какому типу необходимо преобразовывать табличные части, думаю, что данное дополнение будет полезным.

На деле все оказалось намного проще, чем казалось. Чтобы передать несколько табличных частей в ответе:

1. Объявляем массив для записи табличной части;

2. В цикле:

2.1 Создаем структуру для каждой строки табличной части

2.2 Добавляем данную структуру в массив;

3. Получившийся массив после всех итераций вставляем в результирующую структуру;

4. Повторяем для необходимого количества табличных частей.

Рис. 17. Пример программного кода для подготовки нескольких табличных частей перед преобразованию в JSON 

В данной статье мы разобрали реализацию и работу с POST и PUT методами, обработку ошибок, работу с несколькими табличными частями документов и некоторые нюансы по работе с уникальными идентификаторами GUID.