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 がコマンドの場合は、そのコマンドを実行し、標準入力に出力を送ります。
キーワード引数 downloader を指定する場合、その値は Downloader オブジェクトでなければなりません。同じ Downloader で実行されるダウンロード間では、リソースと接続が共有されます。オブジェクトがガベージコレクションされるか、一定の猶予期間にわたってそのオブジェクトを使ったダウンロードが行われなかった場合、リソースと接続は自動的に解放されます。設定と使用方法については、Downloader を参照してください。
キーワード引数 headers を指定する場合、その値は、要素がすべて文字列のペアであるベクターまたは辞書でなければなりません。これらのペアは、HTTP/S など、ヘッダーに対応するプロトコルで URL をダウンロードする際にヘッダーとして渡されます。
キーワード引数 timeout は、ダウンロード完了までのタイムアウトを秒単位(ミリ秒精度)で指定します。デフォルトではタイムアウトは設定されませんが、タイムアウト値に Inf を渡すことで、明示的にタイムアウトなしを指定することもできます。これとは別に、データを受信しない状態が20秒続くと、ダウンロードはタイムアウトします。このタイムアウトを無効にする方法については、拡張ヘルプを参照してください。
キーワード引数 progress を指定する場合、その値は、ダウンロードのサイズや進行状況に関する更新があるたびに呼び出されるコールバック関数でなければなりません。コールバックは、ダウンロードの合計サイズ(バイト単位)を表す total と、これまでにダウンロードされたバイト数を表す now の2つの整数引数を受け取る必要があります。total は最初は0で、サーバーからダウンロードの合計サイズを示す情報(たとえば Content-Length ヘッダー)が提供されるまで0のままです。こうした情報が提供されない場合もあります。そのため、適切な進捗コールバックは、合計サイズが0の場合も問題なく処理できる必要があります。
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)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 オブジェクトでなければなりません。リクエストの実行中にイベントが発生すると、リクエストはキャンセルされ、エラーがスローされます。たとえば、ユーザーがダウンロードをキャンセルしたい場合など、時間のかかるリクエストを中断するために使用できます。
Downloads.Response — Type
struct Response
proto :: String
url :: String
status :: Int
message :: String
headers :: Vector{Pair{String,String}}
endResponseは、リクエストに対する成功レスポンスの情報をオブジェクトとして保持する型です。次のフィールドがあります。
proto: レスポンスの取得に使用したプロトコルurl: リダイレクトをたどった後、最終的にリクエストされたURLstatus: 成功や失敗などを示すレスポンスのステータスコードmessage: レスポンスの内容を説明するテキストメッセージheaders: レスポンスに含まれていたヘッダー
これらのレスポンス情報の一部は、その意味や利用可否がリクエストに使用したプロトコルによって異なります。HTTP/SやS/FTPを含む多くのプロトコルでは、2xxのステータスコードは成功レスポンスを示します。ヘッダーをサポートしないプロトコルのレスポンスでは、ヘッダーのベクターは空になります。HTTP/2にはステータスメッセージがなく、ステータスコードのみが含まれるため、メッセージは空になります。
Downloads.RequestError — Type
struct RequestError <: ErrorException
url :: String
code :: Int
message :: String
response :: Response
endRequestErrorは、リクエストへの応答が失敗した際の情報を例外オブジェクトとして保持する型です。
url: リダイレクトを経由する前の、リクエスト対象の元のURLcode: libcurlのエラーコード。プロトコルのみのエラーが発生した場合は0message: エラーの内容を示すlibcurlのエラーメッセージresponse: 取得可能な応答情報を保持する応答オブジェクト
リクエスト自体は成功したものの、2xxの範囲外のステータスコードで示されるプロトコルレベルのエラーが発生した場合も、downloadは同じRequestError型をスローします。この場合、codeはゼロ、messageフィールドは空文字列になります。request APIがRequestErrorをスローするのは、libcurlのエラーcodeがゼロ以外の場合に限られます。この場合、含まれるresponseオブジェクトのstatusはゼロで、メッセージも空である可能性が高いです。ただし、プロトコルエラーが原因でcurlレベルのエラーがスローされる場合もあり、その場合は内側と外側の両方のコードとメッセージが重要になることがあります。
Downloads.Downloader — Type
Downloader(; [ grace::Real = 30 ])Downloader オブジェクトは、個々の download 操作を実行するために使用されます。接続、名前検索、その他のリソースは、同じ Downloader 内で共有されます。これらの接続とリソースは、設定可能な猶予期間(デフォルトは30秒)が経過した後、またはガベージコレクションされた時点のいずれか早い方で解放されます。猶予期間をゼロに設定すると、進行中のダウンロードがすべて完了した時点で、すべてのリソースが直ちに解放されます。猶予期間を Inf に設定した場合、Downloader がガベージコレクションされるまで、リソースは解放されません。