Документация Engee

Загрузка файлов

download(url, [ output = tempname() ];
    [ method = "GET", ]
    [ headers = <none>, ]
    [ timeout = <none>, ]
    [ progress = <none>, ]
    [ verbose = false, ]
    [ debug = <none>, ]
    [ downloader = <default>, ]
) -> output

    url        :: AbstractString
    output     :: Union{AbstractString, AbstractCmd, IO}
    method     :: AbstractString
    headers    :: Union{AbstractVector, AbstractDict}
    timeout    :: Real
    progress   :: (total::Integer, now::Integer) --> Any
    verbose    :: Bool
    debug      :: (type, message) --> Any
    downloader :: Downloader

Скачивает файл с заданного URL-адреса и сохраняет его в расположении output или, если оно не указано, по временному пути. Аргумент output может также содержать дескриптор IO. В этом случае тело ответа передается в данный дескриптор, который затем возвращается. Если output — это команда, она выполняется, и результат отправляется в stdin.

Если указан именованный аргумент downloader, он должен содержать объект Downloader. При выполнении скачиваний объектом Downloader используются одни и те же ресурсы и подключения, которые очищаются автоматически, когда этот объект удаляется сборщиком мусора или если объект не выполнял скачиваний в течение периода ожидания. Дополнительные сведения о настройке и использовании см. в описании Downloader.

Если указан именованный аргумент headers, он должен содержать вектор или словарь, все элементы которого — это пары строк. Эти пары передаются как заголовки при скачивании с URL-адресов по поддерживаемым протоколам, например HTTP/S.

Именованный аргумент timeout задает время ожидания для скачивания в секундах с миллисекундным разрешением. По умолчанию время ожидания не задано, но его можно запросить явным образом, передав значение времени ожидания Inf.

Если указан именованный аргумент progress, он должен содержать функцию обратного вызова, которая будет вызываться при изменении размера и состояния текущего скачивания. Обратный вызов должен принимать два целочисленных аргумента: total и now. Они представляют общий размер скачивания в байтах и количество уже скачанных байтов. Обратите внимание, что total имеет нулевое начальное значение, которое сохраняется, пока сервер не сообщит общий размер скачивания (например, в заголовке Content-Length), что может и не произойти. Поэтому корректный обратный вызов хода выполнения должен правильно обрабатывать нулевой общий размер.

Если параметр verbose имеет значение true, модуль libcurl, реализующий функции скачивания, выводит отладочную информацию в stderr. Если в параметре debug указана функция, принимающая два аргумента типа String, параметр verbose игнорируется и вместо этого данные, которые должны выводиться в stderr, передаются в обратный вызов debug с аргументами type и message. Аргумент type указывает, событие какого типа произошло, и может иметь одно из следующих значений: TEXT, HEADER IN, HEADER OUT, DATA IN, DATA OUT, SSL DATA IN или SSL DATA OUT. Аргумент message — это описание события отладки.

request(url;
    [ input = <none>, ]
    [ output = <none>, ]
    [ method = input ? "PUT" : output ? "GET" : "HEAD", ]
    [ headers = <none>, ]
    [ timeout = <none>, ]
    [ progress = <none>, ]
    [ verbose = false, ]
    [ debug = <none>, ]
    [ throw = true, ]
    [ downloader = <default>, ]
) -> Union{Response, RequestError}

    url        :: AbstractString
    input      :: Union{AbstractString, AbstractCmd, IO}
    output     :: Union{AbstractString, AbstractCmd, IO}
    method     :: AbstractString
    headers    :: Union{AbstractVector, AbstractDict}
    timeout    :: Real
    progress   :: (dl_total, dl_now, ul_total, ul_now) --> Any
    verbose    :: Bool
    debug      :: (type, message) --> Any
    throw      :: Bool
    downloader :: Downloader

