модуль Net

Константы

HTTPGatewayTimeOut

Класс ответа для ответов Gateway Timeout (код состояния 504).

Сервер выступал в роли шлюза или прокси и не получил своевременный ответ от вышестоящего сервера.

Этот класс также включает (косвенно) модуль Net::HTTPHeader, который предоставляет доступ к методам получения заголовков.

Ссылки:

HTTPMovedTemporarily

Класс ответа для ответов Found (код состояния 302).

Ответ Found указывает, что клиенту следует перейти по другому URL.

Ссылки:

HTTPMultipleChoice

Класс ответа для ответов Multiple Choices (код состояния 300).

Ответ Multiple Choices указывает, что сервер предлагает несколько вариантов ресурса, из которых клиент может выбрать.

Ссылки:

HTTPRequestEntityTooLarge

Класс ответа для ответов Payload Too Large (код состояния 413).

Размер запроса превышает тот, который сервер готов или способен обработать.

Ссылки:

HTTPRequestTimeOut

Класс ответа для ответов Request Timeout (код состояния 408).

Время ожидания запроса на сервере истекло.

Ссылки:

HTTPRequestURITooLarge

Класс ответа для ответов URI Too Long (код состояния 414).

Предоставленный URI был слишком длинным для обработки сервером.

Ссылки:

HTTPRequestURITooLong

Класс ответа для ответов URI Too Long (код состояния 414).

Предоставленный URI был слишком длинным для обработки сервером.

Ссылки:

HTTPRequestedRangeNotSatisfiable

Класс ответа для ответов Range Not Satisfiable (код состояния 416).

Тип мультимедиа сущности запроса не поддерживается сервером или ресурсом.

Ссылки:

HTTPSession

Класс Net::HTTP предоставляет богатую библиотеку, реализующую клиент в модели клиент-сервер, использующей протокол запрос-ответ HTTP. Сведения об HTTP см. здесь:

Об этих примерах

Предполагается, что в примерах здесь подключен net/http (который также требует uri):

require 'net/http'

Во многих примерах кода используются следующие тестовые сайты:

В некоторых примерах также предполагается наличие следующих переменных:

uri = URI('https://jsonplaceholder.typicode.com/')
uri.freeze # Examples may not modify.
hostname = uri.hostname # => "jsonplaceholder.typicode.com"
path = uri.path         # => "/"
port = uri.port         # => 443

Таким образом, тестовые запросы можно записать так:

Net::HTTP.get(uri)
Net::HTTP.get(hostname, '/index.html')
Net::HTTP.start(hostname) do |http|
  http.get('/todos/1')
  http.get('/todos/2')
end

В примере, где требуется изменить URI, сначала создается копия uri, а затем изменяется эта копия:

_uri = uri.dup
_uri.path = '/todos/1'

Стратегии

Если вы собираетесь выполнить лишь несколько GET-запросов, рассмотрите возможность использования OpenURI.

Если вы собираетесь выполнить лишь несколько запросов разных типов, рассмотрите возможность использования различных удобных методов класса. Каждый из следующих методов автоматически открывает и закрывает сеанс, в котором отправляется один запрос:

# Return string response body.
Net::HTTP.get(hostname, path)
Net::HTTP.get(uri)

# Write string response body to $stdout.
Net::HTTP.get_print(hostname, path)
Net::HTTP.get_print(uri)

# Return response as Net::HTTPResponse object.
Net::HTTP.get_response(hostname, path)
Net::HTTP.get_response(uri)
data = '{"title": "foo", "body": "bar", "userId": 1}'
Net::HTTP.post(uri, data)
params = {title: 'foo', body: 'bar', userId: 1}
Net::HTTP.post_form(uri, params)
data = '{"title": "foo", "body": "bar", "userId": 1}'
Net::HTTP.put(uri, data)

Если важна производительность, рассмотрите возможность использования сеансов, которые снижают накладные расходы на запросы. В этом сеансе выполняется несколько запросов с использованием методов HTTP и методов WebDAV:

