Spec-Zone.ru › Ruby 4.0
  1. Net::
  2. HTTP

class Net::HTTP

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

  • Протокол передачи гипертекста.

  • Технический обзор.

Об примерах

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

require 'net/http'

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

  • jsonplaceholder.typicode.com.

  • example.com.

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

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::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 с URL HTTPS. 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"

Это запрашивает у сервера кодирование тела ответа с помощью gzip, если оно есть; сервер не обязан выполнять это требование.

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_timeout=: задает тайм-аут ожидания продолжения в секундах.

  • :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.

  • :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: задает поток вывода для отладки.

Атрибуты

default_configuration [RW]

Позволяет задать конфигурацию по умолчанию, которая будет использоваться при создании нового подключения.

Пример:

Net::HTTP.default_configuration = {
  read_timeout: 1,
  write_timeout: 1
}
http = Net::HTTP.new(hostname)
http.open_timeout   # => 60
http.read_timeout   # => 1
http.write_timeout  # => 1
proxy_address [R]

Возвращает адрес прокси-сервера или nil, если он не задан; см. Прокси-сервер в Net::HTTP.

proxy_pass [R]

Возвращает пароль для доступа к прокси или nil, если он не задан; см. Прокси-сервер в Net::HTTP.

proxy_port [R]

Возвращает номер порта прокси-сервера или nil, если он не задан; см. Прокси-сервер в Net::HTTP.

proxy_use_ssl [R]

Использовать SSL при подключении к прокси. Если Net::HTTP не использует прокси, возвращается nil.

proxy_user [R]

Возвращает имя пользователя для доступа к прокси или nil, если оно не задано; см. Прокси-сервер в Net::HTTP.

address [R]

Возвращает строковое имя хоста или IP-адрес хоста, переданный в качестве аргумента address в ::new.

ca_file [RW]

Задаёт или возвращает путь к файлу сертификата CA в формате PEM.

ca_path [RW]

Задаёт или возвращает путь к каталогу CA, содержащему файлы сертификатов в формате PEM.

cert [RW]

Задаёт или возвращает объект OpenSSL::X509::Certificate, используемый для аутентификации клиента.

cert_store [RW]

Задаёт или возвращает X509::Store, используемый для проверки сертификата узла.

ciphers [RW]

Задаёт или возвращает доступные шифры SSL. См. :SSL::SSLContext#ciphers=.

close_on_empty_response [RW]

Задаёт или возвращает, нужно ли закрывать подключение, если ответ пуст; исходное значение — false.

continue_timeout [R]

Возвращает значение тайм-аута ожидания продолжения; см. continue_timeout=.

extra_chain_cert [RW]

Задаёт или возвращает дополнительные сертификаты X509, добавляемые в цепочку сертификатов. См. :SSL::SSLContext#add_certificate.

ignore_eof [RW]

Задаёт или возвращает, следует ли игнорировать конец файла при чтении тела ответа с заголовками Content-Length; исходное значение — true.

keep_alive_timeout [RW]

Задаёт или возвращает числовое значение (Integer или Float) количества секунд, в течение которых подключение остаётся открытым после отправки запроса; исходное значение — 2. Если в течение заданного интервала отправляется новый запрос, используется всё ещё открытое подключение; в противном случае подключение будет закрыто, и будет открыто новое.

key [RW]

Задаёт или возвращает объект OpenSSL::PKey::RSA или OpenSSL::PKey::DSA.

local_host [RW]

Задаёт или возвращает строковое имя локального хоста, используемого для установки подключения; исходное значение — nil.

local_port [RW]

Задаёт или возвращает целочисленный номер локального порта, используемого для установки подключения; исходное значение — nil.

max_retries [R]

Возвращает максимальное количество повторных попыток для идемпотентного запроса; см. max_retries=.

max_version [RW]

Задаёт или возвращает максимальную версию SSL. См. :SSL::SSLContext#max_version=.

min_version [RW]

Задаёт или возвращает минимальную версию SSL. См. :SSL::SSLContext#min_version=.

open_timeout [RW]

Задаёт или возвращает числовое значение (Integer или Float) количества секунд ожидания установки подключения; исходное значение — 60. Если подключение не будет установлено в течение заданного интервала, возникнет исключение.

port [R]

Возвращает целочисленный номер порта, переданный в качестве аргумента port в ::new.

proxy_address [W]

Задаёт адрес прокси; см. Прокси-сервер.

proxy_from_env [W]

Задаёт, следует ли определять прокси по переменной окружения ‘ENV['http_proxy']’; см. Использование прокси с ENV.

proxy_pass [W]

Задаёт пароль прокси; см. Прокси-сервер.

proxy_port [W]

Задаёт порт прокси; см. Прокси-сервер.

proxy_use_ssl [W]

Задаёт, использует ли прокси SSL; см. Прокси-сервер.

proxy_user [W]

Задаёт имя пользователя прокси; см. Прокси-сервер.

read_timeout [R]

Возвращает числовое значение (Integer или Float) количества секунд ожидания чтения одного блока (одним вызовом read(2)); см. read_timeout=.

response_body_encoding [R]

Возвращает кодировку, используемую для тела ответа; см. response_body_encoding=.

ssl_timeout [RW]

Задаёт или возвращает тайм-аут SSL в секундах.

ssl_version [RW]

Задаёт или возвращает версию SSL. См. :SSL::SSLContext#ssl_version=.

verify_callback [RW]

Задаёт или возвращает функцию обратного вызова для проверки сертификата сервера.

verify_depth [RW]

Задаёт или возвращает максимальную глубину проверки цепочки сертификатов.

verify_hostname [RW]

Задаёт или возвращает, нужно ли проверять, действителен ли сертификат сервера для имени хоста. См. :SSL::SSLContext#verify_hostname=.

verify_mode [RW]

