HTTP Сервисы: Путь к своему сервису. Часть 3

Программирование - Инструментарий

HTTP-сервис API JSON IIS http web apache сервис Публикатор Линк PAPI Pretty API atom-xml XML OData Код состояния СКД БСП Длительные операции

118
Продолжение статьи «HTTP Сервисы: Путь к своему сервису. Часть 2». В предыдущих частях мы использовали только Get, в этой части поговорим о других методах и длительных операциях.

В первой части мы создали каркас для Get метода в расширении конфигурации. Во второй части мы поработали с OData и создали обработку, получающую через HTTP-Сервис используя метод Get данные сформированные при помощи СКД. В этой части поговорим про другие методы и БСП:Базовая функциональность\Длительные операции (при отсутствии БСП в Вашей конфигурации необходимо использовать фоновые задания).

В этой статье http-сервис будет в расширении конфигурации БСП 2.4.6.146 на платформе 8.3.10.2650 + IIS, а вот посылать запросы и получать ответы будем в БСП 3.0.1.231 на платформе 8.3.12.1595.

Начнем.

Какие методы можно добавить в HTTP-Сервис?

  • GET - Получение данных.
  • HEAD - Запрашивает ресурс так же, как и метод GET, но без тела ответа.
  • PUT - Изменение данных.
  • POST - Создания новой сущности на сервере.
  • DELETE - Удаления данных.
  • PATCH - Используется для частичного изменения ресурса.
  • MERGE - Предназначен для дифференциального изменения данных. Аналогичен методу PATCH, но является расширением от Microsoft.
  • OPTIONS - Предназначен для получения информации о способах работы с данным URI (доступные HTTP-методы, форматы представления и т.п.).
  • TRACE - Возвращает полученный запрос так, что клиент может увидеть, какую информацию промежуточные серверы добавляют или изменяют в запросе.
  • CONNECT - Преобразует соединение запроса в прозрачный TCP/IP-туннель, обычно чтобы содействовать установлению защищённого SSL-соединения через нешифрованный прокси.
  • ANY (Любой) - Указывает, что может быть использован любой HTTP-метод из перечисления HTTPМетод.
  • И команды для WebDAV(Web Distributed Authoring and Versioning) или просто DAV — набор расширений и дополнений к протоколу HTTP, поддерживающих совместную работу пользователей над редактированием файлов и управление файлами на удаленных веб-серверах. (Еще ссылка по WebDAV)
 
 WebDAV расширяет HTTP следующими командами:

Подробнее о методах можно почитать туттут и тут

Давайте обратим внимание на метод «ANY (Любой)» - Данный метод позволяет перехватывать любой метод и обрабатывать его.

В голову пришел небольшой эксперимент благодаря статье Отправка PUT запроса средствами 1С 8.3. Давайте создадим в нашем http-сервисе метод ANY и в цикле используя ВызватьHTTPМетод переберем методы (GET, HEAD, PUT, POST, DELETE, PATCH, MERGE, OPTIONS, TRACE, CONNECT), обращаясь с телом запроса и без. Будем возвращать информацию по запросу.

Для начала создадим Демо базу на основе БСП 2.4.6.146 (на платформе 8.3.10), добавим в нее расширении из предыдущей части, изменим Корневой URL на PAPI и добавим метод "Любой (ANY)".

Обратите внимание на заголовок "Content-Type" (Код обработчика PAPI_ALL). Данный заголовок содержит тип данных и служит для того чтобы можно было понять, что находится в запросе или ответе. Про возможные типы можно почитать тут. мы укажем "text/plain; charset=utf-8" - текстовые данные.

 
 Код обработчика PAPI_ALL

Шаблон у нас будет такой: /{ИмяМетода}

Теперь опубликуем:

Создадим, если ранее не создавали Демо базу на основе БСП 3.0.1.231 (на платформе 8.3.12), и создадим небольшую внешнюю обработку с одной командой ВсеМетоды и реквизитом Результат с типом строка.

 
 Код команды ВсеМетоды