Net::HTTP.start(hostname) do |http|
  # Session started automatically before block execution.
  http.get(path)
  http.head(path)
  body = 'Some text'
  http.post(path, body)  # Can also have a block.
  http.put(path, body)
  http.delete(path)
  http.options(path)
  http.trace(path)
  http.patch(path, body) # Can also have a block.
  http.copy(path)
  http.lock(path, body)
  http.mkcol(path, body)
  http.move(path)
  http.propfind(path, body)
  http.proppatch(path, body)
  http.unlock(path, body)
  # Session finished automatically at block exit.
end

Упомянутые выше методы — это методы-обертки, которые благодаря небольшому числу аргументов обеспечивают минимальный контроль над запросами. Для более гибкого управления рассмотрите возможность использования объектов запросов.

URI

В интернете URI (универсальный идентификатор ресурса) — это строка, идентифицирующая определенный ресурс. Она состоит из некоторых или всех следующих частей: схема, имя хоста, путь, запрос и фрагмент; см. синтаксис URI.

Объект Ruby URI::Generic представляет интернет-URI. Среди прочего, он предоставляет методы scheme, hostname, path, query и fragment.

Схемы

У интернет-URI есть схема.

В Net::HTTP поддерживаются две схемы: 'https' и 'http':

uri.scheme                       # => "https"
URI('http://example.com').scheme # => "http"

Имена хостов

Имя хоста идентифицирует сервер (хост), которому можно отправлять запросы:

hostname = uri.hostname # => "jsonplaceholder.typicode.com"
Net::HTTP.start(hostname) do |http|
  # Some HTTP stuff.
end

Пути

Путь, относящийся к конкретному хосту, идентифицирует ресурс на этом хосте:

_uri = uri.dup
_uri.path = '/todos/1'
hostname = _uri.hostname
path = _uri.path
Net::HTTP.get(hostname, path)

Запросы

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

_uri = uri.dup
params = {userId: 1, completed: false}
_uri.query = URI.encode_www_form(params)
_uri # => #<URI::HTTPS https://jsonplaceholder.typicode.com?userId=1&completed=false>
Net::HTTP.get(_uri)

Фрагменты

Фрагмент URI не влияет на работу Net::HTTP: возвращаются одни и те же данные независимо от того, включен ли фрагмент.

Заголовки запросов

Заголовки запросов можно использовать для передачи хосту дополнительной информации, подобно аргументам, передаваемым при вызове метода; каждый заголовок представляет собой пару имя/значение.

У каждого метода Net::HTTP, отправляющего запрос хосту, есть необязательный аргумент headers, в котором заголовки представлены в виде хеша пар имя поля/значение:

headers = {Accept: 'application/json', Connection: 'Keep-Alive'}
Net::HTTP.get(uri, headers)

Списки стандартных и часто используемых полей запроса см. в разделе Поля запроса. Хост также может принимать другие пользовательские поля.

Сеансы HTTP

Сеанс — это соединение между сервером (хостом) и клиентом, которое:

Начинается методом экземпляра Net::HTTP#start.
Может содержать любое количество запросов.
Завершается методом экземпляра Net::HTTP#finish.

Примеры сеансов см. в разделе Стратегии.

Сеанс с использованием Net::HTTP.start

Если вам нужно отправить много запросов одному хосту (и порту), рассмотрите возможность использования метода класса Net::HTTP.start с блоком; метод автоматически управляет сеансом следующим образом:

Вызывает start перед выполнением блока.
Выполняет блок.
Вызывает finish после выполнения блока.

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

Методы HTTP:
- get, request_get: GET.
- head, request_head: HEAD.
- post, request_post: POST.
- delete: DELETE.
- options: OPTIONS.
- trace: TRACE.
- patch: PATCH.
Методы WebDAV:
- copy: COPY.
- lock: LOCK.
- mkcol: MKCOL.
- move: MOVE.
- propfind: PROPFIND.
- proppatch: PROPPATCH.
- unlock: UNLOCK.

