HTTP-запросы

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

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

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

Здесь:

• метод — действие, которое сервер должен выполнить с ресурсом, указанным с помощью URI. Состоит из любых символов US-ASCII (кроме управляющих символов и разделителей). Название метода может быть любым, но рекомендуется использовать методы, описанные в спецификации HTTP 1.1 (RFC 2616).
• uri — путь к конкретному ресурсу на сервере. Запрос будет выполняться над данными, которые адресуются указанным URI. Если используемый в запросе метод не требует указания ресурса, вместо URI пишется символ «*».
• версия — версия HTTP-протокола. В настоящий момент это версия 1.1.

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

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

«1С:Исполнитель» может выступать только в качестве клиента для протокола HTTP.

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

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

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

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

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

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

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

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

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

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

http://xn--d1acpjx3f.xn--p1ai — адрес запроса после преобразования.

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

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

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

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

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

«1С:Исполнитель» поддерживает односторонний (с аутентификацией сервера) и двусторонний (с аутентификацией сервера и клиента) TLS.

Если вы хотите установить защищенное HTTPS-соединение для отправки запросов к серверу, использующему протокол TLS с шифрованием по ГОСТ, используйте метод СКриптоПроTls(). Для работы этого метода убедитесь, что у вас установлены модули КриптоПро.

Пример использования двустороннего TLS ГОСТ

знч ДоверенныеСертификаты = новый ХранилищеJks()
ДоверенныеСертификаты.ДобавитьСертификат(
    "demo",
    новый ЦифровойСертификат(Ресурс{demo.cer}.ОткрытьПотокЧтения().ПрочитатьКакБайты())
)
ДоверенныеСертификаты.ДобавитьСертификат(
    "demo.CA",
    новый ЦифровойСертификат(Ресурс{demo.CA.cer}.ОткрытьПотокЧтения().ПрочитатьКакБайты())
)

знч Параметры = новый ПараметрыЗащищенногоСоединения(
    ДоверенныеСертификаты,
    новый ХранилищеКриптоПро(),
    "key-password"
)

знч Клиент = КлиентHttp.СКриптоПроTls()
                       .СПараметрамиЗащиты(Параметры)

знч Запрос = Клиент.ЗапросGet("https://website-address.ru")
                   .ДобавитьЗаголовок("Заголовок", "Значение")

исп Ответ = Запрос.Выполнить()

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

Если вы хотите выполнить запрос, описанный в стандарте HTTP 1.1, то можете использовать метод КлиентHttp.ЗапросGet() или аналогичные ему (все поддерживаемые имена 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, который содержит полученные от сервера данные.