Функция HTTP_ЗАПРОС
Функция HTTP_ЗАПРОС позволяет осуществить взаимодействие с удаленным http-сервером.
ФУНКЦИЯ ТИП_ЛОГИКА: HTTP_ЗАПРОС(ТИП_СТРОКА: url, файл_вход, файл_выход
[; ТИП_СПИСОК: опции [; ТИП_СПИСОК: заголовки]])
Параметры
- url
- URL http сервера. Возможно указание протокола (http или https; по умолчанию используется http) и порта (для http по умолчанию 80 – стандартный для этого протокола порт). Например, "https://server.example.net/RPC:8080".
При необходимости передачи длинной строки (длина которой превышает 255 символов) следует использовать объект типа список. - файл_вход
- Файл тела HTTP-запроса. Для запросов типа GET, DELETE и др. может не указываться.
Для случая XML RPC – ХML файл входных параметров. За более подробной информацией о формате входных параметров обратитесь к спецификации XMLRPC и к документации к серверу, запрос к которому вы делаете.
Для отправки полей формы как multipart/form-data (аналог curl --form) в параметре указывается "*", а данные для формирования тела запроса берутся из опций form (см. ниже).
Вместо имени файла может указываться имя пользовательского списка атрибутов, начинающееся с символа & или $ (например, "$http_input"). С помощью функции УСТ_СПИСОК_АТРИБУТОВ выполняется задание входных данных в виде объекта список. Строки указанного списка соединяются без разделителя. Текст в списке содержится в кодировке ANSI. При добавлении в HTTP запрос входные данные перекодируется в UTF-8. - файл_выход
- Файл ответа HTTP-сервера.
Для случая XML RPC – XML файл выходных параметров или XML RPC ошибки.
Вместо имени файла может указываться имя пользовательского списка атрибутов, начинающееся с символа & или $ (например, "$http_output"). В этом случае предполагается, что ответ от сервера приходит в кодировке UTF-8. Для помещения текста в список выполняется перекодирование из UTF-8 в ANSI. Следует иметь в виду, что не все Unicode-символы имеют соответствие в ANSI кодировке. С помощью функции СПИСОК_АТРИБУТОВ выполняется получение выходных данных в виде объекта список. В список заносятся фрагменты данных про 255 символов и остаток в конце. - опции
- Необязательный параметр. Список опций HTTP-запроса.
Опции указываются в форме: <имя опции>=<значение>
Поддерживаются следующие опции:verb – Действие HTTP-запроса. Поддерживаются основные действия GET, POST, PUT, DELETE (набор для REST). По умолчанию – нужный для XML-RPC POST. Также можно указать другое действие (custom request). getdata – Флаг true/false отправки входного файла как тела GET-запроса. По умолчанию false. login – Имя пользователя для запросов, требующих авторизации на сервере (аналогично curl --user "login:password"). password – Пароль пользователя, имя которого указано в опции login. connect_timeout – Таймаут установления соединения в миллисекундах. По умолчанию 20 секунд. data_timeout – Таймаут получения данных в миллисекундах. По умолчанию 20 секунд. debug – Флаг true/false вывода расширенной диагностики в окно отладочных сообщений, указанный список атрибутов или файл (аналогично curl --verbose). По умолчанию false. Способ вывода диагностической информации определяется параметрами trace_type, trace_time и log. trace_type – Позволяет указать режим вывода отладочной информации. Этот параметр учитывается только при указании debug=true. - Значение bin применяется для трассировки двоичных данных (аналогично curl --trace). Двоичные данные выводятся столбиками шестнадцатеричных значений байтов (как в hex-редакторах файлов).
- Значение ascii применяется для трассировки текстовых данных (аналогично curl --trace-ascii). Не ASCII символы при выводе заменяются точкой.
- По умолчанию используется режим диагностики и вывод заголовков (аналогично curl --verbose). Для входных и выходных данных в этом режиме выводится только размер в байтах.
trace_time – Вывод времени в начале строк отладочных сообщений (аналогично curl --trace-time). По умолчанию false. Этот параметр учитывается только при указании debug=true. log – Имя лог-файла для записи расширенной диагностики (опция debug). При указании имени файла вывод в окно отладочных сообщений не выполняется. Вместо имени файла может указываться имя пользовательского списка атрибутов, начинающееся с символа & или $. Этот параметр учитывается только при указании debug=true. proxy_address – Позволяет указать адрес и порт прокси-сервера для доступа в Интернет. В адресе прокси надо указать протокол: http или https, ip-адрес и номер порта. Например, https://127.0.0.1:8080. Если этот параметр не указан или адрес - пустая строка, то выполняется поиск глобальной настройки прокси. Глобально указать параметры прокси-сервера можно в файле gnet.ini (см. ниже). proxy_login – Имя пользователя прокси-сервера. Если прокси не использует авторизацию, то этот параметр не указывается. proxy_password – Пароль пользователя прокси-сервера. Если прокси не использует авторизацию, то этот параметр не указывается. ignore_offline – Флаг true/false позволяет игнорировать проверку признака подключения к Интернету по мнению Windows. По умолчанию false. Для выполнения http-запросов к серверу на localhost или в локальной сети без выхода в Интернет необходимо указать ignore_offline=true. Эта возможность может быть полезна для тестирования и отладки. no_cookies – Флаг true/false позволяет запретить использование cookies. По умолчанию false, т.е. cookies разрешены. no_redirect – Флаг true/false позволяет запретить перенаправление запросов. По умолчанию false, т.е. перенаправление запросов разрешено. fail_on_http_errors – Флаг true/false позволяет включить режим интерпретации кодов ответа сервера >=400 как ошибок запроса. По умолчанию false, т.е. используется толерантное отношение к кодам ответа сервера. form – Описание поля формы аналогично команде curl --form. Для простых параметров "form=param=value". Для загрузки файлов "form=logo=@c:\temp\iblogo.jpg". См. другие подробности синтаксиса и дополнительные параметры в документции curl для команды --form. - заголовки
- Необязательный параметр. Список заголовков HTTP-запроса. Например, значение для заголовка Content-Type.
Возвращаемое значение
ДА – при успешном выполнении HTTP-запроса. При недоступности сервера или другой сетевой ошибке функция возвращает НЕТ. Текст ошибки записывается в файл error.log. Дополнительная диагностика может выводится в окно отладки (если включена соответствующая опция в настройках программы) при указании опции "debug=true".
Для случая XML RPC.
ДА – при успешном получении ответного XML файла от сервера. При недоступности сервера или другой сетевой ошибке функция возвращает НЕТ. Следует заметить, что возвращаемый результат говорит об успешности именно получения ответа; в ответе может находится структура <fault>, но в этом случае функция все равно вернет ДА.
Дополнительная информация об ошибках.
С помощью функции АТРИБУТ с параметрами "http_code", "http_response" и "http_error" можно получить дополнительную информацию об ошибке предшествовавшего http-запроса.
Функция АТРИБУТ все значения возвращает в строковом виде.
Параметр "http_code" соответствует коду ошибки библиотеки gnet3.dll. Ниже приведены некоторые коды ошибок:
- 1 – ошибка выполнения запроса (включая сетевые ошибки), описание ошибки можно получить через параметр "http_error";
- 4 – отмена пользователем;
- 5 – таймаут соединения или получения данных (по умолчанию 20 сек.);
- 7 – оффлайн, Windows сообщает, что нет подключения к Интернету, попытка выполнить запрос не предпринимается.
Параметр "http_response" – код ответа сервера, например 404, если указанная в URL страница не найдена. Если до ответа сервера дело не дошло, то возвращается 0. Параметр "http_error" позволяет получить текстовое сообщение ошибки. Для ошибок типа таймаут и оффлайн текстовое сообщение не заполняется. Это же текстовое сообщение записывается в файл error.log.
Глобальная настройка прокси-сервера.
Чтобы не указывать параметры прокси-сервера в каждом запросе, можно задать их глобально в специальном файле. Для этого нужно поместить файл gnet.ini в одну папку с gnet3.dll (или создать папку config на уровень выше и положить его туда – это место проверяется во вторую очередь). В файле в секции [proxy] нужно указать адрес прокси, логин и пароль:
gnet.ini
[proxy] address=proxy_address login=proxy_login password=proxy_password
В адресе прокси надо указать протокол: http или https, ip-адрес и номер порта. Например, https://127.0.0.1:8080. Если прокси не использует авторизацию, то параметры login и password не указываются или указываются пустыми строками.