Сеанс с использованием Net::HTTP.start и Net::HTTP.finish

Управлять сеансом вручную можно с помощью методов start и finish:

http = Net::HTTP.new(hostname)
http.start
http.get('/todos/1')
http.get('/todos/2')
http.delete('/posts/1')
http.finish # Needed to free resources.

Сеанс с одним запросом

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

Создают объект HTTP.
Начинают сеанс.
Отправляют один запрос.
Завершают сеанс.
Уничтожают объект.

Методы, отправляющие GET-запросы:

::get: Возвращает строку с телом ответа.
::get_print: Записывает строку с телом ответа в $stdout.
::get_response: Возвращает объект Net::HTTPResponse.

Методы, отправляющие POST-запросы:

::post: Отправляет данные хосту.
::post_form: Отправляет хосту данные формы.

Запросы и ответы HTTP

Многие из описанных выше методов — это методы-обертки, каждый из которых отправляет запрос и возвращает строку, не используя напрямую объекты Net::HTTPRequest и Net::HTTPResponse.

Однако можно напрямую создать объект запроса, отправить запрос и получить объект ответа; см.:

Перенаправления

Каждый возвращаемый ответ является экземпляром подкласса Net::HTTPResponse. См. иерархию классов ответов.

В частности, класс Net::HTTPRedirection является родительским для всех классов перенаправлений. Это позволяет составить оператор case для корректной обработки перенаправлений:

def fetch(uri, limit = 10)
  # You should choose a better exception.
  raise ArgumentError, 'Too many HTTP redirects' if limit == 0

  res = Net::HTTP.get_response(URI(uri))
  case res
  when Net::HTTPSuccess     # Any success class.
    res
  when Net::HTTPRedirection # Any redirection class.
    location = res['Location']
    warn "Redirected to #{location}"
    fetch(location, limit - 1)
  else                      # Any other class.
    res.value
  end
end

fetch(uri)

Базовая аутентификация

Базовая аутентификация выполняется в соответствии с RFC2617:

req = Net::HTTP::Get.new(uri)
req.basic_auth('user', 'pass')
res = Net::HTTP.start(hostname) do |http|
  http.request(req)
end

Потоковая передача тел ответов

По умолчанию Net::HTTP считывает весь ответ в память. Если вы работаете с большими файлами или хотите реализовать индикатор выполнения, можно вместо этого передавать тело ответа непосредственно в IO.

Net::HTTP.start(hostname) do |http|
  req = Net::HTTP::Get.new(uri)
  http.request(req) do |res|
    open('t.tmp', 'w') do |f|
      res.read_body do |chunk|
        f.write chunk
      end
    end
  end
end

HTTPS

HTTPS включается для соединения HTTP с помощью Net::HTTP#use_ssl=:

Net::HTTP.start(hostname, :use_ssl => true) do |http|
  req = Net::HTTP::Get.new(uri)
  res = http.request(req)
end

Если же вам нужно просто отправить GET-запрос, можно передать объект URI с HTTPS URL. Net::HTTP автоматически включает проверку TLS, если объект URI использует схему URI ‘https’:

uri # => #<URI::HTTPS https://jsonplaceholder.typicode.com/>
Net::HTTP.get(uri)

Прокси-сервер

У объекта HTTP может быть прокси-сервер.

Создать объект HTTP с прокси-сервером можно с помощью метода Net::HTTP.new или метода Net::HTTP.start.

Прокси можно задать аргументом p_addr или переменной окружения 'http_proxy'.

Использование аргумента `p_addr` в виде строки для прокси

Если аргумент p_addr — это строка с именем хоста, возвращаемый http будет использовать указанный хост в качестве прокси:

http = Net::HTTP.new(hostname, nil, 'proxy.example')
http.proxy?          # => true
http.proxy_from_env? # => false
http.proxy_address   # => "proxy.example"
# These use default values.
http.proxy_port      # => 80
http.proxy_user      # => nil
http.proxy_pass      # => nil

