Команда 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(
    lambda i: r.http('http://httpbin.org/get', params={'user': i})
).run(conn)

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

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

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

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

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(None).

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

{
    'url': string, # the next URL to request, or None 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(None)),
    page_limit=5
).run(conn)

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

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