Проверяем результат:

 
Лог из IIS

Из логов видно, что все запросы кроме запроса с методом TRACE отработали и с телом запроса и без.

Результаты метода ANY:

 
 GET
 
 HEAD
 
 PUT
 
 POST
 
 DELETE
 
 PATCH
 
 MERGE
 
 OPTIONS
 
 TRACE
 
 CONNECT

Как мы видим, часть методов имеет схожее назначение за некоторыми отличиями. Большинство API предоставляют клиентам только методы GET, POST и реже PUT.

Давайте сравним GET и POST:

Параметры сравнения

GET

POST

Описание

Запросы можно кэшировать

Да

Нет

Могут быть кэшированы браузером.

Запросы сохраняются в истории браузера

Да

Нет

Следовательно, если логин и пароль указан в параметрах запроса, злоумышленник без труда их узнает.

Запросы можно добавить в закладки, идемпотентность

Да

Нет

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

Безопасные запросы

Да

Нет

Спецификация HTTP 1.1 вводит два понятия: безопасный и небезопасный запрос, или если быть более точным, метод.

Безопасные — это методы, которые могут лишь запросить информацию. Они не могут изменить запрашиваемый ресурс, не могут привести к нежелательным результатам для пользователя, других лиц или сервера.

Содержит тело запроса

Нет

Да

Для POST параметры передаются в теле.

Можно передавать файлы

Нет

Да

 

Способен передать большие объемы данных

Нет

Да

 

Запрос ограничен длинной URL

Да

Нет

Несмотря на то, что RFC не описывает такой параметр, как длина URL, Internet Explorer упорно придерживается мнения, что максимальная длина URL не может превышать 2048 символов, это накладывает некоторые ограничения на использование GET.

Картинка ниже, утрировано, но очень наглядно показывает выбор между GET и POST:

Ссылки по сравнению GET с POST:

Давайте нарисуем сервис «Список заданий за период», раз уж мы используем демо базу БСП, то использовать будем Отчет.Задания и его СКД макет с вариантом настроек «СписокЗаданий». Будем подавать Начало и Конец периода и формировать ответ в формате JSON. Наша задача сделать так, чтобы можно было забирать данные как через GET, так и через POST.

Добавляем метод POST и пишем код его обработки.

 
 Функция PAPI_POST

Правим, обработчик метода GET, добавляем Метод запроса.

 
 Функция PAPI_GET

 В модуль PAPI_ОбработкаУниверсальныхМетодов добавляем код для нового метода.

 
 Код модуля PAPI_ОбработкаУниверсальныхМетодов

В модуль PAPI_ОбщиеПроцедурыИФункции добавляем функцию ПолучитьДатуВремяИзСтроки - для преобразования данных в дату.

 
 Код модуля PAPI_ОбщиеПроцедурыИФункции

В модуль PAPI_ОбработкаМетодовGET добавляем код обработки метода "ПолучитьСписокЗаданийЗаПериод"

 
 Код модуля PAPI_ОбработкаМетодовGET

Создаем модуль PAPI_ОбработкаМетодовPOST

 
 Код модуля PAPI_ОбработкаМетодовPOST

Наш сервис готов! Давайте теперь дорисуем обработку и будем тестировать. Обратите внимание, что я оставил метод ANY, по сути, обращение к нему отличается лишь отсутствием в URL "V1/". Данный метод позволит Вам выводить параметры вашего запроса.

GET: http://127.0.0.1/DemoSSL2_4_6_146/hs/PAPI/V1/ПолучитьСписокЗаданийЗаПериод?StartPeriod=2014-01-01T00:00:00&EndPeriod=2018-01-01

 
 Результат

GET через ANY: http://127.0.0.1/DemoSSL2_4_6_146/hs/PAPI/ПолучитьСписокЗаданийЗаПериод?StartPeriod=2014-01-01T00:00:00&EndPeriod=2018-01-01

 
 Результат