Также можно указать порт, имя пользователя и пароль прокси:

http = Net::HTTP.new(hostname, nil, 'proxy.example', 8000, 'pname', 'ppass')
# => #<Net::HTTP jsonplaceholder.typicode.com:80 open=false>
http.proxy?          # => true
http.proxy_from_env? # => false
http.proxy_address   # => "proxy.example"
http.proxy_port      # => 8000
http.proxy_user      # => "pname"
http.proxy_pass      # => "ppass"

Использование ‘`ENV['http_proxy']`’ для прокси

Если переменной окружения 'http_proxy' присвоена строка URI, возвращаемый http будет использовать сервер, указанный в этом URI, в качестве прокси; обратите внимание, что строка URI должна содержать протокол, например 'http' или 'https':

ENV['http_proxy'] = 'http://example.com'
http = Net::HTTP.new(hostname)
http.proxy?          # => true
http.proxy_from_env? # => true
http.proxy_address   # => "example.com"
# These use default values.
http.proxy_port      # => 80
http.proxy_user      # => nil
http.proxy_pass      # => nil

Строка URI может содержать имя пользователя, пароль и номер порта прокси:

ENV['http_proxy'] = 'http://pname:ppass@example.com:8000'
http = Net::HTTP.new(hostname)
http.proxy?          # => true
http.proxy_from_env? # => true
http.proxy_address   # => "example.com"
http.proxy_port      # => 8000
http.proxy_user      # => "pname"
http.proxy_pass      # => "ppass"

Фильтрация прокси

С помощью метода Net::HTTP.new (но не Net::HTTP.start) можно использовать аргумент p_no_proxy для фильтрации прокси:

Отклонить определенный адрес:

http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'proxy.example')
http.proxy_address # => nil

Отклонить определенные домены или поддомены:

http = Net::HTTP.new('example.com', nil, 'my.proxy.example', 8000, 'pname', 'ppass', 'proxy.example')
http.proxy_address # => nil

Отклонить определенные сочетания адреса и порта:

http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'proxy.example:1234')
http.proxy_address # => "proxy.example"

http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'proxy.example:8000')
http.proxy_address # => nil

Отклонить список значений перечисленных выше типов, разделенных запятыми:

http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'my.proxy,proxy.example:8000')
http.proxy_address # => nil

http = Net::HTTP.new('example.com', nil, 'my.proxy', 8000, 'pname', 'ppass', 'my.proxy,proxy.example:8000')
http.proxy_address # => nil

Сжатие и распаковка

Net::HTTP не сжимает тело запроса перед отправкой.

По умолчанию Net::HTTP добавляет заголовок 'Accept-Encoding' в новый объект запроса:

Net::HTTP::Get.new(uri)['Accept-Encoding']
# => "gzip;q=1.0,deflate;q=0.6,identity;q=0.3"

Этот заголовок просит сервер сжать тело ответа с помощью zip, если оно есть; сервер не обязан это делать.

Net::HTTP не распаковывает тело ответа автоматически, если в ответе есть заголовок 'Content-Range'.

В остальных случаях распаковка (или ее отсутствие) зависит от значения заголовка Content-Encoding:

'deflate', 'gzip' или 'x-gzip': распаковывает тело и удаляет заголовок.
'none' или 'identity': не распаковывает тело, но удаляет заголовок.
Любое другое значение: оставляет тело и заголовок без изменений.

Что здесь описано

Сначала рассмотрим, что описано в других разделах. Класс Net::HTTP:

Наследуется от класса Object.

Ниже приведен обзор методов и атрибутов, сгруппированных по категориям.

Объекты Net::HTTP

::new: Создает новый экземпляр.
#inspect: Возвращает строковое представление self.

Сеансы

::start: Начинает новый сеанс в новом объекте Net::HTTP.
#started?: Возвращает признак того, что сеанс активен.
#finish: Завершает активный сеанс.
#start: Начинает новый сеанс в существующем объекте Net::HTTP (self).

Соединения

