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

Verilen url'den bir dosya indirin, output'a kaydedin veya belirtilmemişse geçici bir yola kaydedin. output ayrıca bir IO handle'ı da olabilir, bu durumda yanıtın gövdesi o handle'a akıtılır ve handle döndürülür. Eğer output bir komutsa, komut çalıştırılır ve çıktı stdin'e gönderilir.

Eğer downloader anahtar argümanı sağlanmışsa, bu bir Downloader nesnesi olmalıdır. Kaynaklar ve bağlantılar, aynı Downloader tarafından gerçekleştirilen indirmeler arasında paylaşılacak ve nesne çöp toplandığında veya onunla hiçbir indirme gerçekleştirilmediğinde otomatik olarak temizlenecektir. Konfigürasyon ve kullanım hakkında daha fazla bilgi için Downloader'a bakın.

Eğer headers anahtar argümanı sağlanmışsa, bu tüm elemanları string çiftleri olan bir vektör veya sözlük olmalıdır. Bu çiftler, HTTP/S gibi bunları destekleyen protokollerle URL'leri indirirken başlıklar olarak geçilir.

timeout anahtar argümanı, indirmenin tamamlanması için saniye cinsinden bir zaman aşımını belirtir ve milisaniye çözünürlüğüne sahiptir. Varsayılan olarak zaman aşımı ayarlanmamıştır, ancak bu, Inf zaman aşımı değeri geçilerek açıkça talep edilebilir. Ayrıca, 20 saniye boyunca herhangi bir veri alınmazsa, indirme zaman aşımına uğrayacaktır. Bu zaman aşımını devre dışı bırakma hakkında daha fazla yardım için genişletilmiş yardıma bakın.

Eğer progress anahtar argmanı sağlanmışsa, bu, devam eden indirme hakkında boyut ve durum güncellemeleri olduğunda çağrılacak bir geri çağırma fonksiyonu olmalıdır. Geri çağırma, toplam indirme boyutu byte cinsinden total ve şu ana kadar indirilen byte sayısı now olmak üzere iki tam sayı argümanı almalıdır. total sıfırdan başlar ve sunucu toplam indirme boyutunun bir göstergesini verene kadar sıfır kalır (örneğin, bir Content-Length başlığı ile), bu asla olmayabilir. Bu nedenle, iyi davranan bir ilerleme geri çağırması, toplam boyutu sıfır olan durumları zarif bir şekilde ele almalıdır.

Eğer verbose seçeneği true olarak ayarlanmışsa, indirme işlevselliğini uygulamak için kullanılan libcurl, hata ayıklama bilgilerini stderr'ye yazdıracaktır. Eğer debug seçeneği iki String argümanı kabul eden bir fonksiyona ayarlanmışsa, o zaman ayrıntılı seçenek göz ardı edilir ve bunun yerine stderr'ye yazdırılacak olan veriler type ve message argümanları ile debug geri çağırmasına iletilir. type argümanı, hangi tür olayın meydana geldiğini belirtir ve şunlardan biridir: TEXT, HEADER IN, HEADER OUT, DATA IN, DATA OUT, SSL DATA IN veya SSL DATA OUT. message argümanı, hata ayıklama olayının tanımıdır.

Genişletilmiş Yardım

Daha fazla özelleştirme için, bir Downloader ve easy_hooks kullanın. Örneğin, veri alınmadığında 20 saniyelik zaman aşımını devre dışı bırakmak için aşağıdakileri kullanabilirsiniz:

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)

verilen url'ye bir istek yapın ve yanıtın durumu, başlıkları ve diğer bilgileri yakalayan bir `Response` nesnesi döndürün. Yanıtın gövdesi, belirtilmişse `output`'a yazılır, aksi takdirde atılır. HTTP/S istekleri için, bir `input` akışı verilmişse, bir `PUT` isteği yapılır; aksi takdirde bir `output` akışı verilmişse, bir `GET` isteği yapılır; eğer ikisi de verilmemişse bir `HEAD` isteği yapılır. Diğer protokoller için, istenen giriş ve çıkış kombinasyonuna dayalı olarak uygun varsayılan yöntemler kullanılır. Aşağıdaki seçenekler `download` işlevinden farklıdır:

  * `input`, bir istek gövdesi sağlamaya olanak tanır; sağlanırsa varsayılan olarak `PUT` isteğine geçer
  * `progress`, yükleme ve indirme ilerlemesi için dört tam sayı alan bir geri çağırmadır
  * `throw`, istek hatası durumunda bir `RequestError` fırlatılıp fırlatılmayacağını kontrol eder