Задаёт или возвращает флаги проверки сертификата сервера в начале сеанса SSL/TLS. Допустимы OpenSSL::SSL::VERIFY_NONE или OpenSSL::SSL::VERIFY_PEER.

write_timeout [R]

Возвращает числовое значение (Integer или Float) количества секунд ожидания записи одного блока (одним вызовом write(2)); см. write_timeout=.

Публичные методы класса

default_port () Показать исходный код
# File lib/net/http.rb, line 935
def HTTP.default_port
  http_default_port()
end

Возвращает целое число 80 — порт по умолчанию для HTTP-запросов:

Net::HTTP.default_port # => 80
Net::HTTP.get(hostname, path, port = 80) → body Показать исходный код
Net::HTTP:get(uri, headers = {}, port = uri.port) → body
# File lib/net/http.rb, line 804
def HTTP.get(uri_or_host, path_or_headers = nil, port = nil)
  get_response(uri_or_host, path_or_headers, port).body
end

Отправляет GET-запрос и возвращает тело HTTP-ответа в виде строки.

Для строковых аргументов hostname и path:

hostname = 'jsonplaceholder.typicode.com'
path = '/todos/1'
puts Net::HTTP.get(hostname, path)

Вывод:

{
  "userId": 1,
  "id": 1,
  "title": "delectus aut autem",
  "completed": false
}

Для объекта URI uri и необязательного аргумента-хеша headers:

uri = URI('https://jsonplaceholder.typicode.com/todos/1')
headers = {'Content-type' => 'application/json; charset=UTF-8'}
Net::HTTP.get(uri, headers)

Связанные методы:

  • Net::HTTP::Get: класс запроса для HTTP-метода GET.

  • Net::HTTP#get: вспомогательный метод для HTTP-метода GET.

Net::HTTP.get_print(hostname, path, port = 80) → nil Показать исходный код
Net::HTTP:get_print(uri, headers = {}, port = uri.port) → nil
# File lib/net/http.rb, line 763
def HTTP.get_print(uri_or_host, path_or_headers = nil, port = nil)
  get_response(uri_or_host, path_or_headers, port) {|res|
    res.read_body do |chunk|
      $stdout.print chunk
    end
  }
  nil
end

Как Net::HTTP.get, но записывает возвращённое тело в $stdout; возвращает nil.

Net::HTTP.get_response(hostname, path, port = 80) → http_response Показать исходный код
Net::HTTP:get_response(uri, headers = {}, port = uri.port) → http_response
# File lib/net/http.rb, line 814
def HTTP.get_response(uri_or_host, path_or_headers = nil, port = nil, &block)
  if path_or_headers && !path_or_headers.is_a?(Hash)
    host = uri_or_host
    path = path_or_headers
    new(host, port || HTTP.default_port).start {|http|
      return http.request_get(path, &block)
    }
  else
    uri = uri_or_host
    headers = path_or_headers
    start(uri.hostname, uri.port,
          :use_ssl => uri.scheme == 'https') {|http|
      return http.request_get(uri, headers, &block)
    }
  end
end

Как Net::HTTP.get, но возвращает объект Net::HTTPResponse вместо строки с телом ответа.

http_default_port () Показать исходный код
# File lib/net/http.rb, line 943
def HTTP.http_default_port
  80
end

Возвращает целое число 80 — порт по умолчанию для HTTP-запросов:

Net::HTTP.http_default_port # => 80
https_default_port () Показать исходный код
# File lib/net/http.rb, line 951
def HTTP.https_default_port
  443
end

Возвращает целое число 443 — порт по умолчанию для HTTPS-запросов:

Net::HTTP.https_default_port # => 443
new (address, port = nil, p_addr = :ENV, p_port = nil, p_user = nil, p_pass = nil, p_no_proxy = nil, p_use_ssl = nil) Показать исходный код
# File lib/net/http.rb, line 1100
def HTTP.new(address, port = nil, p_addr = :ENV, p_port = nil, p_user = nil, p_pass = nil, p_no_proxy = nil, p_use_ssl = nil)
  http = super address, port

  if proxy_class? then # from Net::HTTP::Proxy()
    http.proxy_from_env = @proxy_from_env
    http.proxy_address  = @proxy_address
    http.proxy_port     = @proxy_port
    http.proxy_user     = @proxy_user
    http.proxy_pass     = @proxy_pass
    http.proxy_use_ssl  = @proxy_use_ssl
  elsif p_addr == :ENV then
    http.proxy_from_env = true
  else
    if p_addr && p_no_proxy && !URI::Generic.use_proxy?(address, address, port, p_no_proxy)
      p_addr = nil
      p_port = nil
    end
    http.proxy_address = p_addr
    http.proxy_port    = p_port || default_port
    http.proxy_user    = p_user
    http.proxy_pass    = p_pass
    http.proxy_use_ssl = p_use_ssl
  end

  http
end

Возвращает новый объект Net::HTTP http (но не открывает TCP-соединение или HTTP-сеанс).

Если передан только строковый аргумент address (а ENV['http_proxy'] не задан или равен nil), возвращаемый объект http:

  • Содержит указанный адрес.

  • Использует номер порта по умолчанию — Net::HTTP.default_port (80).

  • Не использует прокси.

Пример:

http = Net::HTTP.new(hostname)
# => #<Net::HTTP jsonplaceholder.typicode.com:80 open=false>
http.address # => "jsonplaceholder.typicode.com"
http.port    # => 80
http.proxy?  # => false

Если также передан целочисленный аргумент port, возвращаемый объект http использует указанный порт:

http = Net::HTTP.new(hostname, 8000)
# => #<Net::HTTP jsonplaceholder.typicode.com:8000 open=false>
http.port # => 8000

Сведения об аргументах для задания прокси p_addr–p_no_proxy см. в разделе Прокси-сервер.