:continue_timeout: Возвращает тайм-аут ожидания continue.
#continue_timeout=: Задает тайм-аут ожидания continue в секундах.
:keep_alive_timeout: Возвращает тайм-аут keep-alive.
:keep_alive_timeout=: Задает тайм-аут keep-alive.
:max_retries: Возвращает максимальное число повторных попыток.
#max_retries=: Задает максимальное число повторных попыток.
:open_timeout: Возвращает тайм-аут открытия соединения.
:open_timeout=: Задает тайм-аут открытия соединения.
:read_timeout: Возвращает тайм-аут чтения.
:read_timeout=: Задает тайм-аут чтения.
:ssl_timeout: Возвращает тайм-аут SSL.
:ssl_timeout=: Задает тайм-аут SSL.
:write_timeout: Возвращает тайм-аут записи.
write_timeout=: Задает тайм-аут записи.

Запросы

::get: Отправляет GET-запрос и возвращает строку с телом ответа.
::get_print: Отправляет GET-запрос и записывает строку с телом ответа в $stdout.
::get_response: Отправляет GET-запрос и возвращает объект ответа.
::post_form: Отправляет POST-запрос с данными формы и возвращает объект ответа.
::post: Отправляет POST-запрос с данными и возвращает объект ответа.
::put: Отправляет PUT-запрос с данными и возвращает объект ответа.
#copy: Отправляет COPY-запрос и возвращает объект ответа.
#delete: Отправляет DELETE-запрос и возвращает объект ответа.
#get: Отправляет GET-запрос и возвращает объект ответа.
#head: Отправляет HEAD-запрос и возвращает объект ответа.
#lock: Отправляет LOCK-запрос и возвращает объект ответа.
#mkcol: Отправляет MKCOL-запрос и возвращает объект ответа.
#move: Отправляет MOVE-запрос и возвращает объект ответа.
#options: Отправляет OPTIONS-запрос и возвращает объект ответа.
#patch: Отправляет PATCH-запрос и возвращает объект ответа.
#post: Отправляет POST-запрос и возвращает объект ответа.
#propfind: Отправляет PROPFIND-запрос и возвращает объект ответа.
#proppatch: Отправляет PROPPATCH-запрос и возвращает объект ответа.
#put: Отправляет PUT-запрос и возвращает объект ответа.
#request: Отправляет запрос и возвращает объект ответа.
#request_get: Отправляет GET-запрос и создает объект ответа; если передан блок, вызывает его с этим объектом, иначе возвращает объект.
#request_head: Отправляет HEAD-запрос и создает объект ответа; если передан блок, вызывает его с этим объектом, иначе возвращает объект.
#request_post: Отправляет POST-запрос и создает объект ответа; если передан блок, вызывает его с этим объектом, иначе возвращает объект.
#send_request: Отправляет запрос и возвращает объект ответа.
#trace: Отправляет TRACE-запрос и возвращает объект ответа.
#unlock: Отправляет UNLOCK-запрос и возвращает объект ответа.

Ответы

:close_on_empty_response: Возвращает признак того, что соединение следует закрыть при пустом ответе.
:close_on_empty_response=: Задает, следует ли закрывать соединение при пустом ответе.
:ignore_eof: Возвращает признак того, что следует игнорировать конец файла при чтении тела ответа с заголовками Content-Length.
:ignore_eof=: Задает, следует ли игнорировать конец файла при чтении тела ответа с заголовками Content-Length.
:response_body_encoding: Возвращает кодировку, используемую для тела ответа.
#response_body_encoding=: Задает кодировку тела ответа.

Прокси

:proxy_address: Возвращает адрес прокси.
:proxy_address=: Задает адрес прокси.
::proxy_class?: Возвращает признак того, что self является классом прокси.
#proxy?: Возвращает признак того, что у self есть прокси.
#proxy_address: Возвращает адрес прокси.
#proxy_from_env?: Возвращает признак того, что прокси задается переменной окружения.
:proxy_from_env=: Задает, следует ли брать прокси из переменной окружения.
:proxy_pass: Возвращает пароль прокси.
:proxy_pass=: Задает пароль прокси.
:proxy_port: Возвращает порт прокси.
:proxy_port=: Задает порт прокси.
#proxy_user: Возвращает имя пользователя прокси.
:proxy_user=: Задает имя пользователя прокси.

