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

В данной статье пойдет речь о кейсе внедрения HTTP-сервиса для мобильного приложения (*Мобильное приложение разрабатывает сторонний подрядчик) клиента по работе с нетиповым (самописным) документом. Рассмотрим все этапы разработки, начиная от создания объекта метаданных в дереве конфигурации, заканчивая отладкой, взаимодействием и работой с параметрами и телом запросов.

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

1. Немного предыстории и необходимость разработки

Одним из основных направлений деятельности клиента является диагностика, обслуживание и ремонт оборудования на выезде, для чего разработан документ «Заявка на ремонт», в которой указывается контрагент, объект, исполняющий работу специалист, диагностируемое оборудование, требуемые и затраченные материалы, работы и другие необходимые реквизиты.

Специалист получает заявку, после выполнения отправляет менеджерам всю информацию по данной заявке, которые заполняют документ в базе 1С, что создает лишние телодвижения и взаимодействие.

Исходя из этого появилась необходимость в мобильном приложении для выезжающих специалистов, в котором они могли бы взаимодействовать с данными заявками на ремонт (создавать, изменять и видеть список всех документов), исключая действия в виде письма менеджерам с необходимой информацией и работы менеджеров по мониторингу данных писем, заведения и редактирования документов.

2.  Работа с документацией API. Создание HTTP-сервиса с необходимыми шаблонами и методами

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

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

Рис.1. Таблица endpoint’ов в документации API

Рис.2. Пример описания GET-метода для справочника в документации API 

Первым делом создаем наш HTTP-сервис, раскрыв ветку «Общие» и найдя объект конфигурации «HTTP-сервисы». При создании указываем имя, синоним и корневой URL, который будет использоваться в формировании строки запроса:

Рис.3. Создание HTTP-сервиса

HTTP-сервис может содержать в себе один или несколько шаблонов. Шаблон задает путь, по которому будет происходить обращение к нашему HTTP-сервису. В шаблоне используется определенный набор символов, в том числе параметризованные сегменты вида «{параметр}» (рассмотрим чуть позже).

Рис.4. Создание шаблонов и методов для HTTP-сервиса

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

В платформе 1С для работы с HTTP-запросами основными методами являются GET, POST, PUT и DELETE. Немного теории:

GET — Получить данные

Для чего: Чтение данных (справочники, документы, отчеты)

POST — Создать или обработать данные

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

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

PUT — Полная замена объекта

Для чего: Перезаписать все поля объекта

DELETE — Удаление данных

Для чего: Удалить объект (документ, элемент справочника)

3. Объявление обработчиков для GET-методов

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

Рис.5. Начальное объявление обработчика метода

В параметре функции передается переменная «Запрос» с типом HTTPСервисЗапрос, в котором передается HTTP-метод, базовый и относительный URL, заголовки и параметры.

В теле функции формируем «Ответ» с типом HTTPСервисОтвет и значением 200 (код ответа, означающий, что запрос был успешно обработан) и возвращаем ответ.

4. Публикация HTTP-сервиса

На данном этапе можем опубликовать наш HTTP-сервис для проверки. Учтите, что при добавлении новых шаблонов и методов придется повторно опубликовывать сервис.

Также должен быть установлен веб сервер Apache (2.2 или 2.4) или IIS.

Если присутствует доступ до сервера, то необходимо запустить конфигуратор от имени администратора, «Администрирование» - «Публикация на веб-сервере»:

Рис.6. Форма публикации сервисов на веб-сервере

Указываем имя публикации, веб-сервер (в данном случае IIS), каталог, в котором будет размещена публикация. Устанавливаем флаг на нашем сервисе и публикуем. После этого перезапускаем веб-сервер.

5. Работа в Postman

Отлаживать работу сервиса будем в Postman - платформе для разработчиков, которая упрощает создание, тестирование и сотрудничество в работе с API.

Указываем необходимый HTTP метод, строку запроса, авторизация через Basic Auth (вводим данные пользователя базы 1С):

Рис.7. Postman. Форма отладки запросов

Строка запроса формируется следующим образом :

[ip адрес]/[имя публикации]/[hs]/[корневой URL]/[шаблон]

• IP адрес – IP адрес веб сервера;
• Имя публикации – имя, указанное при публикации сервиса;
• hs – сокращение от HTTP-сервис;
• Корневой URL – строка, которую мы указали в поле «корневой URL» при создании HTTP-сервиса;
• Шаблон – строка, указанная в шаблоне HTTP-сервиса.

Отправляем запрос, который должен вернуть только ответ с кодом 200, т.к. пока функция ничего больше не возвращает:

Рис.8. Postman. Проверка получения ответа

6. Реализация функций для GET-метода на примере одного из справочников. Работа с JSON. Отладка и получение ответа

На примере данного запроса реализуем метод GET для получения элементов справочника «Магазины» (описание которого указано выше) со следующими полями:

• GUID элемента справочника
• Наименование
• GUID бренда
• GUID контрагента
• GUID прикрепленного специалиста
• Комментарий

Что такое GUID и почему именно он?

Потому что это УНИКАЛЬНЫЙ 128-битный идентификатор, который присваивается каждому объекту в 1С (справочникам, документам, записям регистров и т. д.) и позволяет избежать конфликтов, вызванных совпадением идентификаторов. GUID позволяет надежно ссылаться на объекты, даже если их код или наименование изменились.

Создадим общий модуль, в котором будем объявлять функции и процедуры обработки и подготовки данных для ответа.

Рис.9. Функция получения и подготовки данных для ответа на запрос

На 3 этапе получаем из массива, выглядящего так:

Рис.10. Полученный массив до конвертации в JSON

Строку JSON, выглядящую так:

Рис.11. Полученный массив после конвертации в JSON

Также доработаем обработчик GET-метода:

Рис.12. Обработчик метода после доработки 

В ответ устанавливаем тело из полученной строки JSON, указываем кодировку UTF-8. Без нее русские символы будут передаваться в нечитаемом формате.

Проверяем, что запрос корректно формирует и отправляет ответ в Postman:

Рис.13. Postman. Проверка получения ответа

Код ответа – 200, тело ответа получено – запрос отработал корректно.

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

7. Работа с параметрами запроса (формирование запроса, отладка, работа с форматов даты ISO)

Но как быть, если не нужно постоянно отправлять всю информацию, пробегаясь по всем элементам объектов метаданных, а необходимо отправлять только изменения?

Рис.14. Документация API по поддержке изменений

Для этого были разработаны подписки на события «ПриЗаписи» для необходимых объектов, которые фиксируют изменения в разработанный периодический независимый Регистр сведений с 2 измерениями: ссылка на измененный объект и его GUID (с типом «Строка» для удобной работы с ним в дальнейшем).

Рис.15. Создание подписок на события «ПриЗаписи» для необходимых объектов

Но как работать с этим параметром «?updated_since=» ?

На самом деле все очень просто. Обратимся к Postman для наглядного примера формирования параметров запроса через конструкцию « ?[параметр]=[значение] »:

Перейдем на вкладку «Params», в которой как раз и указываются необходимые параметры, и добавим параметр с именем «updated_since» (поле «key») и его значением в формате ISO (поле «Value»):

Рис.16. Postman. Работа с параметрами запроса

Автоматически запрос дополняется данным параметром и передаваемым значением в нем.

С тем, как формируется строка запроса, понятно. Как обрабатывать подобный параметр?

Отправим данный запрос к базе и посмотрим на поля переменной «Запрос»:

Рис.17. Отладка запроса (параметры запроса)

Видим 2 поля с параметрами, но сейчас нас интересуют именно параметры запроса. В параметрах лежит ключ параметра “updated_since” и его значение. Запишем значение данного параметра в переменную и передадим в функцию для дальнейшей обработки. 

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

Рис.18. Обработчик метода при работе с параметрами запроса 

Но есть 2 небольших нюанса:

Первый – тип данных у полученного параметра даты «Строка», соответственно, необходимо преобразовать ее в переменную с типом «Дата» для дальнейшей работы. Для этого воспользуемся встроенной функцией ПрочитатьДатуJSON(<Строка>, <Формат>):

Рис.19. Работа с датой в формате ISO

Но после преобразования даты сталкиваемся со вторым нюансом – к дате прибавилось 7 часов. Почему так произошло?

Рис.20. Нюанс работы с параметром даты

Дело в том, что без указания часового пояса дата будет интерпретирована как дата в поясе UTC локального компьютера.

После этого в случае получения параметра получаем срез последних записей регистра сведений, подставив дату в параметр запроса, также формируем строку JSON и возвращаем ее обработчику.

Можно ли указать несколько параметров в запросе?

Да, можно. Соединение параметров в строке запроса происходит с помощью амперсанда «&»:

Рис.21. Postman. Работа с несколькими параметрами запроса

8. Работа с параметром URL. Отличия параметра запроса от параметра URL. Реализация обработчика GET-метода с параметром URL

Что же за такие параметры URL передаются вместе с параметрами запроса?

Давайте разбираться.

Помимо GET-запросов к справочникам, необходим GET-запрос для получения документа «Заявка на ремонт» (и всех необходимых полей) по идентификатору GUID. Безусловно, мы могли бы отправлять GUID точно так же, как и дату изменений, но есть некоторые ключевые отличия:

Рис.22. Отличия параметров запроса и URL

Параметр запроса в основном используется для фильтрации и сортировки, параметр URL же используется для идентификации ресурсов, поэтому в данном случае корректнее будет использовать именно его.

Окей, почему именно параметр URL – понятно, но как с этим работать?

Все очень просто: этот параметр «вшивается» в шаблон и указывается в фигурных скобках {}:

Рис.23. Настройка шаблона для работы с параметром URL

В данном случае параметром является «external_key».

А теперь посмотрим, как это выглядит на практике. Для начала перейдем в Postman:

Рис.24. Postman. Запрос, содержащий параметр URL

Если перейдем на вкладку «Params», то видим, что никаких параметров запроса нет. GUID указывается после «/» и является частью URL (после которого может использоваться конструкция «?[параметр]=[значение]»).

Отправим запрос и перейдем в отладку:

Рис.25. Отладка запроса (параметр URL)

Теперь в запросе параметр передается в «ПараметрыURL».

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

Рис.26. Обработчик метода, обрабатывающего параметр URL (получения документа по GUID)

Проверим сформированный ответ в Postman:

Рис.27. Postman. Проверка получения ответа

Код ответа – 200, тело ответа получено с необходимыми полями.

9. Заголовки в HTTP-ответе

Также хорошим тоном является объявление заголовков.

Заголовки в HTTP-ответе 1С обеспечивают корректное взаимодействие с клиентами (браузерами, мобильными приложениями, другими системами), управляют кэшированием, безопасностью и форматом данных. Без них интеграция с внешними системами была бы значительно сложнее.

Сообщим в заголовке “Content-Type”, в каком формате мы передаем данные (в нашем случае JSON), а также используемую кодировку UTF-8:

Рис.28. Добавление заголовков в HTTP ответ

Рис.29. Postman. Проверка полученного заголовка (вкладка «Headers»)

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

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