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 下载。