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秒間データを受信しない場合、ダウンロードはタイムアウトします。このタイムアウトを無効にする方法については、extended helpを参照してください。

progressキーワード引数が提供される場合、それは進行中のダウンロードのサイズとステータスに関する更新があるたびに呼び出されるコールバック関数でなければなりません。コールバックは、ダウンロードの合計サイズ（バイト単位）と、これまでにダウンロードされたバイト数を表す2つの整数引数totalとnowを取る必要があります。totalは最初はゼロで、サーバーがダウンロードの合計サイズを示す（例：Content-Lengthヘッダーで）までゼロのままです。したがって、適切に動作するプログレスコールバックは、合計サイズがゼロであることを適切に処理する必要があります。

verboseオプションがtrueに設定されている場合、ダウンロード機能を実装するために使用されるlibcurlは、デバッグ情報をstderrに出力します。debugオプションが2つのString引数を受け取る関数に設定されている場合、verboseオプションは無視され、代わりにstderrに出力されるはずのデータがtypeとmessage引数を持つdebugコールバックに渡されます。type引数は、どのようなイベントが発生したかを示し、TEXT、HEADER IN、HEADER OUT、DATA IN、DATA OUT、SSL DATA INまたはSSL DATA OUTのいずれかです。message引数はデバッグイベントの説明です。

Extended Help

さらなるカスタマイズには、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に書き込まれ、そうでない場合は破棄されます。HTTP/Sリクエストの場合、inputストリームが指定されている場合はPUTリクエストが行われます。そうでない場合、outputストリームが指定されている場合はGETリクエストが行われます。どちらも指定されていない場合はHEADリクエストが行われます。他のプロトコルの場合、要求された入力と出力の組み合わせに基づいて適切なデフォルトメソッドが使用されます。以下のオプションはdownload関数とは異なります：

inputはリクエストボディを提供することを可能にします。提供された場合はデフォルトでPUTリクエストになります。
progressはアップロードとダウンロードの進行状況のための4つの整数を受け取るコールバックです。
throwはリクエストエラーが発生した場合にRequestErrorをスローするかどうかを制御します。

要求されたURLがダウンロードできなかった場合（非2xxステータスコードで示される）にエラーをスローするdownloadとは異なり、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: 利用可能なレスポンス情報をキャプチャするレスポンスオブジェクト

同じ RequestError 型は、リクエストが成功したが、2xx範囲外のステータスコードによってプロトコルレベルのエラーが示された場合に 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