Доделаем обработку, которую создавали выше. Добавим реквизиты КонецПериода и НачалоПериода с типом Дата, МетодСервиса с типом Строка и делаем РежимВыбораИзСписка (GET(GET), POST(POST), Проверить(ANY)). Добавляем команду ПолучитьРезультат.

 
 Код команды ПолучитьРезультат

Проверяем:

 
 Результат "Проверить"

Длительные операции.

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

Давайте для нашего GET метода создадим параметр BTask=True - будет означать, что операцию нужно выполнить используя БСП:Базовая функциональность\Длительные операции. Создадим модуль для асинхронных операций. Создадим метод GET для проверки выполнения фонового задания и получения результата "ФоновоеЗаданиеПроверить" с параметрами Result_Key (Адрес хранилища результата. Обязательный параметр) и Task_Key (Идентификатор фонового задания. Необязательный параметр).

Предлагаю перенести наше разрешение в Демо базу на основе БСП 3.0.1.231 (на платформе 8.3.12). Хочу создать справочник для хранения результатов, что позволит обращаться к результатам хоть через год... Пока не удалят элемент справочника.

Редактируем обработчик PAPI_GET, добавляем в структуру БазовыйURL.

 
 Функция PAPI_GET

Создаем Справочник.PAPI_ХранилищеРезультатов. Добавляем реквизиты АдресРезультата - Строка(200) и Результат - ХранилищеЗначения

Создаем модуль PAPI_АсинхронныеОперации

 
 Код модуля PAPI_АсинхронныеОперации

Правим модуль PAPI_ОбработкаМетодовGET. Добавляем код для запуска фонового задания и метод получения результата фонового задания.

 
 Код модуля PAPI_ОбработкаМетодовGET

В модуль PAPI_ОбщиеПроцедурыИФункции, добавляем функцию НайтиЗадание.

 
 Код модуля PAPI_ОбщиеПроцедурыИФункции

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

http://127.0.0.1/DemoSSL3_0_1_231/hs/PAPI/V1/ПолучитьСписокЗаданийЗаПериод?StartPeriod=2008-01-01T00:00:00&EndPeriod=2018-01-01&BTask=true

Нажимаем "Ссылка на получение результата"

Была сформирована ссылка на сохраненный результат:

http://127.0.0.1/DemoSSL3_0_1_231/hs/PAPI/V1/ФоновоеЗаданиеПроверить?Result_Key=ПолучитьСписокЗаданийЗаПериод_b2fe7494-3e86-4748-bce6-a33d69c14ca2&Task_Key=e8a450b1-bdd5-4703-a76b-9c6015a39fb7

Соответственно можно и без идентификатора задания обращаться:

http://127.0.0.1/DemoSSL3_0_1_231/hs/PAPI/V1/ФоновоеЗаданиеПроверить?Result_Key=ПолучитьСписокЗаданийЗаПериод_b2fe7494-3e86-4748-bce6-a33d69c14ca2

Третью часть заканчиваю. Мы рассмотрели с Вами методы GET, POST и ANY, создали сервис на основании данных отчета СКД. Сделали возможность запускать фоновое задание через GET и сохранили результат. Данный механизм при должной доработке позволит выдавать одинаковые запросы без обработки запросов.

Статьи из данного цикла:

HTTP Сервисы: Путь к своему сервису. Часть 1

HTTP Сервисы: Путь к своему сервису. Часть 2

HTTP Сервисы: Путь к своему сервису. Часть 4

118

Скачать файлы

Наименование Файл Версия Размер
Расширение с рассмотренными примерами сервисов. (Под 8.3.12)
.cfe 31,34Kb
10.10.18
9
.cfe 0.0.4 31,34Kb 9 Скачать
Расширение с рассмотренными примерами сервисов. Без Длительных Операций (Под 8.3.10)
.cfe 26,81Kb
10.10.18
4
.cfe 0.0.3 26,81Kb 4 Скачать
Внешняя обработка созданная по ходу статьи (HTTP-сервисы часть3)
.epf 8,07Kb
10.10.18
8
.epf 0.1 8,07Kb 8 Скачать