Вызывает метод суперкласса
post (url, data, header = nil) Показать исходный код
# File lib/net/http.rb, line 857
def HTTP.post(url, data, header = nil)
  start(url.hostname, url.port,
        :use_ssl => url.scheme == 'https' ) {|http|
    http.post(url, data, header)
  }
end

Отправляет данные на хост; возвращает объект Net::HTTPResponse.

Аргумент url должен быть URL-адресом; аргумент data должен быть строкой:

_uri = uri.dup
_uri.path = '/posts'
data = '{"title": "foo", "body": "bar", "userId": 1}'
headers = {'content-type': 'application/json'}
res = Net::HTTP.post(_uri, data, headers) # => #<Net::HTTPCreated 201 Created readbody=true>
puts res.body

Вывод:

{
  "title": "foo",
  "body": "bar",
  "userId": 1,
  "id": 101
}

Связанные методы:

  • Net::HTTP::Post: класс запроса для HTTP-метода POST.

  • Net::HTTP#post: вспомогательный метод для HTTP-метода POST.

post_form (url, params) Показать исходный код
# File lib/net/http.rb, line 884
def HTTP.post_form(url, params)
  req = Post.new(url)
  req.form_data = params
  req.basic_auth url.user, url.password if url.user
  start(url.hostname, url.port,
        :use_ssl => url.scheme == 'https' ) {|http|
    http.request(req)
  }
end

Отправляет данные на хост; возвращает объект Net::HTTPResponse.

Аргумент url должен быть объектом URI; аргумент data должен быть хешем:

_uri = uri.dup
_uri.path = '/posts'
data = {title: 'foo', body: 'bar', userId: 1}
res = Net::HTTP.post_form(_uri, data) # => #<Net::HTTPCreated 201 Created readbody=true>
puts res.body

Вывод:

{
  "title": "foo",
  "body": "bar",
  "userId": "1",
  "id": 101
}
proxy_class? () Показать исходный код
# File lib/net/http.rb, line 1855
def proxy_class?
  defined?(@is_proxy_class) ? @is_proxy_class : false
end

Возвращает true, если self — класс, созданный HTTP::Proxy.

put (url, data, header = nil) Показать исходный код
# File lib/net/http.rb, line 920
def HTTP.put(url, data, header = nil)
  start(url.hostname, url.port,
        :use_ssl => url.scheme == 'https' ) {|http|
    http.put(url, data, header)
  }
end

Отправляет PUT-запрос на сервер; возвращает объект Net::HTTPResponse.

Аргумент url должен быть URL-адресом; аргумент data должен быть строкой:

_uri = uri.dup
_uri.path = '/posts'
data = '{"title": "foo", "body": "bar", "userId": 1}'
headers = {'content-type': 'application/json'}
res = Net::HTTP.put(_uri, data, headers) # => #<Net::HTTPCreated 201 Created readbody=true>
puts res.body

Вывод:

{
  "title": "foo",
  "body": "bar",
  "userId": 1,
  "id": 101
}

Связанные методы:

  • Net::HTTP::Put: класс запроса для HTTP-метода PUT.

  • Net::HTTP#put: вспомогательный метод для HTTP-метода PUT.

start(address, port = nil, p_addr = :ENV, p_port = nil, p_user = nil, p_pass = nil, opts) → http Показать исходный код
start(address, port = nil, p_addr = :ENV, p_port = nil, p_user = nil, p_pass = nil, opts) {|http| ... } → object
# File lib/net/http.rb, line 1045
def HTTP.start(address, *arg, &block) # :yield: +http+
  arg.pop if opt = Hash.try_convert(arg[-1])
  port, p_addr, p_port, p_user, p_pass = *arg
  p_addr = :ENV if arg.size < 2
  port = https_default_port if !port && opt && opt[:use_ssl]
  http = new(address, port, p_addr, p_port, p_user, p_pass)
  http.ipaddr = opt[:ipaddr] if opt && opt[:ipaddr]

  if opt
    if opt[:use_ssl]
      opt = {verify_mode: OpenSSL::SSL::VERIFY_PEER}.update(opt)
    end
    http.methods.grep(/\A(\w+)=\z/) do |meth|
      key = $1.to_sym
      opt.key?(key) or next
      http.__send__(meth, opt[key])
    end
  end

  http.start(&block)
end

Создаёт новый объект Net::HTTP http с помощью Net::HTTP.new:

  • Сведения об аргументах address и port см. в описании Net::HTTP.new.

  • Сведения об аргументах для задания прокси p_addr–p_pass см. в разделе Прокси-сервер.

  • Сведения об аргументе opts приведены ниже.

Если блок не указан:

  • Вызывает http.start без блока (см. start), открывая TCP-соединение и HTTP-сеанс.

  • Возвращает http.

  • Вызывающий код должен вызвать finish, чтобы закрыть сеанс:

    http = Net::HTTP.start(hostname)
    http.started? # => true
    http.finish
    http.started? # => false
    

Если блок указан:

  • Вызывает http.start с блоком (см. start), который:

    • Открывает TCP-соединение и HTTP-сеанс.

    • Вызывает блок, в котором можно отправить любое количество запросов к хосту.

    • Закрывает HTTP-сеанс и TCP-соединение после завершения блока.

    • Возвращает значение блока object.

  • Возвращает object.

Пример:

hostname = 'jsonplaceholder.typicode.com'
Net::HTTP.start(hostname) do |http|
  puts http.get('/todos/1').body
  puts http.get('/todos/2').body
end

Вывод:

{
  "userId": 1,
  "id": 1,
  "title": "delectus aut autem",
  "completed": false
}
{
  "userId": 1,
  "id": 2,
  "title": "quis ut nam facilis et officia qui",
  "completed": false
}

