модуль Net

Константы

HTTPGatewayTimeOut

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

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

Этот класс также включает (косвенно) модуль 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 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. См. иерархию классов ответов Response.

В частности, класс 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 с URL HTTPS. Net::HTTP автоматически включает проверку TLS, если у объекта URI есть схема ‘https’ URI:

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' к новому объекту запроса request object:

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

Это запрашивает у сервера сжатие тела ответа, если оно есть; сервер не обязан это делать.

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

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

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

Что здесь

Сначала, что где-то еще. Class Net::HTTP:

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

Это категоризированный обзор методов и атрибутов.

Объекты Net::HTTP

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

Сессии

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

Соединения

:continue_timeout: Возвращает таймаут продолжения.
#continue_timeout=: Устанавливает таймаут продолжения в секундах.
:keep_alive_timeout: Возвращает таймаут поддержания соединения.
:keep_alive_timeout=: Устанавливает таймаут поддержания соединения.
: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.
:ca_file=: Устанавливает путь к файлу сертификата CA.
:ca_path: Возвращает путь к каталогу CA, содержащему сертификационные файлы.
:ca_path=: Устанавливает путь к каталогу CA, содержащему сертификационные файлы.
: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–2024 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.

модуль Net

О примерах

Стратегии

URI

Схемы

Имена хостов

Пути

Запросы

Фрагменты

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

Сессии HTTP

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

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

Сессия одного запроса

HTTP-запросы и ответы

Следование перенаправлению

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

Потоковое чтение тела ответа

HTTPS

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

Прокси с использованием аргумента p_addr в качестве строки

Прокси с использованием ‘ENV['http_proxy']’

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

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

Что здесь

Объекты Net::HTTP

Сессии

Соединения

Запросы

Ответы

Прокси

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

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

Версия HTTP

Отладка

Прокси с использованием аргумента `p_addr` в качестве строки

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