См. также

Специальные предложения

Лучшие комментарии
5. dsdred 914 29.08.18 19:57 Сейчас в теме
(4)
Веб-/хттп-сервисы не занимают клиентскую лицензию (работают без ее использования)

Я не про лицензии на подключение web\http-сервисов имел ввиду. Я про тот случай когда клиент использует наш сервис, в своей системе. На картинке ниже изобразил.
Прикрепленные файлы:
Остальные комментарии
Избранное Подписка Сортировка: Древо
1. 🅵🅾️🆇 28.08.18 12:09 Сейчас в теме
3. dsdred 914 28.08.18 21:34 Сейчас в теме
(1)Не за что ;)) А за слово не мне спасибо, а Бенджамину Пирсу.
2. eeeio 102 28.08.18 16:16 Сейчас в теме
Обязательно продолжайте
4. Cyberhawk 108 29.08.18 15:05 Сейчас в теме
мы знаем, что результат будет формироваться долгое время и нет смысла держать сеанс (лицензию)
Веб-/хттп-сервисы не занимают клиентскую лицензию (работают без ее использования)
5. dsdred 914 29.08.18 19:57 Сейчас в теме
(4)
Веб-/хттп-сервисы не занимают клиентскую лицензию (работают без ее использования)

Я не про лицензии на подключение web\http-сервисов имел ввиду. Я про тот случай когда клиент использует наш сервис, в своей системе. На картинке ниже изобразил.
Прикрепленные файлы:
6. Cyberhawk 108 29.08.18 20:47 Сейчас в теме
(5) Ясно. Но все равно пока не приходит на ум такой сценарий, при котором на стороне потребителя хттп-сервиса такая экономия лицензии будет иметь смысл.
7. dsdred 914 29.08.18 21:07 Сейчас в теме
(6) Это просто вариант, который возможен, а смысл длительных операций и хранения результата может использоваться во многих вещах. Про одну из таких вещей я сказал в конце данной статьи вскользь - хранение результата для «одинаковых запросов». О еще одной вещице расскажу в 4 части, если соберусь ее писать…
8. maxx 659 30.08.18 10:54 Сейчас в теме
9. maxx 659 30.08.18 11:32 Сейчас в теме
Вопросик про длительные операции возник.

Вы в запросе входящем передаёте ИдентификаторЗадания для поиска фонового и АдресРезультат для поиска элемента в справочнике хранилище результатов. А можно ли бы идентификатор задания сохранить в реквизите справочника ХранилищеРезультатов, тогда в url запросе можно было передавать только один параметр АдресРезультата (или вообще уже передавать уникальный идентификатор элемента ХранилищеРезультатов) ?
10. dsdred 914 30.08.18 12:19 Сейчас в теме
(9)
А можно ли бы идентификатор задания сохранить в реквизите справочника ХранилищеРезультатов, тогда в url запросе можно было передавать только один параметр АдресРезультата (или вообще уже передавать уникальный идентификатор элемента ХранилищеРезультатов) ?


Не вижу смысла хранить идентификатор фонового задания.

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

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

http://127.0.0.1/DemoSSL3_0_1_231/hs/PAPI/V1/ФоновоеЗаданиеПроверить?Result_Key=ПолучитьСписокЗаданийЗаПериод_b2fe7494-3e86-4748-bce6-a33d69c14ca2

где Result_Key - адрес результата

Я конечно понимаю что имя метода ФоновоеЗаданиеПроверить несовсем корректно, надо было назвать ПолучитьРезультат или что то в этом духе...
С другой стороны я просто рисую примеры, а не коммерческий проект))
Оставьте свое сообщение