Выполняет запрос к указанному URL-адресу, возвращая объект Response с состоянием, заголовками и другой информацией об ответе. Тело ответа записывается в output, если этот аргумент указан, или отбрасывается в противном случае. Если при запросе по HTTP/S указан поток input, выполняется запрос PUT; в противном случае, если указан поток output, выполняется запрос GET. Если не указан ни тот, ни другой поток, выполняется запрос HEAD. Для других протоколов используются соответствующие методы по умолчанию в зависимости от запрошенного сочетания входного и выходного потоков. Следующие параметры отличаются от параметров функции download:

  • input позволяет предоставить тело запроса; если оно предоставлено, по умолчанию выполняется запрос PUT.

  • progress — это обратный вызов, принимающий четыре целочисленных аргумента для отслеживания хода отправки и скачивания.

  • throw определяет, следует ли вызвать или вернуть RequestError в случае ошибки запроса.

Обратите внимание, что, в отличие от функции download, которая выдает ошибку, если с запрошенного URL-адреса не удалось выполнить скачивание (о чем свидетельствует код состояния, отличный от 2xx), request возвращает объект Response независимо от кода состояния в ответе. Если вообще не удается получить ответ, вызывается или возвращается ошибка RequestError.

struct Response
    proto   :: String
    url     :: String
    status  :: Int
    message :: String
    headers :: Vector{Pair{String,String}}
end

Response — это тип, содержащий свойства успешного ответа на запрос в виде объекта. Он имеет следующие поля:

  • proto: протокол, использовавшийся для получения ответа;

  • url: URL-адрес, который был запрошен в итоге после всех перенаправлений;

  • status: код состояния ответа — успех, сбой и т. д.;

  • message: текстовое сообщение с описанием характера ответа;

  • headers: заголовки, которые были возвращены с ответом.

Смысл и доступность некоторых из этих ответов зависят от протокола, используемого для запроса. Для многих протоколов, включая HTTP/S и S/FTP, код состояния 2xx означает успешный ответ. Для ответов по протоколам, которые не поддерживают заголовки, вектор заголовков будет пуст. Протокол HTTP/2 не предполагает сообщения о состоянии, только код состояния, поэтому сообщение будет пустым.

struct RequestError <: ErrorException
    url      :: String
    code     :: Int
    message  :: String
    response :: Response
end

RequestError — это тип, содержащий свойства неудачного ответа на запрос в виде объекта исключения:

  • url: исходный запрошенный URL-адрес без перенаправлений;

  • code: код ошибки libcurl; 0, если произошла ошибка, связанная исключительно с протоколом;

  • message: сообщение об ошибке libcurl, указывающее, какая именно проблема возникла;

  • response: объект ответа со всей доступной информацией об ответе.

Такая же ошибка RequestError выдается функцией download, если запрос был выполнен успешно, но произошла ошибка на уровне протокола с кодом состояния вне диапазона 2xx. В этом случае code будет иметь нулевое значение, а поле message будет содержать пустую строку. API request выдает ошибку RequestError, только если код (code) ошибки libcurl отличен от нуля, в случае чего объект response, скорее всего, будет иметь нулевое значение status и пустое сообщение. Однако возможны ситуации, когда ошибка на уровне curl возникает из-за ошибки на уровне протокола. В этом случае интерес могут представлять как внутренние, так и внешние код и сообщение.

Downloader(; [ grace::Real = 30 ])

Объекты Downloader служат для выполнения отдельных операций download. Объект Downloader использует одни и те же подключения, преобразования имен и другие ресурсы. Эти подключения и ресурсы очищаются по истечении настраиваемого периода ожидания (по умолчанию 30 секунд) с момента последнего скачивания или в процессе сборки мусора в зависимости от того, что произойдет раньше. Если задан нулевой период ожидания, все ресурсы очищаются, как только не остается текущих операций скачивания. Если задан период ожидания Inf, то ресурсы очищаются только при удалении объекта Downloader сборщиком мусора.