下载

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 是一个命令，则运行该命令，并将输出发送到它的标准输入。

如果提供了 downloader 关键字参数，则它必须是 Downloader 对象。资源和连接将在由相同 Downloader 执行的下载之间共享，并在对象被垃圾回收或在一段宽限期内没有使用它执行任何下载时自动清理。有关配置和用法的更多信息，请参阅 Downloader。

如果提供了 headers 关键字参数，则它必须是一个向量或字典，其元素都是字符串对。这些对在下载支持它们的协议（如 HTTP/S）的 URL 时作为标头传递。

timeout 关键字参数指定下载完成的超时时间（以秒为单位），分辨率为毫秒。默认情况下，不设置超时，但也可以通过传递 Inf 的超时值来显式请求。另外，如果 20 秒内没有收到任何数据，下载将超时。请参阅扩展帮助以了解如何禁用此超时。

如果提供了 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 参数是调试事件的描述。

扩展帮助

对于进一步的自定义，请使用 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)

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，则响应的主体将写入 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：捕获可用响应信息的响应对象

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

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

Downloader 对象用于执行单个 download 操作。连接、名称查找和其他资源在 Downloader 内共享。这些连接和资源会在自上次使用它们下载任何内容起可配置的宽限期（默认：30 秒）后或在进行垃圾回收时清理，以先发生者为准。如果宽限期设置为零，则一旦没有更多正在进行的下载，所有资源将立即清理。如果宽限期设置为 Inf，则资源不会被清理，直到 Downloader 被垃圾回收。