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 أمرًا، يتم تشغيل الأمر ويتم إرسال المخرجات إليه عبر stdin.

إذا تم توفير وسيط الكلمة الرئيسية downloader، يجب أن يكون كائن Downloader. سيتم مشاركة الموارد والاتصالات بين التنزيلات التي يتم تنفيذها بواسطة نفس Downloader وسيتم تنظيفها تلقائيًا عندما يتم جمع الكائن بواسطة جامع القمامة أو لم يتم تنفيذ أي تنزيلات به لفترة سماح. راجع Downloader لمزيد من المعلومات حول التكوين والاستخدام.

إذا تم توفير وسيط الكلمة الرئيسية headers، يجب أن يكون متجهًا أو قاموسًا تكون عناصره جميعها أزواج من السلاسل. يتم تمرير هذه الأزواج كعناوين عند تنزيل عناوين URL مع البروتوكولات التي تدعمها، مثل HTTP/S.

يحدد وسيط الكلمة الرئيسية timeout مهلة لإكمال التنزيل بالثواني، بدقة المللي ثانية. بشكل افتراضي، لا يتم تعيين مهلة، ولكن يمكن طلب ذلك أيضًا بشكل صريح عن طريق تمرير قيمة مهلة Inf. بشكل منفصل، إذا مرت 20 ثانية دون تلقي أي بيانات، ستنتهي المهلة. راجع المساعدة الموسعة حول كيفية تعطيل هذه المهلة.

إذا تم توفير وسيط الكلمة الرئيسية progress، يجب أن يكون دالة رد نداء سيتم استدعاؤها كلما كانت هناك تحديثات حول حجم وحالة التنزيل الجاري. يجب أن تأخذ دالة رد النداء وسيطين صحيحين: total و now، وهما الحجم الإجمالي للتنزيل بالبايت، وعدد البايتات التي تم تنزيلها حتى الآن. لاحظ أن total يبدأ كصفر ويظل صفرًا حتى يعطي الخادم إشارة عن الحجم الإجمالي للتنزيل (على سبيل المثال، مع رأس Content-Length)، والذي قد لا يحدث أبدًا. لذا يجب أن تتعامل دالة رد النداء الخاصة بالتقدم بشكل جيد مع حجم إجمالي يساوي صفر.

إذا تم تعيين خيار verbose إلى true، ستقوم libcurl، التي تُستخدم لتنفيذ وظيفة التنزيل، بطباعة معلومات تصحيح الأخطاء إلى stderr. إذا تم تعيين خيار debug إلى دالة تقبل وسيطين من نوع String، يتم تجاهل خيار verbose وبدلاً من ذلك يتم تمرير البيانات التي كان من الممكن طباعتها إلى stderr إلى دالة رد النداء debug مع وسائط type و message. تشير وسيلة type إلى نوع الحدث الذي حدث، وهي واحدة من: TEXT، HEADER IN، HEADER OUT، DATA IN، DATA OUT، SSL DATA IN أو SSL DATA OUT. وسيلة message هي وصف حدث التصحيح.

مساعدة موسعة

للمزيد من التخصيص، استخدم 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)

source

Downloads.request — Function

اطلب(url;
    [ الإدخال = <none>, ]
    [ الإخراج = <none>, ]
    [ الطريقة = الإدخال ? "PUT" : الإخراج ? "GET" : "HEAD", ]
    [ الرؤوس = <none>, ]
    [ المهلة = <none>, ]
    [ التقدم = <none>, ]
    [ مفصل = false, ]
    [ تصحيح = <none>, ]
    [ رمي = true, ]
    [ المتنزل = <default>, ]
    [ مقاطعة = <none>, ]
) -> Union{Response, RequestError}

    url        :: AbstractString
    الإدخال      :: Union{AbstractString, AbstractCmd, IO}
    الإخراج     :: Union{AbstractString, AbstractCmd, IO}
    الطريقة     :: AbstractString
    الرؤوس    :: Union{AbstractVector, AbstractDict}
    المهلة    :: Real
    التقدم   :: (dl_total, dl_now, ul_total, ul_now) --> Any
    مفصل    :: Bool
    تصحيح      :: (type, message) --> Any
    رمي      :: Bool
    المتنزل :: Downloader
    مقاطعة  :: Base.Event

قم بعمل طلب إلى عنوان URL المعطى، مع إرجاع كائن Response يلتقط الحالة، الرؤوس ومعلومات أخرى حول الاستجابة. يتم كتابة جسم الاستجابة إلى الإخراج إذا تم تحديده ويتم تجاهله بخلاف ذلك. بالنسبة لطلبات HTTP/S، إذا تم إعطاء دفق الإدخال، يتم إجراء طلب PUT؛ خلاف ذلك، إذا تم إعطاء دفق الإخراج، يتم إجراء طلب GET؛ إذا لم يتم إعطاء أي منهما، يتم إجراء طلب HEAD. بالنسبة للبروتوكولات الأخرى، يتم استخدام طرق افتراضية مناسبة بناءً على ما تم طلبه من مزيج الإدخال والإخراج. الخيارات التالية تختلف عن وظيفة download:

