Downloads

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

Laden Sie eine Datei von der angegebenen URL herunter und speichern Sie sie in output oder, falls nicht angegeben, an einem temporären Speicherort. Das output kann auch ein IO-Handle sein, in diesem Fall wird der Inhalt der Antwort an dieses Handle gestreamt und das Handle wird zurückgegeben. Wenn output ein Befehl ist, wird der Befehl ausgeführt und die Ausgabe wird über stdin an ihn gesendet.

Wenn das Schlüsselwortargument downloader bereitgestellt wird, muss es sich um ein Downloader-Objekt handeln. Ressourcen und Verbindungen werden zwischen Downloads, die vom selben Downloader durchgeführt werden, geteilt und automatisch bereinigt, wenn das Objekt garbage collected wird oder wenn in einem bestimmten Zeitraum keine Downloads mit ihm durchgeführt wurden. Weitere Informationen zur Konfiguration und Verwendung finden Sie in Downloader.

Wenn das Schlüsselwortargument headers bereitgestellt wird, muss es sich um einen Vektor oder ein Wörterbuch handeln, dessen Elemente alle Paare von Zeichenfolgen sind. Diese Paare werden als Header übergeben, wenn URLs mit Protokollen heruntergeladen werden, die sie unterstützen, wie z.B. HTTP/S.

Das Schlüsselwortargument timeout gibt einen Timeout für den Download in Sekunden an, mit einer Auflösung von Millisekunden. Standardmäßig ist kein Timeout festgelegt, dies kann jedoch auch ausdrücklich angefordert werden, indem ein Timeout-Wert von Inf übergeben wird. Separat, wenn 20 Sekunden vergehen, ohne dass Daten empfangen werden, wird der Download zeitlich begrenzt. Siehe erweiterte Hilfe, um zu erfahren, wie Sie diesen Timeout deaktivieren können.

Wenn das Schlüsselwortargument progress bereitgestellt wird, muss es sich um eine Callback-Funktion handeln, die aufgerufen wird, wann immer es Updates zur Größe und zum Status des laufenden Downloads gibt. Der Callback muss zwei ganzzahlige Argumente annehmen: total und now, die die Gesamtgröße des Downloads in Bytes und die Anzahl der bisher heruntergeladenen Bytes darstellen. Beachten Sie, dass total zu Beginn null ist und null bleibt, bis der Server einen Hinweis auf die Gesamtgröße des Downloads gibt (z.B. mit einem Content-Length-Header), was möglicherweise nie geschieht. Ein gut funktionierender Fortschritts-Callback sollte eine Gesamtgröße von null elegant behandeln.

Wenn die Option verbose auf true gesetzt ist, wird libcurl, das zur Implementierung der Download-Funktionalität verwendet wird, Debugging-Informationen an stderr ausgeben. Wenn die Option debug auf eine Funktion gesetzt ist, die zwei String-Argumente akzeptiert, wird die verbose-Option ignoriert und stattdessen werden die Daten, die an stderr ausgegeben worden wären, an den debug-Callback mit den Argumenten type und message übergeben. Das Argument type gibt an, welche Art von Ereignis aufgetreten ist, und ist eines von: TEXT, HEADER IN, HEADER OUT, DATA IN, DATA OUT, SSL DATA IN oder SSL DATA OUT. Das Argument message ist die Beschreibung des Debug-Ereignisses.

Erweiterte Hilfe

