Команда ReQL: http

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

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

Описание

Получает данные с указанного URL по протоколу HTTP. Тип возвращаемого значения зависит от опции resultFormat, которая по умолчанию проверяет Content-Type ответа.

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

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

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

Параметры

Эти параметры задаются с помощью команды optArg.

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

• timeout: время ожидания в секундах перед прерыванием соединения (по умолчанию 30).
• attempts: количество попыток повтора после неудачных соединений (по умолчанию 5).
• redirects: количество перенаправлений и заголовков расположения для следования (по умолчанию 1).
• verify: если true, проверять сертификат SSL сервера (по умолчанию true).
• resultFormat: строка, определяющая формат возвращаемых результатов. Один из следующих:
  • text: всегда возвращать строку.
  • json: анализировать результат как JSON, вызывая ошибку при неудаче.
  • jsonp: анализировать результат как 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: hashMap или объект, определяющий параметры 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, данные могут быть либо объектом (который будет записан в тело как пары ключ/значение в формате form-encoded), либо строкой; для всех других запросов данные будут сериализованы в JSON и помещены в тело запроса, отправленные как Content-Type: application/json. По умолчанию данные не отправляются.

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

r.expr(r.array(1, 2, 3)).map(
    i -> r.http("http://httpbin.org/get")
          .optArg("params", r.hashMap("user", i))
).run(conn);

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

r.table("data").map(
    row -> r.http("http://httpbin.org/put")
            .optArg("method", "PUT")
            .optArg("data", row)
).run(conn);

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

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

r.http("http://httpbin.org/post").optArg("method", "POST")
 .optArg("data", r.hashMap("player", "Bob").with("game", "tic tac toe"))
 .run(conn);

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

r.http("http://httpbin.org/post").optArg("method", "POST")
 .optArg("data", r.expr(value).coerceTo("string"))
 .optArg("header", r.hashMap("Content-Type", "application/json"))
 .run(conn);

Пейджинг

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

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

В настоящее время единственной встроенной стратегией является link-next, которая эквивалентна info -> info.g("header").g("link").g("rel='next'").default_(null).

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

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

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

{
    "params": object,  // the URL parameters used in the last request
    "header": object,  // the 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")
 .optArg("page", info -> info.g("body").g("meta").g("next").default_(null))
 .optArg("page_limit", 5)
 .run(conn);

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

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