Если последний переданный аргумент — хеш, он является хешем opts, в котором каждый ключ — это вызываемый метод или метод доступа, а значение — устанавливаемое значение.

Среди ключей могут быть:

  • ca_file

  • ca_path

  • cert

  • cert_store

  • ciphers

  • close_on_empty_response

  • ipaddr (вызывает ipaddr=)

  • keep_alive_timeout

  • key

  • open_timeout

  • read_timeout

  • ssl_timeout

  • ssl_version

  • use_ssl (вызывает use_ssl=)

  • verify_callback

  • verify_depth

  • verify_mode

  • write_timeout

Примечание: если port равно nil, а opts[:use_ssl] имеет истинное значение, в new передаётся Net::HTTP.https_default_port, а не port.

version_1_2 () Показать исходный код
# File lib/net/http.rb, line 738
def HTTP.version_1_2
  true
end

Возвращает true; сохранён для обратной совместимости.

version_1_2? () Показать исходный код
# File lib/net/http.rb, line 743
def HTTP.version_1_2?
  true
end

Возвращает true; сохранён для обратной совместимости.

Открытые методы экземпляра

continue_timeout= (sec) Показать исходный код
# File lib/net/http.rb, line 1455
def continue_timeout=(sec)
  @socket.continue_timeout = sec if @socket
  @continue_timeout = sec
end

Задаёт значение тайм-аута ожидания продолжения — количество секунд, в течение которых ожидается ответ 100 Continue. Если объект HTTP не получает ответ за это время, он отправляет тело запроса.

copy (path, initheader = nil) Показать исходный код
# File lib/net/http.rb, line 2227
def copy(path, initheader = nil)
  request(Copy.new(path, initheader))
end

Отправляет серверу запрос COPY; возвращает экземпляр подкласса Net::HTTPResponse.

Запрос основан на объекте Net::HTTP::Copy, созданном из строки path и хеша начальных заголовков initheader.

http = Net::HTTP.new(hostname)
http.copy('/todos/1')
delete (path, initheader = {'Depth' => 'Infinity'}) Показать исходный код
# File lib/net/http.rb, line 2201
def delete(path, initheader = {'Depth' => 'Infinity'})
  request(Delete.new(path, initheader))
end

Отправляет серверу запрос DELETE; возвращает экземпляр подкласса Net::HTTPResponse.

Запрос основан на объекте Net::HTTP::Delete, созданном из строки path и хеша начальных заголовков initheader.

http = Net::HTTP.new(hostname)
http.delete('/todos/1')
finish () Показать исходный код
# File lib/net/http.rb, line 1648
def finish
  raise IOError, 'HTTP session not yet started' unless started?
  do_finish
end

Завершает сеанс HTTP:

http = Net::HTTP.new(hostname)
http.start
http.started? # => true
http.finish   # => nil
http.started? # => false

Вызывает исключение IOError, если сеанс не запущен.

get(path, initheader = nil) {|res| ... } Показать исходный код
# File lib/net/http.rb, line 2013
def get(path, initheader = nil, dest = nil, &block) # :yield: +body_segment+
  res = nil

  request(Get.new(path, initheader)) {|r|
    r.read_body dest, &block
    res = r
  }
  res
end

Отправляет серверу запрос GET; возвращает экземпляр подкласса Net::HTTPResponse.

Запрос основан на объекте Net::HTTP::Get, созданном из строки path и хеша начальных заголовков initheader.

Если передан блок, вызывает его с телом ответа:

http = Net::HTTP.new(hostname)
http.get('/todos/1') do |res|
  p res
end # => #<Net::HTTPOK 200 OK readbody=true>

Вывод:

"{\n  \"userId\": 1,\n  \"id\": 1,\n  \"title\": \"delectus aut autem\",\n  \"completed\": false\n}"

Если блок не передан, просто возвращает объект ответа:

http.get('/') # => #<Net::HTTPOK 200 OK readbody=true>

Связанные методы:

  • Net::HTTP::Get: класс запроса для метода HTTP GET.

  • Net::HTTP.get: отправляет запрос GET и возвращает тело ответа.

head (path, initheader = nil) Показать исходный код
# File lib/net/http.rb, line 2037
def head(path, initheader = nil)
  request(Head.new(path, initheader))
end

Отправляет серверу запрос HEAD; возвращает экземпляр подкласса Net::HTTPResponse.

Запрос основан на объекте Net::HTTP::Head, созданном из строки path и хеша начальных заголовков initheader:

res = http.head('/todos/1') # => #<Net::HTTPOK 200 OK readbody=true>
res.body                    # => nil
res.to_hash.take(3)
# =>
[["date", ["Wed, 15 Feb 2023 15:25:42 GMT"]],
 ["content-type", ["application/json; charset=utf-8"]],
 ["connection", ["close"]]]
inspect () Показать исходный код
# File lib/net/http.rb, line 1206
def inspect
  "#<#{self.class} #{@address}:#{@port} open=#{started?}>"
end

Возвращает строковое представление self:

Net::HTTP.new(hostname).inspect
# => "#<Net::HTTP jsonplaceholder.typicode.com:80 open=false>"
ipaddr () Показать исходный код
# File lib/net/http.rb, line 1349
def ipaddr
  started? ?  @socket.io.peeraddr[3] : @ipaddr
end

Возвращает IP-адрес соединения.

Если сеанс не запущен, возвращает значение, заданное методом ipaddr=, или nil, если оно не задано:

http = Net::HTTP.new(hostname)
http.ipaddr # => nil
http.ipaddr = '172.67.155.76'
http.ipaddr # => "172.67.155.76"

Если сеанс запущен, возвращает IP-адрес из сокета:

http = Net::HTTP.new(hostname)
http.start
http.ipaddr # => "172.67.155.76"
http.finish
ipaddr= (addr) Показать исходный код
# File lib/net/http.rb, line 1361
def ipaddr=(addr)
  raise IOError, "ipaddr value changed, but session already started" if started?
  @ipaddr = addr
