R download.file 從互聯網下載文件

說明

此函數可用於從 Internet 下載文件。

用法

download.file(url, destfile, method, quiet = FALSE, mode = "w",
              cacheOK = TRUE,
              extra = getOption("download.file.extra"),
              headers = NULL, ...)

參數

url	character 字符串(或 "libcurl" 方法的更長向量)，命名要下載的資源的 URL。
destfile	一個字符串(或向量，請參閱url 參數)，其中包含要保存下載的文件的文件路徑。執行Tilde-expansion。
method	用於下載文件的方法。目前的下載方法是 "internal" 、 "libcurl" 、 "wget" 、 "curl" 和 "wininet" (僅限 Windows)，並且有一個值 "auto" ：請參閱“詳細信息”和“注意”。 該方法也可以通過選項"download.file.method"設置：參見options()。
quiet	如果是 TRUE ，則抑製狀態消息(如果有)和進度條。
mode	特點。寫入文件的模式。有用的值是 "w" 、 "wb" (二進製)、 "a" (追加)和 "ab" 。不用於方法 "wget" 和 "curl" 。另請參閱“詳細信息”，特別是有關在 Windows 上使用 "wb" 的信息。
cacheOK	合乎邏輯的。服務器端緩存值是否可以接受？
extra	"wget" 和 "curl" 方法的附加命令行參數的字符向量。
headers	在 HTTP[S] 請求中使用的附加 HTTP 標頭的命名字符向量。對於非 HTTP[S] URL，它會被忽略。從 HTTPUserAgent 選項獲取的 User-Agent 標頭(請參閱 options )自動用作第一個標頭。
...	允許傳遞額外的參數，但未使用。

細節

函數 download.file 可用於從互聯網下載 url 說明的單個文件並將其存儲在 destfile 中。

url必須從諸如“⁠http://⁠', '⁠https://⁠' 或者 '⁠文件://⁠’。哪些方法支持哪些方案因情況而異R版本，但是method = "auto"將嘗試找到支持該方案的方法。

為了method = "auto"(默認)當前"internal"方法用於‘⁠文件://⁠’ 網址和"libcurl"對於所有其他人。

