Команда ReQL: http

Синтаксис команды

r.http(url[, options]) → value
r.http(url[, options]) → stream

Описание

Извлекает данные из указанного URL-адреса по протоколу HTTP. Тип возвращаемого значения зависит от параметра result_format, который по умолчанию проверяет Content-Type ответа. Убедитесь, что вы никогда не используете эту команду для URL-адресов, предоставленных пользователем.

Пример: Выполните HTTP GET и сохраните результат в таблице.

r.table('posts').insert(r.http('http://httpbin.org/get')).run(conn)

См. учебник по r.http для получения дополнительных примеров использования этой команды.

Параметры

Общие параметры

• timeout: период ожидания в секундах перед прерыванием соединения (по умолчанию 30).
• attempts: количество попыток повторного подключения после неудачных соединений (по умолчанию 5).
• redirects: количество переадресаций и заголовков расположения для следования (по умолчанию 1).
• verify: если true, проверять сертификат SSL сервера (по умолчанию true).
• result_format: строка, определяющая формат возвращаемых результатов. Один из следующих:
  • text: всегда возвращает строку.
  • json: анализирует результат как JSON, генерируя ошибку при неудаче.
  • jsonp: анализирует результат как JSONP.
  • binary: возвращает двоичный объект.
  • auto: анализирует результат на основе его Content-Type (по умолчанию):
    • application/json: как json
    • application/json-p, text/json-p, text/javascript: как jsonp
    • audio/*, video/*, image/*, application/octet-stream: как binary
    • в противном случае: как text

Параметры запроса

• method: HTTP-метод для использования в запросе. Один из GET, POST, PUT, PATCH, DELETE или HEAD. По умолчанию: GET.
• auth: объект, задающий аутентификацию, с указанием следующих полей:
  • type: basic (по умолчанию) или digest
  • user: имя пользователя
  • pass: пароль в открытом виде
• params: объект, определяющий параметры URL для добавления к URL в виде закодированных пар ключ/значение. { :query => 'banana', :limit => 2 } будут добавлены в виде ?query=banana&limit=2. По умолчанию: нет параметров.
• header: Дополнительные строки заголовков для включения. Значение может быть массивом строк или объектом. По умолчанию: Accept-Encoding: deflate;q=1, gzip;q=0.5 и User-Agent: RethinkDB/<VERSION>.
• data: Данные для отправки на сервер в запросе типа POST, PUT, PATCH, или DELETE. Для запросов типа POST, данные могут быть объектом (который будет записан в тело как парные данные ключ/значение в формате формы) или строкой; для всех других запросов данные будут сериализованы как JSON и помещены в тело запроса, отправленные как Content-Type: application/json. По умолчанию данные не будут отправляться.

Пример: Выполнение нескольких запросов с различными параметрами.

r.expr([1, 2, 3]).map{|i|
    r.http('http://httpbin.org/get', :params => { :user => i })
}.run(conn)

Пример: Выполнение запроса PUT для каждого элемента в таблице.

r.table('data').map{|row|
    r.http('http://httpbin.org/put', :method => 'PUT', :data => row)
}.run(conn)

Пример: Выполнение запроса POST с сопровождающими данными.

Использование данных в формате формы:

r.http('http://httpbin.org/post',
       :method => 'POST',
       :data => { :player => 'Bob', :game => 'tic tac toe' }).run(conn)

Использование данных в формате JSON:

r.http('http://httpbin.org/post',
       :method => 'POST',
       :data => r.expr(value).coerce_to('string'),
       :header => { 'Content-Type' => 'application/json' }).run(conn)

Пейджинг

r.http поддерживает пейджинг, который запрашивает несколько страниц подряд и агрегирует результаты в поток. Использование этой функции контролируется необязательными аргументами page и page_limit. Должны быть указаны либо оба, либо ни одного из этих аргументов.

• page: Этот параметр может указать встроенную стратегию пейджирования (см. ниже) или функцию для получения следующего URL-адреса и/или params для запроса.
• page_limit: Целое число, указывающее максимальное количество запросов для выдачи с помощью функциональности page. Это необходимо для предотвращения чрезмерного использования квот API и должно быть указано с page.
  • -1: без ограничения
  • 0: запросы не будут выполнены, будет возвращен пустой поток
  • n: будет выполнено n запросов

В настоящее время единственная встроенная стратегия — 'link-next', что эквивалентно lambda { |info| info['header']['link']['rel="next"'].default(nil) }.

Пример: Выполнение поиска GitHub и сбор до 3 страниц результатов.

r.http("https://api.github.com/search/code?q=addClass+user:mozilla",
       :page => 'link-next', :page_limit => 3).run(conn)

В качестве функции, page принимает один параметр, объект формата:

{
    :params => object, # the URL parameters used in the last request
    :header => object, # the HTTP headers of the last response as key/value pairs
    :body => value # the body of the last response in the format specified by `result_format`
}

Поле header будет содержать обработанную версию заголовка с полями в нижнем регистре, например:

{
    'content-length' => '1024',
    'content-type' => 'application/json',
    'date' => 'Thu, 1 Jan 1970 00:00:00 GMT',
    'link' => {
        'rel="last"' => 'http://example.com/?page=34',
        'rel="next"' => 'http://example.com/?page=2'
    }
}

Функция page может возвратить строку, соответствующую следующему URL-адресу для запроса, nil, указывающее, что больше данных нет, или объект формата:

{
    :url => string, # the next URL to request, or nil for no more pages
    :params => object # new URL parameters to use, will be merged with the previous request's params
}

Пример: Выполнение пейджирования с настраиваемой функцией page.

r.http('example.com/pages',
       :page => lambda {|info| info['body']['meta']['next'].default(nil)},
       :page_limit => 5).run(conn)

Дополнительная информация

См. учебник по r.http для получения дополнительных примеров использования этой команды.