Downloads

Downloads.download — Function

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 关键字参数，则它必须是一个向量或字典，其元素都是字符串对。这些对在下载支持它们的协议（如 HTTP/S）的 URL 时作为头部传递。

timeout 关键字参数指定下载完成的超时时间（以秒为单位），分辨率为毫秒。默认情况下未设置超时，但也可以通过传递超时值 Inf 明确请求。单独地，如果在 20 秒内没有接收到任何数据，则下载将超时。有关如何禁用此超时的扩展帮助，请参见。

如果提供了 progress 关键字参数，则它必须是一个回调函数，该函数将在有关正在进行的下载的大小和状态有更新时被调用。回调必须接受两个整数参数：total 和 now，它们分别是下载的总大小（以字节为单位）和到目前为止已下载的字节数。请注意，total 初始为零，并且在服务器给出下载总大小的指示（例如，通过 Content-Length 头）之前保持为零，这可能永远不会发生。因此，一个良好的进度回调应该优雅地处理总大小为零的情况。

如果将 verbose 选项设置为 true，则用于实现下载功能的 libcurl 将向 stderr 打印调试信息。如果将 debug 选项设置为接受两个 String 参数的函数，则将忽略详细选项，而是将本应打印到 stderr 的数据传递给 debug 回调，参数为 type 和 message。type 参数指示发生了什么类型的事件，可能是：TEXT、HEADER IN、HEADER OUT、DATA IN、DATA OUT、SSL DATA IN 或 SSL DATA OUT。message 参数是调试事件的描述。

扩展帮助

有关进一步的自定义，请使用 Downloader 和 easy_hooks。例如，要在未接收到数据时禁用 20 秒超时，可以使用以下代码：

downloader = Downloads.Downloader()
downloader.easy_hook = (easy, info) -> Downloads.Curl.setopt(easy, Downloads.Curl.CURLOPT_LOW_SPEED_TIME, 0)

Downloads.download("https://httpbingo.julialang.org/delay/30"; downloader)

source

Downloads.request — Function

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>, ]
    [ interrupt = <none>, ]
) -> 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
    interrupt  :: Base.Event

向给定的 URL 发起请求，返回一个 Response 对象，捕获状态、头信息和关于响应的其他信息。如果指定了 output，响应的主体将被写入 output，否则将被丢弃。对于 HTTP/S 请求，如果给定了 input 流，则发起 PUT 请求；否则如果给定了 output 流，则发起 GET 请求；如果两者都没有，则发起 HEAD 请求。对于其他协议，将根据请求的输入和输出组合使用适当的默认方法。以下选项与 download 函数不同：

input 允许提供请求主体；如果提供，则默认为 PUT 请求
progress 是一个回调，接受四个整数用于上传和下载进度
throw 控制在请求错误时是抛出异常还是返回 RequestError

请注意，与 download 不同，如果请求的 URL 无法下载（由非 2xx 状态码指示），request 无论响应的状态码是什么都会返回一个 Response 对象。如果在获取响应时出现错误，则会抛出或返回 RequestError。

如果提供了 interrupt 关键字参数，它必须是一个 Base.Event 对象。如果在请求进行时触发该事件，请求将被取消并抛出错误。这可以用于中断长时间运行的请求，例如如果用户想要取消下载。

source

Downloads.Response — Type

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 不包括状态消息，仅包含状态码，因此消息将为空。

source

Downloads.RequestError — Type

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

RequestError 是一个类型，用于捕获请求失败响应的属性作为异常对象：

url: 原始请求的 URL，没有任何重定向
code: libcurl 错误代码；如果发生了仅协议错误，则为 0
message: libcurl 错误消息，指示出了什么问题
response: 捕获可用响应信息的响应对象

如果请求成功但由于状态代码不在 2xx 范围内而指示存在协议级别错误，则相同的 RequestError 类型会被 download 抛出，此时 code 将为零，message 字段将为空字符串。request API 仅在 libcurl 错误 code 非零时抛出 RequestError，在这种情况下，包含的 response 对象可能会有 status 为零和空消息。然而，也存在由于协议错误而抛出 curl 级别错误的情况，在这种情况下，内部和外部的代码和消息都可能是重要的。

source

Downloads.Downloader — Type

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

Downloader 对象用于执行单个 download 操作。连接、名称查找和其他资源在 Downloader 内部共享。这些连接和资源将在配置的宽限期（默认：30 秒）后清理，宽限期从最后一次下载开始计算，或者在其被垃圾回收时，二者以先到者为准。如果宽限期设置为零，则所有资源将在没有更多进行中的下载时立即清理。如果宽限期设置为 Inf，则资源不会被清理，直到 Downloader 被垃圾回收。

source