支持方法"libcurl"之前的 Windows 上是可選的R4.2.0：使用capabilities("libcurl")查看早期版本是否支持它。它使用該名稱的外部庫(https://curl.se/libcurl/)針對哪個R可以編譯。

當使用 "libcurl" 方法時，支持同時下載，因此 url 和 destfile 可以是相同長度大於 1 的字符向量(但必須顯式指定該方法，而不是通過 "auto" ) 。對於單個 URL 和 quiet = FALSE，交互式使用時會顯示進度條。

如今的"internal"方法僅支持‘⁠文件://⁠' 方案(這是默認方案)。在 Windows 上"wininet"方法目前支持‘⁠文件://⁠' 和(但已棄用並帶有警告)'⁠http://⁠' 和 '⁠https://⁠’的計劃。

對於方法"wget"和"curl"對以下給出的工具進行係統調用method，並且相應的程序必須安裝在您的係統上並且位於可執行文件的搜索路徑中。他們將阻止網站上的所有其他活動R進程直到完成：這可能會使 GUI 無響應。

cacheOK = FALSE對於‘⁠http://⁠' 和 '⁠https://⁠’ URL：它將嘗試直接從站點而不是從中間緩存獲取副本。它由以下人員使用available.packages.

"libcurl"和"wget"方法如下‘⁠http://⁠' 和 '⁠https://⁠’重定向到他們支持的任何方案。 (對於方法"curl"使用參數extra = "-L"。禁用重定向wget， 采用extra = "--max-redirect=0"。) 這"wininet"方法支持一些重定向，但不是全部。 (對於方法"libcurl"，消息將引用重定向的端點。)

參看url如何 '⁠文件://⁠’ URL 會被解釋，尤其是在 Windows 上。這"internal"和"wininet"方法不是percent-decode，而是"libcurl"和"curl"方法做：方法"wget"不支持他們。

大多數方法不使用 percent-encode 特殊字符，例如 URL 中的空格(請參閱 URLencode )，但 "wininet" 方法似乎可以。

其餘詳細信息僅適用於 "wininet" 和 "libcurl" 方法。

傳輸的許多部分的超時可以通過選項設置timeout默認為 60 秒。這通常不足以下載大文件(50MB 或更多)，因此應在以下情況下增加：download.file在包中使用來執行此操作。注意，用戶可以通過環境變量設置默認超時時間R_DEFAULT_INTERNET_TIMEOUT在最近的版本中R，所以為了確保這不會減少，包應該使用類似的東西

    options(timeout = max(300, getOption("timeout")))
  

(要求下載時間低於1s/MB是不現實的。)

傳輸期間提供的詳細信息級別可以通過 quiet 參數和 internet.info 選項設置：詳細信息取決於平台和方案。對於 "libcurl" 方法，選項值小於 2 會給出詳細輸出。

進度條跟蹤傳輸platform-specifically：

在 Windows 上

如果文件長度已知，則條形的全寬就是已知長度。否則，初始寬度表示 100 KB，並且每當超過當前寬度時就會加倍。 (在非交互式使用中，這使用文本版本。如果文件長度已知，等號代表已完成傳輸的 2%：否則點代表 10Kb。)

在類 Unix 係統上

如果文件長度已知，等號代表已完成傳輸的 2%：否則點代表 10Kb。

二進製傳輸的選擇(mode = "wb"或者"ab") 在 Windows 上很重要，因為與 Unix 類似的係統不同，它確實區分文本和二進製文件，並且對於文本傳輸更改‘⁠\n⁠' 行結尾為 '⁠\r\n⁠”(又名“CRLF’)。

在 Windows 上，如果mode未提供(missing()) 和url以‘之一結尾⁠.gz⁠', '⁠.bz2⁠', '⁠.xz⁠', '⁠.tgz⁠', '⁠.zip⁠', '⁠.jar⁠', '⁠.rda⁠', '⁠.rds⁠', '⁠.RData⁠' 或者 '⁠.pdf⁠’,mode = "wb"設置為進行二進製傳輸以幫助粗心的用戶。

為下載二進製文件而編寫的代碼必須使用 mode = "wb" (或 "ab" )，但文本傳輸引起的問題隻會在 Windows 上出現。

值

一個(不可見的)整數代碼，0 表示成功，非零表示失敗。對於"wget" 和"curl" 方法，這是外部程序返回的狀態代碼。 "internal" 方法可以返回 1 ，但在大多數情況下會拋出錯誤。

發生錯誤時目標文件會發生什麽情況取決於方法和R版本。目前"internal","wininet"和"libcurl"如果 URL 不可用，方法將刪除該文件，除非mode指定文件應保持不變時進行追加。

設置代理

對於Windows-only方法"wininet"，係統的“Internet選項”用於選擇代理等；這些是在控製麵板中設置的，並且是用於係統瀏覽器的。

為了"libcurl"和"curl"方法，可以設置代理通過環境變量http_proxy或者ftp_proxy.看https://curl.se/libcurl/c/libcurl-tutorial.html了解更多詳情。

安全 URL

訪問‘的方法⁠https://⁠' 和(如果支持)'⁠ftps://⁠’ URL 應嘗試驗證站點證書。這通常是使用操作係統安裝的 CA 根證書來完成的(盡管我們已經看到這些證書被刪除而不是更新的實例)。欲了解更多信息，請參閱https://curl.se/docs/sslcerts.html.

在 Windows 上method = "libcurl"，CA根證書由操作係統提供R與libcurl和Schannel啟用，這是 Rtools 中當前的默認設置。這可以通過檢查來驗證libcurlVersion()返回包含‘的版本字符串⁠"Schannel"⁠’。如果沒有，請在環境變量上進行驗證CURL_CA_BUNDLE必須設置為證書捆綁文件的路徑，通常名為“ca-bundle.crt' 或者 'curl-ca-bundle.crt’。 (對於二進製安裝，這通常是自動完成的R，它安裝‘R_HOME/etc/curl-ca-bundle.crt’並設置CURL_CA_BUNDLE如果尚未設置該環境變量，則指向它。)有關更新的證書包，請參閱https://curl.se/docs/sslcerts.html。目前可以從以下位置下載一份副本https://raw.githubusercontent.com/bagder/ca-bundle/master/ca-bundle.crt並設置CURL_CA_BUNDLE到下載文件的完整路徑。

在 Windows 上method = "libcurl"， 什麽時候R與libcurl和Schannel啟用後，如果無法確定證書未被吊銷，則連接失敗。某些 MITM 代理(特別是在企業環境中)不支持這種行為。可以通過設置環境變量來改變R_LIBCURL_SSL_REVOKE_BEST_EFFORT到TRUE，從而降低安全性。

請注意，使用的根證書R可能與瀏覽器中使用的相同，也可能不同，並且實際上不同的瀏覽器可能使用不同的證書捆綁包(通常有一個構建選項可以選擇它們自己的證書捆綁包或係統的證書捆綁包)。

好的做法

設置 method 應留給最終用戶。 wget 和 curl 命令都不是廣泛可用的：您可以通過 Sys.which 檢查命令是否可用，並且應該在包或腳本中執行此操作。

如果你使用download.file在包或腳本中，您必須檢查返回值，因為下載可能會失敗並顯示非零狀態，但不是R錯誤。

支持的method改變：方法libcurl被介紹於R3.2.0 並且在 Windows 上是可選的，直到R4.2.0-使用capabilities("libcurl")在程序中查看它是否可用。

'⁠ftp://⁠’ 網址

大多數現代瀏覽器不支持此類 URL，並且‘⁠https://⁠' 更適合用於R。 '⁠ftps://⁠’ URL 一直很少見，現在支持更少。

其目的是R將繼續允許此類 URLlibcurl確實如此，但隨著它們變得越來越少，這種情況也越來越未經測試。 ‘protocols’是什麽版本libcurl正在使用的支持可以通過調用查看libcurlVersion().

這些 URL 可使用 FTP 協議進行訪問，該協議有多種變體。 ‘active’ 和“(擴展)被動”模式之間的一個區別是：使用哪種模式由客戶端選擇。 "libcurl" 方法使用被動模式，在完全放棄支持之前，該模式幾乎被瀏覽器普遍使用。

注意

64 位版本支持超過 2GB 的文件R;它們可能在某些 32 位版本上被截斷。

方法"wget" 和"curl" 主要用於曆史兼容性，但也可能提供"libcurl" 或"wininet" 方法不支持的函數。

如果 wget 的配置文件中存儲了正確的值，則方法 "wget" 可以與需要用戶/密碼身份驗證的代理防火牆一起使用。

wget ( https://www.gnu.org/software/wget/ ) 通常安裝在 Unix 類係統上(但不是 macOS)。 Windows 二進製文件可從 MSYS2 和其他地方獲得。

curl ( https://curl.se/ ) 安裝在 macOS 上，並且越來越普遍地安裝在 Unix 類似係統上。 Windows 二進製文件可從該 URL 獲取。

也可以看看

options 設置某些方法使用的 HTTPUserAgent 、 timeout 和 internet.info 選項。

url 用於從 URL 讀取數據的更細粒度的方法。

url.show 、 available.packages 、 download.packages 適用於應用程序。

貢獻的軟件包 RCurl 和 curl 提供了更全麵的工具來從 URL 下載。