`download`'ın aksine, istenen URL indirilemediğinde (2xx dışı durum kodu ile gösterilir) bir hata fırlatırken, `request` yanıtın durum kodu ne olursa olsun bir `Response` nesnesi döndürür. Eğer bir yanıt almakta bir hata varsa, o zaman bir `RequestError` fırlatılır veya döndürülür.

`interrupt` anahtar argümanı sağlanırsa, bir `Base.Event` nesnesi olmalıdır. İstek devam ederken olay tetiklenirse, istek iptal edilir ve bir hata fırlatılır. Bu, örneğin kullanıcının bir indirmeyi iptal etmek istemesi durumunda uzun süren bir isteği kesmek için kullanılabilir.

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

Response bir isteğe başarılı bir yanıtın özelliklerini bir nesne olarak yakalayan bir türdür. Aşağıdaki alanlara sahiptir:

• proto: yanıtı almak için kullanılan protokol
• url: yönlendirmeleri takip ettikten sonra nihayetinde istenen URL
• status: yanıtın durum kodu, başarı, başarısızlık vb. durumları belirtir.
• message: yanıtın niteliğini tanımlayan bir metin mesajı
• headers: yanıtla birlikte dönen herhangi bir başlık

Bu yanıtların bazılarının anlamı ve kullanılabilirliği, istekte kullanılan protokole bağlıdır. HTTP/S ve S/FTP dahil birçok protokolde, 2xx durum kodu başarılı bir yanıtı belirtir. Başlıkları desteklemeyen protokollerdeki yanıtlar için başlıklar vektörü boş olacaktır. HTTP/2, yalnızca bir durum kodu içerir, durum mesajı içermez, bu nedenle mesaj boş olacaktır.

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

RequestError, bir isteğe verilen başarısız yanıtın özelliklerini bir istisna nesnesi olarak yakalayan bir türdür:

• url: yönlendirme olmadan talep edilen orijinal URL
• code: libcurl hata kodu; yalnızca bir protokol hatası meydana geldiyse 0
• message: neyin yanlış gittiğini belirten libcurl hata mesajı
• response: mevcut yanıt bilgilerini yakalayan yanıt nesnesi

Aynı RequestError türü, istek başarılı olsa bile, 2xx aralığında olmayan bir durum kodu ile gösterilen bir protokol düzeyi hatası varsa download tarafından fırlatılır; bu durumda code sıfır olacak ve message alanı boş bir dize olacaktır. request API'si yalnızca libcurl hata code'u sıfırdan farklı olduğunda bir RequestError fırlatır; bu durumda dahil edilen response nesnesinin muhtemelen sıfır bir status ve boş bir mesajı olacaktır. Ancak, bir protokol hatası nedeniyle bir curl düzeyi hatası fırlatılan durumlar da vardır; bu durumda hem iç hem de dış kod ve mesaj ilgi çekici olabilir.

Downloader(; [ grace::Gerçek = 30 ])

Downloader nesneleri, bireysel download işlemlerini gerçekleştirmek için kullanılır. Bağlantılar, ad aramaları ve diğer kaynaklar bir Downloader içinde paylaşılır. Bu bağlantılar ve kaynaklar, onunla bir şey indirildiğinden itibaren yapılandırılabilir bir grace süresi (varsayılan: 30 saniye) sonra veya çöp toplayıcı tarafından temizlendiğinde, hangisi önce gelirse, temizlenir. Grace süresi sıfıra ayarlanırsa, devam eden indirme işlemi kalmadığında tüm kaynaklar hemen temizlenecektir. Grace süresi Inf olarak ayarlanırsa, kaynaklar Downloader çöp toplayıcı tarafından temizlenene kadar temizlenmez.