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

Descarga un archivo desde la URL dada, guardándolo en output o, si no se especifica, en una ruta temporal. El output también puede ser un manejador IO, en cuyo caso el cuerpo de la respuesta se transmite a ese manejador y se devuelve el manejador. Si output es un comando, el comando se ejecuta y la salida se envía a él a través de stdin.

Si se proporciona el argumento de palabra clave downloader, debe ser un objeto Downloader. Los recursos y conexiones se compartirán entre las descargas realizadas por el mismo Downloader y se limpiarán automáticamente cuando el objeto sea recolectado por el garbage collector o no se hayan realizado descargas con él durante un período de gracia. Consulta Downloader para obtener más información sobre la configuración y el uso.

Si se proporciona el argumento de palabra clave headers, debe ser un vector o diccionario cuyos elementos son todos pares de cadenas. Estos pares se pasan como encabezados al descargar URLs con protocolos que los admiten, como HTTP/S.

El argumento de palabra clave timeout especifica un tiempo de espera para que la descarga se complete en segundos, con una resolución de milisegundos. Por defecto, no se establece ningún tiempo de espera, pero esto también se puede solicitar explícitamente pasando un valor de tiempo de espera de Inf. Por separado, si transcurren 20 segundos sin recibir ningún dato, la descarga se agotará. Consulta la ayuda extendida para saber cómo desactivar este tiempo de espera.

Si se proporciona el argumento de palabra clave progress, debe ser una función de callback que se llamará cada vez que haya actualizaciones sobre el tamaño y el estado de la descarga en curso. El callback debe tomar dos argumentos enteros: total y now, que son el tamaño total de la descarga en bytes y el número de bytes que se han descargado hasta ahora. Ten en cuenta que total comienza en cero y permanece en cero hasta que el servidor da una indicación del tamaño total de la descarga (por ejemplo, con un encabezado Content-Length), lo que puede que nunca suceda. Por lo tanto, un callback de progreso bien comportado debería manejar un tamaño total de cero de manera adecuada.

Si la opción verbose se establece en verdadero, libcurl, que se utiliza para implementar la funcionalidad de descarga, imprimirá información de depuración en stderr. Si la opción debug se establece en una función que acepta dos argumentos String, entonces se ignora la opción verbose y, en su lugar, los datos que se habrían impreso en stderr se pasan al callback debug con los argumentos type y message. El argumento type indica qué tipo de evento ha ocurrido y es uno de: TEXT, HEADER IN, HEADER OUT, DATA IN, DATA OUT, SSL DATA IN o SSL DATA OUT. El argumento message es la descripción del evento de depuración.

Ayuda Extendida

Para una mayor personalización, utiliza un Downloader y easy_hooks. Por ejemplo, para desactivar el tiempo de espera de 20 segundos cuando no se recibe ningún dato, puedes usar lo siguiente:

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

Realiza una solicitud a la URL dada, devolviendo un objeto Response que captura el estado, los encabezados y otra información sobre la respuesta. El cuerpo de la respuesta se escribe en output si se especifica y se descarta de lo contrario. Para solicitudes HTTP/S, si se proporciona un flujo input, se realiza una solicitud PUT; de lo contrario, si se proporciona un flujo output, se realiza una solicitud GET; si no se proporciona ninguno, se realiza una solicitud HEAD. Para otros protocolos, se utilizan métodos predeterminados apropiados según la combinación de entrada y salida solicitada. Las siguientes opciones difieren de la función download:

• input permite proporcionar un cuerpo de solicitud; si se proporciona, se predetermina a la solicitud PUT
• progress es una devolución de llamada que toma cuatro enteros para el progreso de carga y descarga
• throw controla si se lanza o se devuelve un RequestError en caso de error de solicitud

Tenga en cuenta que, a diferencia de download, que lanza un error si la URL solicitada no se pudo descargar (indicado por un código de estado no 2xx), request devuelve un objeto Response sin importar cuál sea el código de estado de la respuesta. Si hay un error al obtener una respuesta, se lanza o se devuelve un RequestError.

Si se proporciona el argumento de palabra clave interrupt, debe ser un objeto Base.Event. Si se activa el evento mientras la solicitud está en progreso, la solicitud se cancelará y se lanzará un error. Esto se puede usar para interrumpir una solicitud de larga duración, por ejemplo, si el usuario desea cancelar una descarga.

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

Response es un tipo que captura las propiedades de una respuesta exitosa a una solicitud como un objeto. Tiene los siguientes campos:

• proto: el protocolo que se utilizó para obtener la respuesta
• url: la URL que se solicitó finalmente después de seguir las redirecciones
• status: el código de estado de la respuesta, que indica éxito, fallo, etc.
• message: un mensaje textual que describe la naturaleza de la respuesta
• headers: cualquier encabezado que se devolvió con la respuesta

El significado y la disponibilidad de algunas de estas respuestas dependen del protocolo utilizado para la solicitud. Para muchos protocolos, incluidos HTTP/S y S/FTP, un código de estado 2xx indica una respuesta exitosa. Para respuestas en protocolos que no admiten encabezados, el vector de encabezados estará vacío. HTTP/2 no incluye un mensaje de estado, solo un código de estado, por lo que el mensaje estará vacío.

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

RequestError es un tipo que captura las propiedades de una respuesta fallida a una solicitud como un objeto de excepción:

• url: la URL original que se solicitó sin redirecciones
• code: el código de error de libcurl; 0 si ocurrió un error solo de protocolo
• message: el mensaje de error de libcurl que indica qué salió mal
• response: objeto de respuesta que captura la información de respuesta disponible

El mismo tipo RequestError es lanzado por download si la solicitud fue exitosa pero hubo un error a nivel de protocolo indicado por un código de estado que no está en el rango de 2xx, en cuyo caso code será cero y el campo message será la cadena vacía. La API request solo lanza un RequestError si el código de error de libcurl es distinto de cero, en cuyo caso el objeto response incluido probablemente tendrá un status de cero y un mensaje vacío. Sin embargo, hay situaciones en las que se lanza un error a nivel de curl debido a un error de protocolo, en cuyo caso tanto el código como el mensaje interno y externo pueden ser de interés.

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

Los objetos Downloader se utilizan para realizar operaciones de download individuales. Las conexiones, las búsquedas de nombres y otros recursos se comparten dentro de un Downloader. Estas conexiones y recursos se limpian después de un período de gracia configurable (por defecto: 30 segundos) desde que se descargó algo con él, o cuando se recolecta como basura, lo que ocurra primero. Si el período de gracia se establece en cero, todos los recursos se limpiarán inmediatamente tan pronto como no haya más descargas en curso. Si el período de gracia se establece en Inf, entonces los recursos no se limpiarán hasta que el Downloader sea recolectado como basura.