Безопасность

:ca_file: Возвращает путь к файлу сертификатов центра сертификации.
:ca_file=: Задает путь к файлу сертификатов центра сертификации.
:ca_path: Возвращает путь к каталогу центра сертификации, содержащему файлы сертификатов.
:ca_path=: Задает путь к каталогу центра сертификации, содержащему файлы сертификатов.
:cert: Возвращает объект OpenSSL::X509::Certificate, используемый для аутентификации клиента.
:cert=: Задает объект OpenSSL::X509::Certificate, используемый для аутентификации клиента.
:cert_store: Возвращает X509::Store, используемый для проверки сертификата узла.
:cert_store=: Задает X509::Store, используемый для проверки сертификата узла.
:ciphers: Возвращает доступные шифры SSL.
:ciphers=: Задает доступные шифры SSL.
:extra_chain_cert: Возвращает дополнительные сертификаты X509, добавляемые в цепочку сертификатов.
:extra_chain_cert=: Задает дополнительные сертификаты X509, добавляемые в цепочку сертификатов.
:key: Возвращает объект OpenSSL::PKey::RSA или OpenSSL::PKey::DSA.
:key=: Задает объект OpenSSL::PKey::RSA или OpenSSL::PKey::DSA.
:max_version: Возвращает максимальную версию SSL.
:max_version=: Задает максимальную версию SSL.
:min_version: Возвращает минимальную версию SSL.
:min_version=: Задает минимальную версию SSL.
#peer_cert: Возвращает цепочку сертификатов X509 для узла на другом конце сокета сеанса.
:ssl_version: Возвращает версию SSL.
:ssl_version=: Задает версию SSL.
#use_ssl=: Задает, следует ли использовать Transport Layer Security в новом сеансе.
#use_ssl?: Возвращает признак того, что self использует SSL.
:verify_callback: Возвращает функцию обратного вызова для проверки сертификата сервера.
:verify_callback=: Задает функцию обратного вызова для проверки сертификата сервера.
:verify_depth: Возвращает максимальную глубину проверки цепочки сертификатов.
:verify_depth=: Задает максимальную глубину проверки цепочки сертификатов.
:verify_hostname: Возвращает флаги проверки сертификата сервера в начале сеанса SSL/TLS.
:verify_hostname=: Задает флаги проверки сертификата сервера в начале сеанса SSL/TLS.
:verify_mode: Возвращает флаги проверки сертификата сервера в начале сеанса SSL/TLS.
:verify_mode=: Задает флаги проверки сертификата сервера в начале сеанса SSL/TLS.

Адреса и порты

:address: Возвращает строку с именем хоста или IP-адресом хоста.
::default_port: Возвращает целое число 80 — порт по умолчанию для запросов HTTP.
::http_default_port: Возвращает целое число 80 — порт по умолчанию для запросов HTTP.
::https_default_port: Возвращает целое число 443 — порт по умолчанию для HTTPS-запросов.
#ipaddr: Возвращает IP-адрес соединения.
#ipaddr=: Задает IP-адрес соединения.
:local_host: Возвращает строку с локальным хостом, используемым для установки соединения.
:local_host=: Задает строку с локальным хостом, используемым для установки соединения.
:local_port: Возвращает целое число — локальный порт, используемый для установки соединения.
:local_port=: Задает целое число — локальный порт, используемый для установки соединения.
:port: Возвращает целое число — номер порта.

Версия HTTP

::version_1_2? (имеет псевдоним ::version_1_2): Возвращает true; сохранен для совместимости.

Отладка

#set_debug_output: Задает поток вывода для отладки.

Ruby Core © 1993–2025 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.