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

Téléchargez un fichier à partir de l'URL donnée, en le sauvegardant dans output ou, si non spécifié, dans un chemin temporaire. L'output peut également être un handle IO, auquel cas le corps de la réponse est diffusé vers ce handle et le handle est retourné. Si output est une commande, la commande est exécutée et la sortie lui est envoyée sur stdin.

Si l'argument clé downloader est fourni, il doit s'agir d'un objet Downloader. Les ressources et les connexions seront partagées entre les téléchargements effectués par le même Downloader et nettoyées automatiquement lorsque l'objet est collecté par le ramasse-miettes ou qu'aucun téléchargement n'a été effectué avec lui pendant une période de grâce. Voir Downloader pour plus d'informations sur la configuration et l'utilisation.

Si l'argument clé headers est fourni, il doit s'agir d'un vecteur ou d'un dictionnaire dont les éléments sont tous des paires de chaînes. Ces paires sont passées en tant qu'en-têtes lors du téléchargement d'URL avec des protocoles qui les prennent en charge, tels que HTTP/S.

L'argument clé timeout spécifie un délai d'attente pour que le téléchargement soit terminé en secondes, avec une résolution en millisecondes. Par défaut, aucun délai d'attente n'est défini, mais cela peut également être explicitement demandé en passant une valeur de délai d'attente de Inf. Séparément, si 20 secondes s'écoulent sans recevoir de données, le téléchargement expirera. Voir l'aide étendue pour savoir comment désactiver ce délai d'attente.

Si l'argument clé progress est fourni, il doit s'agir d'une fonction de rappel qui sera appelée chaque fois qu'il y a des mises à jour sur la taille et l'état du téléchargement en cours. Le rappel doit prendre deux arguments entiers : total et now, qui sont la taille totale du téléchargement en octets et le nombre d'octets qui ont été téléchargés jusqu'à présent. Notez que total commence à zéro et reste à zéro jusqu'à ce que le serveur donne une indication de la taille totale du téléchargement (par exemple, avec un en-tête Content-Length), ce qui peut ne jamais se produire. Ainsi, un rappel de progression bien conçu devrait gérer une taille totale de zéro de manière appropriée.

Si l'option verbose est définie sur true, libcurl, qui est utilisé pour implémenter la fonctionnalité de téléchargement, imprimera des informations de débogage sur stderr. Si l'option debug est définie sur une fonction acceptant deux arguments String, alors l'option verbose est ignorée et les données qui auraient été imprimées sur stderr sont passées au rappel debug avec les arguments type et message. L'argument type indique quel type d'événement s'est produit, et est l'un des suivants : TEXT, HEADER IN, HEADER OUT, DATA IN, DATA OUT, SSL DATA IN ou SSL DATA OUT. L'argument message est la description de l'événement de débogage.

Aide Étendue

Pour une personnalisation supplémentaire, utilisez un Downloader et des easy_hooks. Par exemple, pour désactiver le délai d'attente de 20 secondes lorsque aucune donnée n'est reçue, vous pouvez utiliser ce qui suit :

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

Faites une requête à l'URL donnée, retournant un objet Response capturant le statut, les en-têtes et d'autres informations sur la réponse. Le corps de la réponse est écrit dans output si spécifié et ignoré sinon. Pour les requêtes HTTP/S, si un flux input est donné, une requête PUT est effectuée ; sinon, si un flux output est donné, une requête GET est effectuée ; si aucun n'est donné, une requête HEAD est effectuée. Pour d'autres protocoles, des méthodes par défaut appropriées sont utilisées en fonction de la combinaison d'input et d'output demandée. Les options suivantes diffèrent de la fonction download :

• input permet de fournir un corps de requête ; si fourni, par défaut à une requête PUT
• progress est un rappel prenant quatre entiers pour le progrès de téléchargement et d'upload
• throw contrôle si une erreur doit être levée ou si une RequestError doit être retournée en cas d'erreur de requête

Notez que contrairement à download qui lève une erreur si l'URL demandée ne peut pas être téléchargée (indiquée par un code de statut non-2xx), request retourne un objet Response peu importe le code de statut de la réponse. S'il y a une erreur pour obtenir une réponse, alors une RequestError est levée ou retournée.

Si l'argument clé interrupt est fourni, il doit s'agir d'un objet Base.Event. Si l'événement est déclenché pendant que la requête est en cours, la requête sera annulée et une erreur sera levée. Cela peut être utilisé pour interrompre une requête de longue durée, par exemple si l'utilisateur souhaite annuler un téléchargement.

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

Response est un type capturant les propriétés d'une réponse réussie à une requête sous forme d'objet. Il a les champs suivants :

• proto : le protocole qui a été utilisé pour obtenir la réponse
• url : l'URL qui a finalement été demandée après avoir suivi les redirections
• status : le code d'état de la réponse, indiquant le succès, l'échec, etc.
• message : un message textuel décrivant la nature de la réponse
• headers : tous les en-têtes qui ont été renvoyés avec la réponse

La signification et la disponibilité de certaines de ces réponses dépendent du protocole utilisé pour la requête. Pour de nombreux protocoles, y compris HTTP/S et S/FTP, un code d'état 2xx indique une réponse réussie. Pour les réponses dans des protocoles qui ne prennent pas en charge les en-têtes, le vecteur d'en-têtes sera vide. HTTP/2 n'inclut pas de message d'état, seulement un code d'état, donc le message sera vide.

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

RequestError est un type capturant les propriétés d'une réponse échouée à une requête en tant qu'objet d'exception :

• url : l'URL d'origine qui a été demandée sans aucune redirection
• code : le code d'erreur libcurl ; 0 si une erreur de protocole uniquement s'est produite
• message : le message d'erreur libcurl indiquant ce qui a mal tourné
• response : objet de réponse capturant les informations de réponse disponibles

Le même type RequestError est lancé par download si la requête a réussi mais qu'il y avait une erreur au niveau du protocole indiquée par un code d'état qui n'est pas dans la plage 2xx, auquel cas code sera zéro et le champ message sera une chaîne vide. L'API request ne lance une RequestError que si le code d'erreur libcurl est non nul, auquel cas l'objet response inclus aura probablement un status de zéro et un message vide. Cependant, il existe des situations où une erreur au niveau de curl est lancée en raison d'une erreur de protocole, auquel cas à la fois le code et le message internes et externes peuvent être d'un intérêt.

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

Les objets Downloader sont utilisés pour effectuer des opérations de download individuelles. Les connexions, les recherches de noms et d'autres ressources sont partagées au sein d'un Downloader. Ces connexions et ressources sont nettoyées après une période de grâce configurable (par défaut : 30 secondes) depuis la dernière opération de téléchargement effectuée avec celui-ci, ou lorsqu'il est collecté par le ramasse-miettes, selon la première éventualité. Si la période de grâce est fixée à zéro, toutes les ressources seront nettoyées immédiatement dès qu'il n'y a plus de téléchargements en cours. Si la période de grâce est fixée à Inf, alors les ressources ne seront pas nettoyées tant que le Downloader n'est pas collecté par le ramasse-miettes.