end

Задаёт IP-адрес соединения:

http = Net::HTTP.new(hostname)
http.ipaddr # => nil
http.ipaddr = '172.67.155.76'
http.ipaddr # => "172.67.155.76"

IP-адрес нельзя задать, если сеанс уже запущен.

lock (path, body, initheader = nil) Показать исходный код
# File lib/net/http.rb, line 2147
def lock(path, body, initheader = nil)
  request(Lock.new(path, initheader), body)
end

Отправляет серверу запрос LOCK; возвращает экземпляр подкласса Net::HTTPResponse.

Запрос основан на объекте Net::HTTP::Lock, созданном из строки path, строки body и хеша начальных заголовков initheader.

data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}'
http = Net::HTTP.new(hostname)
http.lock('/todos/1', data)
max_retries= (retries) Показать исходный код
# File lib/net/http.rb, line 1395
def max_retries=(retries)
  retries = retries.to_int
  if retries < 0
    raise ArgumentError, 'max_retries should be non-negative integer number'
  end
  @max_retries = retries
end

Задаёт максимальное количество повторных попыток для идемпотентного запроса в случае Net::ReadTimeout, IOError, EOFError, Errno::ECONNRESET, Errno::ECONNABORTED, Errno::EPIPE, OpenSSL::SSL::SSLError, Timeout::Error. Начальное значение — 1.

Аргумент retries должен быть неотрицательным числовым значением:

http = Net::HTTP.new(hostname)
http.max_retries = 2   # => 2
http.max_retries       # => 2
mkcol (path, body = nil, initheader = nil) Показать исходный код
# File lib/net/http.rb, line 2241
def mkcol(path, body = nil, initheader = nil)
  request(Mkcol.new(path, initheader), body)
end

Отправляет серверу запрос MKCOL; возвращает экземпляр подкласса Net::HTTPResponse.

Запрос основан на объекте Net::HTTP::Mkcol, созданном из строки path, строки body и хеша начальных заголовков initheader.

data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}'
http.mkcol('/todos/1', data)
http = Net::HTTP.new(hostname)
move (path, initheader = nil) Показать исходный код
# File lib/net/http.rb, line 2214
def move(path, initheader = nil)
  request(Move.new(path, initheader))
end

Отправляет серверу запрос MOVE; возвращает экземпляр подкласса Net::HTTPResponse.

Запрос основан на объекте Net::HTTP::Move, созданном из строки path и хеша начальных заголовков initheader.

http = Net::HTTP.new(hostname)
http.move('/todos/1')
options (path, initheader = nil) Показать исходный код
# File lib/net/http.rb, line 2174
def options(path, initheader = nil)
  request(Options.new(path, initheader))
end

Отправляет серверу запрос Options; возвращает экземпляр подкласса Net::HTTPResponse.

Запрос основан на объекте Net::HTTP::Options, созданном из строки path и хеша начальных заголовков initheader.

http = Net::HTTP.new(hostname)
http.options('/')
patch(path, data, initheader = nil) {|res| ... } Показать исходный код
# File lib/net/http.rb, line 2100
def patch(path, data, initheader = nil, dest = nil, &block) # :yield: +body_segment+
  send_entity(path, data, initheader, dest, Patch, &block)
end

Отправляет серверу запрос PATCH; возвращает экземпляр подкласса Net::HTTPResponse.

Запрос основан на объекте Net::HTTP::Patch, созданном из строки path, строки data и хеша начальных заголовков initheader.

Если передан блок, вызывает его с телом ответа:

data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}'
http = Net::HTTP.new(hostname)
http.patch('/todos/1', data) do |res|
  p res
end # => #<Net::HTTPOK 200 OK readbody=true>

Вывод:

"{\n  \"userId\": 1,\n  \"id\": 1,\n  \"title\": \"delectus aut autem\",\n  \"completed\": false,\n  \"{\\\"userId\\\": 1, \\\"id\\\": 1, \\\"title\\\": \\\"delectus aut autem\\\", \\\"completed\\\": false}\": \"\"\n}"

Если блок не передан, просто возвращает объект ответа:

http.patch('/todos/1', data) # => #<Net::HTTPCreated 201 Created readbody=true>
peer_cert () Показать исходный код
# File lib/net/http.rb, line 1597
def peer_cert
  if not use_ssl? or not @socket
    return nil
  end
  @socket.io.peer_cert
end

Возвращает цепочку сертификатов X509 (массив строк) для узла на другой стороне сокета сеанса или nil, если сертификатов нет.

post(path, data, initheader = nil) {|res| ... } Показать исходный код
# File lib/net/http.rb, line 2071
def post(path, data, initheader = nil, dest = nil, &block) # :yield: +body_segment+
  send_entity(path, data, initheader, dest, Post, &block)
end

Отправляет серверу запрос POST; возвращает экземпляр подкласса Net::HTTPResponse.

Запрос основан на объекте Net::HTTP::Post, созданном из строки path, строки data и хеша начальных заголовков initheader.

Если передан блок, вызывает его с телом ответа:

data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}'
http = Net::HTTP.new(hostname)
http.post('/todos', data) do |res|
  p res
end # => #<Net::HTTPCreated 201 Created readbody=true>

Вывод:

"{\n  \"{\\\"userId\\\": 1, \\\"id\\\": 1, \\\"title\\\": \\\"delectus aut autem\\\", \\\"completed\\\": false}\": \"\",\n  \"id\": 201\n}"

Если блок не передан, просто возвращает объект ответа:

http.post('/todos', data) # => #<Net::HTTPCreated 201 Created readbody=true>

