HTTP-запросы во встроенном языке

Общая информация

В основе HTTP-взаимодействия лежит понятие URI (или, в более простом варианте - URL) - универсального идентификатора ресурса, который описан к стандарте RFC 3986. Взаимодействие осуществляется с помощью запросов. Каждый запрос содержит несколько частей: стартовая строка (определяет тип сообщения), заголовки (определяет параметры запроса) и тело сообщения (дополнительные данные запроса, тело сообщения может быть пустым).

метод uri HTTP/версия

HTTP/версия код-состояния пояснение

Заголовки запроса — это набор именованных параметров запроса. Каждый запрос может содержать различный набор таких параметров. Заголовки делятся на 4 большие части: общие заголовки (используются как в запросах, так и в ответах), заголовки запроса (используются только в запросах), заголовки ответа (используются только в ответах) и заголовки сущностей (сопровождают каждую сущность сообщений, используются как в запросах, так и в ответах). Имена заголовков не чувствительны к регистру символов. Запрос может содержать несколько заголовков с одинаковым именем. Такое допускается только в том случае, если несколько значений заголовка могут быть перечислены через символ «,», а также если порядок следования значений в заголовке не изменяет семантику заголовка.

Таким образом HTTP-взаимодействие выполняется следующим образом:

Методы HTTP-запроса

Описание методов, приведенное в таблице, является рекомендуемым поведением. Фактическое поведение целиком и полностью определяется фактической реализацией сервера HTTP-запроса.

Коды состояния

Кодирование URL адреса в ЗапросHttp

В адресе запроса могут содержаться символы, использование которых недопустимо в URI. Для успешного выполнения такого запроса недопустимые символы должны быть закодированы с использованием символа «%». Однако разработчик не всегда может гарантировать кодирование всех недопустимых символов. В результате в адресе запроса могут встречаться допустимые символы, закодированные недопустимые символы и недопустимые символы, которые не были закодированы.

Для того чтобы обеспечить успешное выполнение запроса в любом случае, ЗапросHttp во входящей строке сохраняет процент-кодированные представления символов, которые там уже есть, а все недопустимые символы кодирует. Входящая строка адреса обрабатывается следующим образом: если за символом процента (%) следует значение, допустимое для кода символа (два шестнадцатеричных значения), то считается, что это код символа. Иначе считается, что это знак процента, который будет закодирован (%25).

Входящий адрес URL (строка) разделяется на группы и каждая группа кодируется отдельно (например, путь, запрос и т. д.). Группы адреса соответствуют описанию стандарта RFC3986: схема (scheme), основание (authority), путь (path), запрос (query), фрагмент (fragment):

Допустимыми являются все разделители внутри сегментов, которые указаны в стандарте RFC 3986: «!», «&», «'», «+», «*», «$», «(», «)», «,», «;», «=». Также для сегментов запрос и фрагмент допустимы «/», «?».

Символы, которые являются разделителями сегментов, не меняются «:» / «/» / «?» / «#» / «[» / «]» / «@». Не меняются разрешенные к использованию во всех частях URL-адреса символы: «-» / «.» / «_» / «~».

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

Примеры процентного кодирования:

Пример IDN-кодирования:

Объектная модель

Теперь, когда мы знаем, как устроено клиент-серверное взаимодействие с использованием HTTP-запросов, можно наложить на эту схему объектную модель, которую предоставляет «1С:Шина».

В качестве основы всей модели выступает тип КлиентHttp. Экземпляр этого типа может быть получен из свойства глобального контекста КлиентHttp. Он содержит базовые параметры HTTP-взаимодействия.

В тоже время, нам может потребоваться в один момент времени работать с несколькими серверами. Поэтому экземпляр типа КлиентHttp может создавать новые экземпляры типа КлиентHttp, которые будут получать все параметры из своего базового экземпляра, кроме некоторых параметров, которые можно изменить при создании копии. Другими словами - будет создавать измененная копия родительского экземпляра. Говоря про такую возможность (создание нового экземпляра на базе существующего) мы будет говорить, что существующий экземпляр выступает в роли фабрики. Экземпляр типа КлиентHttp, который предоставляет «1С:Шина», будем называть базовым экземпляром.

пер МойКлиент = КлиентHttp.СБазовымUrl("http://example.com")

знч ДоверенныеСертификаты = новый ХранилищеPkcs12()
ДоверенныеСертификаты.ДобавитьСертификат("1", СертификатГост)
 
исп Ответ = КлиентHttp.СКриптоПроTls()
            .СПараметрамиЗащиты(новый ПараметрыЗащищенногоСоединения(ДоверенныеСертификаты))          
            .СТаймаутомЗапроса(15с)
            .ЗапросGet("https://website-address.ru")
            .Выполнить()

Теперь мы имеем экземпляр, который выступает в роли клиента и нам необходимо выполнить запрос к серверу, который мы указали при создании клиента. Для этого мы от экземпляра типа КлиентHttp получим экземпляр типа ЗапросHttp.

Тип ЗапросHttp служит для формирования запроса от клиента серверу и получения ответа от сервера. Ответ от сервера поступает в виде экземпляра типа ОтветHttp.

Если мы хотим выполнить запрос, описанный в стандарте HTTP 1.1, то можно использовать метод КлиентHttp.ЗапросGet() и аналогичные ему (все поддерживаемые имена HTTP-методов перечислены в таблице Методы HTTP-запроса). В этом случае в метод необходимо передать только URI на сервере, к которому будет применяться запрос.

пер Запрос = МойКлиент.ЗапросGet("/path/resource?param1=value1&param2=value")
пер Запрос = МойКлиент.СоздатьЗапрос("GET", "/path/resource?param1=value1&param2=value")

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

Также ЗапросHttp позволяет работать как с одним заголовком (методы ДобавитьЗаголовок()/УстановитьЗаголовок()/УдалитьЗаголовок()), так и с несколькими заголовками сразу (методы ДобавитьЗаголовки()/УстановитьЗаголовки()/ОчиститьЗаголовки()). С помощью методов добавления/установки заголовков нельзя изменять заголовки Content-Type и Transfer-Encoding. Для изменения заголовка Content-Type предназначен метод УстановитьТипСодержимого(). Для установки информации о клиентском приложении (заголовок User-Agent) предназначен метод УстановитьUserAgent().

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