الإدخال يسمح بتوفير جسم الطلب؛ إذا تم توفيره، يتم الافتراض إلى طلب PUT
التقدم هو رد نداء يأخذ أربعة أعداد صحيحة لتقدم التحميل والتنزيل
رمي يتحكم فيما إذا كان سيتم رمي خطأ أو إرجاع RequestError عند حدوث خطأ في الطلب

لاحظ أنه على عكس download الذي يرمي خطأ إذا لم يكن من الممكن تنزيل عنوان URL المطلوب (المشار إليه برمز حالة غير 2xx)، فإن request ترجع كائن Response بغض النظر عن رمز حالة الاستجابة. إذا كان هناك خطأ في الحصول على استجابة على الإطلاق، فسيتم رمي أو إرجاع RequestError.

إذا تم توفير وسيط الكلمة الرئيسية مقاطعة، يجب أن يكون كائن Base.Event. إذا تم تفعيل الحدث أثناء تقدم الطلب، فسيتم إلغاء الطلب وسيتم رمي خطأ. يمكن استخدام ذلك لإيقاف طلب طويل الأمد، على سبيل المثال إذا أراد المستخدم إلغاء تنزيل.

source

Downloads.Response — Type

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

Response هو نوع يلتقط خصائص الاستجابة الناجحة لطلب ككائن. يحتوي على الحقول التالية:

proto: البروتوكول الذي تم استخدامه للحصول على الاستجابة
url: عنوان URL الذي تم طلبه في النهاية بعد اتباع عمليات إعادة التوجيه
status: رمز الحالة للاستجابة، مما يدل على النجاح أو الفشل، إلخ.
message: رسالة نصية تصف طبيعة الاستجابة
headers: أي رؤوس تم إرجاعها مع الاستجابة

تعتمد معاني وتوافر بعض هذه الاستجابات على البروتوكول المستخدم في الطلب. بالنسبة للعديد من البروتوكولات، بما في ذلك HTTP/S و S/FTP، يشير رمز الحالة 2xx إلى استجابة ناجحة. بالنسبة للاستجابات في البروتوكولات التي لا تدعم الرؤوس، ستكون متجه الرؤوس فارغًا. لا يتضمن HTTP/2 رسالة حالة، فقط رمز حالة، لذا ستكون الرسالة فارغة.

source

Downloads.RequestError — Type

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

RequestError هو نوع يلتقط خصائص استجابة فاشلة لطلب ككائن استثناء:

url: عنوان URL الأصلي الذي تم طلبه دون أي إعادة توجيه
code: رمز خطأ libcurl؛ 0 إذا حدث خطأ فقط على مستوى البروتوكول
message: رسالة خطأ libcurl تشير إلى ما حدث خطأ
response: كائن الاستجابة الذي يلتقط معلومات الاستجابة المتاحة

نفس نوع RequestError يتم طرحه بواسطة download إذا كان الطلب ناجحًا ولكن كان هناك خطأ على مستوى البروتوكول يشير إليه رمز حالة ليس في نطاق 2xx، وفي هذه الحالة سيكون code صفرًا وسيكون حقل message هو سلسلة فارغة. واجهة برمجة التطبيقات request لا ترمي RequestError إلا إذا كان رمز خطأ libcurl code غير صفري، وفي هذه الحالة من المحتمل أن يحتوي كائن response المضمن على status صفر ورسالة فارغة. ومع ذلك، هناك حالات يتم فيها طرح خطأ على مستوى curl بسبب خطأ بروتوكول، وفي هذه الحالة قد تكون كل من الرموز والرسائل الداخلية والخارجية ذات أهمية.

source

Downloads.Downloader — Type

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

تُستخدم كائنات Downloader لأداء عمليات download فردية. يتم مشاركة الاتصالات، وعمليات البحث عن الأسماء، والموارد الأخرى داخل Downloader. يتم تنظيف هذه الاتصالات والموارد بعد فترة نعمة قابلة للتكوين (افتراضي: 30 ثانية) منذ آخر عملية تحميل تمت بها، أو عندما يتم جمعها بواسطة جامع القمامة، أيهما يأتي أولاً. إذا تم تعيين فترة النعمة إلى صفر، فسيتم تنظيف جميع الموارد على الفور بمجرد عدم وجود أي عمليات تحميل جارية. إذا تم تعيين فترة النعمة إلى Inf، فلن يتم تنظيف الموارد حتى يتم جمع Downloader بواسطة جامع القمامة.

source