Команда ReQL: http

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

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

Описание

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

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

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

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

Параметры

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

• timeout: интервал ожидания в секундах перед прерыванием соединения (по умолчанию 30).
• attempts: количество попыток повтора после неудачных подключений (по умолчанию 5).
• redirects: количество перенаправлений и заголовков расположения для следования (по умолчанию 1).
• verify: если true, проверять сертификат SSL сервера (по умолчанию true).
• resultFormat: строка, определяющая формат возвращаемых результатов. Один из следующих:
  • text: всегда возвращать строку.
  • json: анализировать результат как JSON, вызывая ошибку при неудаче.
  • jsonp: анализировать результат как Padded JSON.
  • 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(function(i) {
    return r.http('http://httpbin.org/get', { params: { user: i } });
}).run(conn, callback)

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

r.table('data').map(function(row) {
    return r.http('http://httpbin.org/put', { method: 'PUT', data: row });
}).run(conn, callback)

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

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

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

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

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

Пагинация

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

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

В настоящее время единственная встроенная стратегия — 'link-next', которая эквивалентна function(info) { return info('header')('link')('rel="next"').default(null); }.

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

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

В качестве функции, 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 `resultFormat`
}

Поле 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 для запроса, null указывая, что больше ничего нет, или объект следующего формата:

{
    url: string // the next URL to request, or null 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: function(info) { return info('body')('meta')('next').default(null); },
         pageLimit: 5 })
.run(conn, callback)

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

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