Как правильно передавать и обрабатывать параметры в GET-запросах HTTP-сервисов 1С?

При разработке интеграций на базе HTTP-сервисов в платформе «1С:Предприятие 8» программисты часто сталкиваются с дилеммой: как лучше передавать идентификаторы и фильтры в запросе. Существует два основных способа передачи данных в строке URL: через сегменты пути (Path Parameters) и через параметры строки запроса (Query Parameters). Разберем по шагам, чем они отличаются, как настраиваются в конфигураторе и как правильно обрабатываются в программном коде. Для организации регулярной синхронизации данных без разработки собственных сервисов предусмотрен инструмент для автоматизации регулярного обмена данными между базами 1С по расписанию через XML-правила.

Различие между ПараметрыURL и ПараметрыЗапроса

Для начала проанализируем ситуацию, с которой столкнулся автор темы. Изначально сервис работал по адресу {{base_url}}/partners/83256700-4e39-11ee.... Это классический пример использования Параметров URL. В этом случае идентификатор ресурса является частью самого пути.

Когда же возникает необходимость передать параметр после знака вопроса, например /partners?partner_ref=83256700..., мы имеем дело с Параметрами Запроса. В объектной модели 1С эти данные попадают в разные коллекции объекта HTTPСервисЗапрос:

1. ПараметрыURL (URLParameters): Содержит части адреса, которые были описаны в шаблоне URL в фигурных скобках. Если шаблон выглядит как /partners/{partner_ref}, то платформа автоматически извлечет значение из пути и поместит его в эту коллекцию.
2. ПараметрыЗапроса (QueryOptions): Содержит всё, что идет в URL после символа «?». Эти параметры не описываются в шаблоне метаданных 1С явным образом.

Корректная настройка шаблона URL

Выясним причину, по которой у автора перестал работать запрос при переходе к использованию знака вопроса. Если в метаданных 1С (в дереве конфигурации) для HTTP-сервиса указан шаблон /partners/{partner_ref}, система ожидает, что после слова «partners» обязательно будет идти какой-то текст через слеш. Если мы отправляем запрос на /partners?partner_ref=..., то для веб-сервера путь заканчивается на слове «partners», и он не находит соответствия заданному шаблону, возвращая ошибку 404 Not Found.

Чтобы сервис начал принимать параметры через «?», выполним следующие действия:

1. Упростим шаблон URL в конфигураторе. Вместо /partners/{partner_ref} укажем просто /partners.
2. Теперь платформа будет сопоставлять любой запрос, начинающийся с этого пути, отсекая всё, что идет после знака вопроса для целей поиска шаблона. При необходимости забирать файлы из внешних источников предусмотрена программа для автоматического сбора файлов из электронной почты, FTP и HTTP с последующей выгрузкой.
3. Если необходимо поддерживать оба варианта (и путь, и строку запроса), придется создать два разных шаблона или использовать символ «*» (например, /partners/*), но первый вариант предпочтительнее для чистоты архитектуры.

Программная обработка параметров в методе GET

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

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

Функция partnersGet(Запрос)
    
    // 1. Пытаемся получить параметр из строки запроса (после ?)
    ИдентификаторПартнера = Запрос.ПараметрыЗапроса.Получить("partner_ref");
    
    // 2. Если параметр не найден в QueryOptions, возможно, он передан в URL (в шаблоне)
    Если ИдентификаторПартнера = Неопределено Тогда
        ИдентификаторПартнера = Запрос.ПараметрыURL.Получить("partner_ref");
    КонецЕсли;
    
    // 3. Валидация данных
    Если ИдентификаторПартнера = Неопределено Тогда
        Возврат Новый HTTPСервисОтвет(400); // Ошибка: параметр не передан
    КонецЕсли;
    
    // 4. Преобразование типа, если ожидается GUID
    Попытка
        УИД = Новый УникальныйИдентификатор(ИдентификаторПартнера);
    Исключение
        Возврат Новый HTTPСервисОтвет(400); // Ошибка: неверный формат GUID
    КонецПопытки;
    
    // Далее следует логика поиска партнера в базе...
    
КонецФункции

Обратите внимание на проверку через Неопределено. В коллекции ПараметрыЗапроса метод Получить() вернет именно этот тип, если ключ отсутствует в строке URL. Это позволяет гибко настраивать логику фильтрации. Для быстрой проверки корректности работы разработанных методов можно использовать инструмент для тестирования и отладки HTTP-сервисов.

Особенности лицензирования и время жизни сеанса

В процессе обсуждения на форуме была затронута важная тема «времени жизни сеанса 20 секунд». Разберем, как это влияет на работу системы. HTTP-сервисы в 1С работают через механизм пула сеансов. Это сделано для того, чтобы на каждый чих внешнего приложения не тратилось время на полноценный запуск нового сеанса (авторизацию, инициализацию параметров сеанса и т.д.). После выполнения обмена данными через сервисы для поиска расхождений в учете применяется программа автоматической сверки бухгалтерских и налоговых проводок между базами 1С через COM-соединение.

Когда запрос поступает на веб-сервер (IIS или Apache), расширение 1С ищет свободный сеанс в пуле. Если он найден, запрос выполняется мгновенно. Если нет — создается новый сеанс, при этом расходуется клиентская лицензия. После завершения обработки запроса сеанс не закрывается сразу, а «засыпает» и удерживает лицензию в течение времени, указанного в настройках (обычно в файле default.vrd). Если в течение этих 20 секунд придет новый запрос, он использует ту же лицензию. Это критически важно учитывать при проектировании высоконагруженных систем, чтобы не столкнуться с нехваткой лицензий для обычных пользователей.

Безопасность и работа со спецсимволами

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

1. Кодирование строк: Если в параметре partner_ref передается не GUID, а, скажем, наименование партнера с пробелами или кириллицей, строка в URL должна быть закодирована (URL-encoded). Платформа 1С обычно автоматически декодирует значения в коллекции ПараметрыЗапроса, но при формировании обратных запросов из 1С не забывайте использовать функцию КодироватьСтроку().
2. Ограничение длины: Помните, что длина строки URL ограничена возможностями веб-серверов и прокси-серверов (обычно лимит составляет около 2-8 тысяч символов). Если вам нужно передать огромный массив данных, знак вопроса в GET-запросе — не лучшее решение. В таких случаях следует использовать метод POST и передавать данные в теле (Body) запроса в формате JSON.
3. Чувствительность к регистру: Хотя 1С внутри себя работает с ключами соответствия, имена параметров в URL могут быть чувствительны к регистру на стороне веб-сервера. Старайтесь всегда придерживаться единого стандарта (например, snake_case или camelCase) и в коде, и в документации к API.

Использование ПараметрыЗапроса делает ваши API более гибкими и привычными для веб-разработчиков, так как позволяет передавать необязательные фильтры, настройки пагинации (limit, offset) и параметры сортировки, не перегружая структуру шаблонов URL в метаданных конфигурации.