Связанные методы:

  • Net::HTTP::Post: класс запроса для метода HTTP POST.

  • Net::HTTP.post: отправляет запрос POST и возвращает тело ответа.

propfind (path, body = nil, initheader = {'Depth' => '0'}) Показать исходный код
# File lib/net/http.rb, line 2188
def propfind(path, body = nil, initheader = {'Depth' => '0'})
  request(Propfind.new(path, initheader), body)
end

Отправляет серверу запрос PROPFIND; возвращает экземпляр подкласса Net::HTTPResponse.

Запрос основан на объекте Net::HTTP::Propfind, созданном из строки path, строки body и хеша начальных заголовков initheader.

data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}'
http = Net::HTTP.new(hostname)
http.propfind('/todos/1', data)
proppatch (path, body, initheader = nil) Показать исходный код
# File lib/net/http.rb, line 2133
def proppatch(path, body, initheader = nil)
  request(Proppatch.new(path, initheader), body)
end

Отправляет серверу запрос PROPPATCH; возвращает экземпляр подкласса Net::HTTPResponse.

Запрос основан на объекте Net::HTTP::Proppatch, созданном из строки path, строки body и хеша начальных заголовков initheader.

data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}'
http = Net::HTTP.new(hostname)
http.proppatch('/todos/1', data)
proxy? () Показать исходный код
# File lib/net/http.rb, line 1881
def proxy?
  !!(@proxy_from_env ? proxy_uri : @proxy_address)
end

Возвращает true, если задан прокси-сервер, и false в противном случае; см. раздел Прокси-сервер.

proxy_address () Показать исходный код
# File lib/net/http.rb, line 1903
def proxy_address
  if @proxy_from_env then
    proxy_uri&.hostname
  else
    @proxy_address
  end
end

Возвращает адрес прокси-сервера, если он задан, и nil в противном случае; см. раздел Прокси-сервер.

proxy_from_env? () Показать исходный код
# File lib/net/http.rb, line 1888
def proxy_from_env?
  @proxy_from_env
end

Возвращает true, если прокси-сервер задан в окружении, и false в противном случае; см. раздел Прокси-сервер.

proxy_pass () Показать исходный код
# File lib/net/http.rb, line 1934
def proxy_pass
  if @proxy_from_env
    pass = proxy_uri&.password
    unescape(pass) if pass
  else
    @proxy_pass
  end
end

Возвращает пароль прокси-сервера, если он задан, и nil в противном случае; см. раздел Прокси-сервер.

proxy_port () Показать исходный код
# File lib/net/http.rb, line 1913
def proxy_port
  if @proxy_from_env then
    proxy_uri&.port
  else
    @proxy_port
  end
end

Возвращает номер порта прокси-сервера, если он задан, и nil в противном случае; см. раздел Прокси-сервер.

proxy_user () Показать исходный код
# File lib/net/http.rb, line 1923
def proxy_user
  if @proxy_from_env
    user = proxy_uri&.user
    unescape(user) if user
  else
    @proxy_user
  end
end

Возвращает имя пользователя прокси-сервера, если оно задано, и nil в противном случае; см. раздел Прокси-сервер.

put (path, data, initheader = nil) Показать исходный код
# File lib/net/http.rb, line 2119
def put(path, data, initheader = nil)
  request(Put.new(path, initheader), data)
end

Отправляет серверу запрос PUT; возвращает экземпляр подкласса Net::HTTPResponse.

Запрос основан на объекте Net::HTTP::Put, созданном из строки path, строки data и хеша начальных заголовков initheader.

data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}'
http = Net::HTTP.new(hostname)
http.put('/todos/1', data) # => #<Net::HTTPOK 200 OK readbody=true>

Связанные методы:

  • Net::HTTP::Put: класс запроса для метода HTTP PUT.

  • Net::HTTP.put: отправляет запрос PUT и возвращает тело ответа.

read_timeout= (sec) Показать исходный код
# File lib/net/http.rb, line 1418
def read_timeout=(sec)
  @socket.read_timeout = sec if @socket
  @read_timeout = sec
end

Задаёт тайм-аут чтения в секундах для self целым числом sec; начальное значение — 60.

Аргумент sec должен быть неотрицательным числовым значением:

http = Net::HTTP.new(hostname)
http.read_timeout # => 60
http.get('/todos/1') # => #<Net::HTTPOK 200 OK readbody=true>
http.read_timeout = 0
http.get('/todos/1') # Raises Net::ReadTimeout.
request (req, body = nil) { |response| ... } Показать исходный код
# File lib/net/http.rb, line 2399
def request(req, body = nil, &block)  # :yield: +response+
  unless started?
    start {
      req['connection'] ||= 'close'
      return request(req, body, &block)
    }
  end
  if proxy_user()
    req.proxy_basic_auth proxy_user(), proxy_pass() unless use_ssl?
  end
  req.set_body_internal body
  res = transport_request(req, &block)
  if sspi_auth?(res)
    sspi_auth(req)
    res = transport_request(req, &block)
  end
  res
end

Отправляет серверу заданный запрос req; формирует ответ в виде объекта Net::HTTPResponse.

Заданный req должен быть экземпляром подкласса Net::HTTPRequest. Аргумент body следует указывать только в том случае, если он требуется для запроса.

Если блок не передан, возвращает объект ответа:

http = Net::HTTP.new(hostname)

req = Net::HTTP::Get.new('/todos/1')
http.request(req)
# => #<Net::HTTPOK 200 OK readbody=true>

req = Net::HTTP::Post.new('/todos')
http.request(req, 'xyzzy')
# => #<Net::HTTPCreated 201 Created readbody=true>

Если блок передан, вызывает его с ответом и возвращает ответ:

req = Net::HTTP::Get.new('/todos/1')
http.request(req) do |res|
  p res
end # => #<Net::HTTPOK 200 OK readbody=true>

Вывод:

#<Net::HTTPOK 200 OK readbody=false>
request_get (path, initheader = nil) { |response| ... } Показать исходный код
# File lib/net/http.rb, line 2280
def request_get(path, initheader = nil, &block) # :yield: +response+
  request(Get.new(path, initheader), &block)
end

Отправляет серверу запрос GET; формирует ответ в виде объекта Net::HTTPResponse.

Запрос основан на объекте Net::HTTP::Get, созданном из строки path и хеша начальных заголовков initheader.

Если блок не передан, возвращает объект ответа:

http = Net::HTTP.new(hostname)
http.request_get('/todos') # => #<Net::HTTPOK 200 OK readbody=true>

Если блок передан, вызывает его с объектом ответа и возвращает объект ответа:

http.request_get('/todos') do |res|
  p res
end # => #<Net::HTTPOK 200 OK readbody=true>

Вывод:

#<Net::HTTPOK 200 OK readbody=false>
request_head (path, initheader = nil, &block) Показать исходный код
# File lib/net/http.rb, line 2293
def request_head(path, initheader = nil, &block)
  request(Head.new(path, initheader), &block)
end

Отправляет серверу запрос HEAD; возвращает экземпляр подкласса Net::HTTPResponse.

Запрос основан на объекте Net::HTTP::Head, созданном из строки path и хеша начальных заголовков initheader.

http = Net::HTTP.new(hostname)
http.head('/todos/1') # => #<Net::HTTPOK 200 OK readbody=true>
request_post (path, data, initheader = nil) { |response| ... } Показать исходный код
# File lib/net/http.rb, line 2320
def request_post(path, data, initheader = nil, &block) # :yield: +response+
  request Post.new(path, initheader), data, &block
end

Отправляет серверу запрос POST; формирует ответ в виде объекта Net::HTTPResponse.

Запрос основан на объекте Net::HTTP::Post, созданном из строки path, строки data и хеша начальных заголовков initheader.

Если блок не передан, возвращает объект ответа:

http = Net::HTTP.new(hostname)
http.post('/todos', 'xyzzy')
# => #<Net::HTTPCreated 201 Created readbody=true>

Если блок передан, вызывает его с телом ответа и возвращает объект ответа:

http.post('/todos', 'xyzzy') do |res|
  p res
end # => #<Net::HTTPCreated 201 Created readbody=true>

Вывод:

"{\n  \"xyzzy\": \"\",\n  \"id\": 201\n}"
response_body_encoding= (value) Показать исходный код
# File lib/net/http.rb, line 1300
def response_body_encoding=(value)
  value = Encoding.find(value) if value.is_a?(String)
  @response_body_encoding = value
end

Задаёт кодировку, используемую для тела ответа; возвращает кодировку.

Значение value может быть:

  • объектом Encoding;

  • названием кодировки;

  • псевдонимом названия кодировки.

См. Encoding.

Примеры:

http = Net::HTTP.new(hostname)
http.response_body_encoding = Encoding::US_ASCII # => #<Encoding:US-ASCII>
http.response_body_encoding = 'US-ASCII'         # => "US-ASCII"
http.response_body_encoding = 'ASCII'            # => "ASCII"
send_request (name, path, data = nil, header = nil) Показать исходный код
# File lib/net/http.rb, line 2363
def send_request(name, path, data = nil, header = nil)
  has_response_body = name != 'HEAD'
  r = HTTPGenericRequest.new(name,(data ? true : false),has_response_body,path,header)
  request r, data
end

Отправляет серверу HTTP-запрос; возвращает экземпляр подкласса Net::HTTPResponse.

Запрос основан на объекте Net::HTTPRequest, созданном из строки path, строки data и хеша начальных заголовков header. Этот объект является экземпляром подкласса Net::HTTPRequest, соответствующего заданной строке name в верхнем регистре, которая должна обозначать метод HTTP-запроса или метод запроса WebDAV.

Примеры:

http = Net::HTTP.new(hostname)
http.send_request('GET', '/todos/1')
# => #<Net::HTTPOK 200 OK readbody=true>
http.send_request('POST', '/todos', 'xyzzy')
# => #<Net::HTTPCreated 201 Created readbody=true>
set_debug_output (output) Показать исходный код
# File lib/net/http.rb, line 1259
def set_debug_output(output)
  warn 'Net::HTTP#set_debug_output called after HTTP started', uplevel: 1 if started?
  @debug_output = output
end

ПРЕДУПРЕЖДЕНИЕ Этот метод создаёт серьёзную уязвимость системы безопасности. Никогда не используйте его в рабочем коде.

Задаёт поток вывода для отладки:

http = Net::HTTP.new(hostname)
File.open('t.tmp', 'w') do |file|
  http.set_debug_output(file)
  http.start
  http.get('/nosuch/1')
  http.finish
end
puts File.read('t.tmp')

Вывод:

opening connection to jsonplaceholder.typicode.com:80...
opened
<- "GET /nosuch/1 HTTP/1.1\r\nAccept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3\r\nAccept: */*\r\nUser-Agent: Ruby\r\nHost: jsonplaceholder.typicode.com\r\n\r\n"
-> "HTTP/1.1 404 Not Found\r\n"
-> "Date: Mon, 12 Dec 2022 21:14:11 GMT\r\n"
-> "Content-Type: application/json; charset=utf-8\r\n"
-> "Content-Length: 2\r\n"
-> "Connection: keep-alive\r\n"
-> "X-Powered-By: Express\r\n"
-> "X-Ratelimit-Limit: 1000\r\n"
-> "X-Ratelimit-Remaining: 999\r\n"
-> "X-Ratelimit-Reset: 1670879660\r\n"
-> "Vary: Origin, Accept-Encoding\r\n"
-> "Access-Control-Allow-Credentials: true\r\n"
-> "Cache-Control: max-age=43200\r\n"
-> "Pragma: no-cache\r\n"
-> "Expires: -1\r\n"
-> "X-Content-Type-Options: nosniff\r\n"
-> "Etag: W/\"2-vyGp6PvFo4RvsFtPoIWeCReyIC8\"\r\n"
-> "Via: 1.1 vegur\r\n"
-> "CF-Cache-Status: MISS\r\n"
-> "Server-Timing: cf-q-config;dur=1.3000000762986e-05\r\n"
-> "Report-To: {\"endpoints\":[{\"url\":\"https:\\/\\/a.nel.cloudflare.com\\/report\\/v3?s=yOr40jo%2BwS1KHzhTlVpl54beJ5Wx2FcG4gGV0XVrh3X9OlR5q4drUn2dkt5DGO4GDcE%2BVXT7CNgJvGs%2BZleIyMu8CLieFiDIvOviOY3EhHg94m0ZNZgrEdpKD0S85S507l1vsEwEHkoTm%2Ff19SiO\"}],\"group\":\"cf-nel\",\"max_age\":604800}\r\n"
-> "NEL: {\"success_fraction\":0,\"report_to\":\"cf-nel\",\"max_age\":604800}\r\n"
-> "Server: cloudflare\r\n"
-> "CF-RAY: 778977dc484ce591-DFW\r\n"
-> "alt-svc: h3=\":443\"; ma=86400, h3-29=\":443\"; ma=86400\r\n"
-> "\r\n"
reading 2 bytes...
-> "{}"
read 2 bytes
Conn keep-alive
start () { |http| ... } Показать исходный код
# File lib/net/http.rb, line 1625
def start  # :yield: http
  raise IOError, 'HTTP session already opened' if @started
  if block_given?
    begin
      do_start
      return yield(self)
    ensure
      do_finish
    end
  end
  do_start
  self
end

Запускает сеанс HTTP.

Если блок не передан, возвращает self:

http = Net::HTTP.new(hostname)
# => #<Net::HTTP jsonplaceholder.typicode.com:80 open=false>
http.start
# => #<Net::HTTP jsonplaceholder.typicode.com:80 open=true>
http.started? # => true
http.finish

Если блок передан, вызывает его с self, завершает сеанс после выхода из блока и возвращает значение блока:

http.start do |http|
  http
end
# => #<Net::HTTP jsonplaceholder.typicode.com:80 open=false>
http.started? # => false
started? () Показать исходный код
# File lib/net/http.rb, line 1488
def started?
  @started
end

Возвращает true, если сеанс HTTP запущен:

http = Net::HTTP.new(hostname)
http.started? # => false
http.start
http.started? # => true
http.finish # => nil
http.started? # => false

Net::HTTP.start(hostname) do |http|
  http.started?
end # => true
http.started? # => false
trace (path, initheader = nil) Показать исходный код
# File lib/net/http.rb, line 2254
def trace(path, initheader = nil)
  request(Trace.new(path, initheader))
end

Отправляет серверу запрос TRACE; возвращает экземпляр подкласса Net::HTTPResponse.

Запрос основан на объекте Net::HTTP::Trace, созданном из строки path и хеша начальных заголовков initheader.

http = Net::HTTP.new(hostname)
http.trace('/todos/1')
unlock (path, body, initheader = nil) Показать исходный код
# File lib/net/http.rb, line 2161
def unlock(path, body, initheader = nil)
  request(Unlock.new(path, initheader), body)
end

Отправляет серверу запрос UNLOCK; возвращает экземпляр подкласса Net::HTTPResponse.

Запрос формируется на основе объекта Net::HTTP::Unlock, созданного из строки path, строки body и хеша начальных заголовков initheader.

data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}'
http = Net::HTTP.new(hostname)
http.unlock('/todos/1', data)
use_ssl= (flag) Показать исходный код
# File lib/net/http.rb, line 1510
def use_ssl=(flag)
  flag = flag ? true : false
  if started? and @use_ssl != flag
    raise IOError, "use_ssl value changed, but session already started"
  end
  @use_ssl = flag
end

Устанавливает, будет ли новый сеанс использовать протокол защиты транспортного уровня:

Вызывает исключение IOError при попытке изменить значение во время сеанса.

Вызывает исключение OpenSSL::SSL::SSLError, если порт не является портом HTTPS.

use_ssl? () Показать исходный код
# File lib/net/http.rb, line 1500
def use_ssl?
  @use_ssl
end

Возвращает true, если self использует SSL, и false в противном случае. См. Net::HTTP#use_ssl=.

write_timeout= (sec) Показать исходный код
# File lib/net/http.rb, line 1442
def write_timeout=(sec)
  @socket.write_timeout = sec if @socket
  @write_timeout = sec
end

Устанавливает время ожидания записи в секундах для self в целое число sec; начальное значение — 60.

Аргумент sec должен быть неотрицательным числовым значением:

_uri = uri.dup
_uri.path = '/posts'
body = 'bar' * 200000
data = <<EOF
{"title": "foo", "body": "#{body}", "userId": "1"}
EOF
headers = {'content-type': 'application/json'}
http = Net::HTTP.new(hostname)
http.write_timeout # => 60
http.post(_uri.path, data, headers)
# => #<Net::HTTPCreated 201 Created readbody=true>
http.write_timeout = 0
http.post(_uri.path, data, headers) # Raises Net::WriteTimeout.

Приватные методы экземпляра

send_entity (path, data, initheader, dest, type, &block) Показать исходный код
# File lib/net/http.rb, line 2422
def send_entity(path, data, initheader, dest, type, &block)
  res = nil
  request(type.new(path, initheader), data) {|r|
    r.read_body dest, &block
    res = r
  }
  res
end

Выполняет запрос, использующий представление, и возвращает его тело.

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

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API