Für weitere Anpassungen verwenden Sie einen Downloader und easy_hooks. Um beispielsweise den 20-Sekunden-Timeout zu deaktivieren, wenn keine Daten empfangen werden, können Sie Folgendes verwenden:

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>, ]
    [ 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

Machen Sie eine Anfrage an die angegebene URL und geben Sie ein Response-Objekt zurück, das den Status, die Header und andere Informationen zur Antwort erfasst. Der Körper der Antwort wird in output geschrieben, wenn angegeben, und andernfalls verworfen. Bei HTTP/S-Anfragen wird, wenn ein input-Stream angegeben ist, eine PUT-Anfrage gestellt; andernfalls, wenn ein output-Stream angegeben ist, wird eine GET-Anfrage gestellt; wenn weder angegeben ist, wird eine HEAD-Anfrage gestellt. Bei anderen Protokollen werden geeignete Standardmethoden basierend auf der angeforderten Kombination von Eingabe und Ausgabe verwendet. Die folgenden Optionen unterscheiden sich von der Funktion download:

• input ermöglicht die Bereitstellung eines Anfragekörpers; wenn bereitgestellt, wird standardmäßig eine PUT-Anfrage gestellt
• progress ist ein Callback, das vier Ganzzahlen für den Upload- und Download-Fortschritt entgegennimmt
• throw steuert, ob bei einem Anforderungsfehler eine Ausnahme ausgelöst oder ein RequestError zurückgegeben wird

Beachten Sie, dass im Gegensatz zu download, das einen Fehler auslöst, wenn die angeforderte URL nicht heruntergeladen werden konnte (angezeigt durch einen Statuscode ungleich 2xx), request ein Response-Objekt zurückgibt, egal was der Statuscode der Antwort ist. Wenn es einen Fehler beim Erhalten einer Antwort gibt, wird ein RequestError ausgelöst oder zurückgegeben.

Wenn das Schlüsselwortargument interrupt bereitgestellt wird, muss es ein Base.Event-Objekt sein. Wenn das Ereignis ausgelöst wird, während die Anfrage in Bearbeitung ist, wird die Anfrage abgebrochen und ein Fehler wird ausgelöst. Dies kann verwendet werden, um eine lang laufende Anfrage zu unterbrechen, beispielsweise wenn der Benutzer einen Download abbrechen möchte.

struct Response
    proto   :: String
    url     :: String
    status  :: Int
    message :: String
    headers :: Vector{Pair{String,String}}
end

Response ist ein Typ, der die Eigenschaften einer erfolgreichen Antwort auf eine Anfrage als Objekt erfasst. Es hat die folgenden Felder:

• proto: das Protokoll, das verwendet wurde, um die Antwort zu erhalten
• url: die URL, die letztendlich nach dem Folgen von Weiterleitungen angefordert wurde
• status: der Statuscode der Antwort, der Erfolg, Misserfolg usw. anzeigt
• message: eine textuelle Nachricht, die die Art der Antwort beschreibt
• headers: alle Header, die mit der Antwort zurückgegeben wurden

Die Bedeutung und Verfügbarkeit einiger dieser Antworten hängt vom verwendeten Protokoll für die Anfrage ab. Für viele Protokolle, einschließlich HTTP/S und S/FTP, zeigt ein 2xx-Statuscode eine erfolgreiche Antwort an. Bei Antworten in Protokollen, die keine Header unterstützen, wird der Header-Vektor leer sein. HTTP/2 enthält keine Statusnachricht, nur einen Statuscode, sodass die Nachricht leer sein wird.

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

RequestError ist ein Typ, der die Eigenschaften einer fehlgeschlagenen Antwort auf eine Anfrage als Ausnahmeobjekt erfasst:

• url: die ursprüngliche URL, die angefordert wurde, ohne Weiterleitungen
• code: der libcurl-Fehlercode; 0, wenn ein nur protokollbezogener Fehler aufgetreten ist
• message: die libcurl-Fehlermeldung, die angibt, was schiefgelaufen ist
• response: Antwortobjekt, das die verfügbaren Antwortinformationen erfasst

Der gleiche RequestError-Typ wird von download ausgelöst, wenn die Anfrage erfolgreich war, aber ein protokollbezogener Fehler durch einen Statuscode angezeigt wurde, der nicht im 2xx-Bereich liegt, in diesem Fall wird code null sein und das Feld message wird der leere String sein. Die request-API wirft nur einen RequestError, wenn der libcurl-Fehler code ungleich null ist, in diesem Fall hat das enthaltene response-Objekt wahrscheinlich einen status von null und eine leere Nachricht. Es gibt jedoch Situationen, in denen ein curl-Fehler aufgrund eines Protokollfehlers ausgelöst wird, in diesem Fall können sowohl der innere als auch der äußere Code und die Nachricht von Interesse sein.

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

Downloader-Objekte werden verwendet, um einzelne download-Operationen durchzuführen. Verbindungen, Namensauflösungen und andere Ressourcen werden innerhalb eines Downloader geteilt. Diese Verbindungen und Ressourcen werden nach einer konfigurierbaren Grace-Periode (Standard: 30 Sekunden) bereinigt, nachdem etwas mit ihm heruntergeladen wurde, oder wenn er garbage collected wird, je nachdem, was zuerst eintritt. Wenn die Grace-Periode auf null gesetzt ist, werden alle Ressourcen sofort bereinigt, sobald keine laufenden Downloads mehr im Gange sind. Wenn die Grace-Periode auf Inf gesetzt ist, werden Ressourcen erst bereinigt, wenn der Downloader garbage collected wird.