下載

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 的逾時值來明確要求。另外，如果在未收到任何資料的情況下經過 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_hook。例如，若要在未收到資料時停用 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

對指定的網址提出要求，傳回 Response 物件，其中包含回應的狀態、標頭及其他資訊。如果已指定，回應的主體會寫入 output，否則會捨棄。對於 HTTP/S 要求，如果已提供 input 串流，則會提出 PUT 要求；否則如果已提供 output 串流，則會提出 GET 要求；如果兩者都沒有提供，則會提出 HEAD 要求。對於其他通訊協定，會根據所要求的輸入和輸出組合使用適當的預設方法。下列選項與 download 函式不同

• input 允許提供要求主體；如果已提供，預設為 PUT 要求
• progress 是回呼，會針對上傳和下載進度擷取四個整數
• throw 控制是否在要求錯誤時擲回或傳回 RequestError

請注意，與 download 不同（如果無法下載所要求的網址，則會擲回錯誤，由非 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 物件此時很可能會有一個狀態為零且訊息為空的訊息。然而，有時候會因為協定錯誤而擲出 curl 層級錯誤，此時內外層的 code 和訊息都可能是有用的。

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

Downloader 物件用於執行個別的 download 作業。連線、名稱查詢和其他資源會在 Downloader 內部共用。這些連線和資源會在自上次下載後經過一段可設定的寬限期（預設：30 秒）或垃圾回收時清除，以先發生的為準。如果寬限期設為零，只要沒有正在進行的下載，所有資源就會立即清除。如果寬限期設為 Inf，則資源會等到 Downloader 被垃圾回收時才清除。