import-url

跟踪位于外部位置（如 s3://、/local/path 等）的文件或目录，并将其下载到本地项目中，或在远程存储中创建副本。

请参阅 dvc import，用于从其他DVC 仓库（例如托管在 GitHub 上的仓库）下载并跟踪数据/模型文件或目录。

概要

usage: dvc import-url [-h] [-q | -v]
           [--to-remote] [-r <name>] [--no-exec | --no-download]
           [-j <number>] [-f] [--version-aware]
           [--fs-config <name>=<value>]
           url [out]

positional arguments:
  url                   (See supported URLs in the description.)
  out                   Destination path to put files in.

描述

在某些情况下，将来自外部位置的数据文件或目录添加到工作区（或dvc remote）会很方便，这样当外部数据源发生变化时，可以稍后更新。典型场景包括：

远程系统可能偶尔生成被其他项目使用的数据文件。
定期运行的批处理任务会更新一个需要导入的数据文件。
存储在云上的共享数据集，由 DVC 外部的系统进行管理和更新。

请注意，dvc get-url 对应的是此命令执行的第一步（仅下载文件或目录）。

dvc import-url 可帮助您创建此类外部数据依赖，而无需手动从支持的位置（如下所列）复制文件，这些操作通常需要为每种类型安装不同的工具。

如果您不希望将目标数据存储在本地系统中，仍可通过使用 --to-remote 选项，在将文件或目录直接传输到远程存储的同时创建导入的 .dvc 文件。更多细节请参见传输至远程存储示例。

url 参数指定要导入数据的外部位置。导入的数据会被缓存，并通过其原始文件名链接（或复制）到当前工作目录（例如 data.txt），或复制到通过 out 指定的位置。

请参阅 dvc list-url，了解如何浏览外部位置中的文件和目录以供下载。

将在相同位置创建一个导入 .dvc 文件（例如 data.txt.dvc），类似于下载数据后使用 dvc add 的效果。这使得之后可以在数据源更改时更新导入（参见 dvc update）。

您可以像正常操作一样对从外部位置导入的数据执行 dvc push 和 dvc pull 操作（与 dvc import 不同）。

.dvc 文件支持对外部位置数据的引用，请参见外部依赖项。在此类导入的 .dvc 文件中，deps 字段存储外部 URL，而 outs 字段包含工作区中的相应本地路径。它记录了足够的元数据，使 DVC 能高效判断本地副本是否已过期。

请注意，dvc repro 不会检查或更新导入的 .dvc 文件，应使用 dvc update 将导入从数据源更新至最新状态。

DVC 支持多种类型的外部位置（协议）：

类型	描述	`url` 格式示例
`s3`	Amazon S3	`s3://bucket/data`
`azure`	Microsoft Azure Blob 存储	`azure://container/data`
`gs`	Google Cloud Storage	`gs://bucket/data`
`ssh`	SSH 服务器	`ssh://user@example.com/path/to/data`
`hdfs`	HDFS 到文件*	`hdfs://user@example.com/path/to/data.csv`
`http`	HTTP 到带有 ETag* 的文件	`https://example.com/path/to/data.csv`
`webdav`	WebDav 到文件*	`webdavs://example.com/endpoint/path`
`webhdfs`	HDFS REST API*	`webhdfs://user@example.com/path/to/data.csv`
`本地`	本地路径	`/path/to/local/data`

如果你通过 pip 安装了 DVC，并计划使用云服务作为远程存储，你可能需要安装以下可选依赖项：[s3]、[azure]、[gs]、[oss]、[ssh]。或者，使用 [all] 来包含所有依赖。命令应如下所示：pip install "dvc[s3]"。（此示例会随 DVC 一起安装 boto3 库以支持 S3 存储。）

* 关于远程位置的说明：

HDFS、HTTP、WebDav 和 WebHDFS 不支持下载整个目录，仅支持单个文件。
对于 HTTP，必须有 ETag 才能跟踪指定 URL 是否发生变化。

DVC 还支持从某些云存储提供商捕获云版本控制信息。当提供 --version-aware 选项，或 url 参数中包含受支持的云版本 ID 时，DVC 将导入指定版本。

使用版本化存储时，DVC 始终会从源拉取版本化数据，而不会向远程存储推送额外的版本。

类型	描述	版本化 `url` 格式示例
`s3`	Amazon S3	`s3://bucket/data?versionId=L4kqtJlcpXroDTDmpUMLUo`
`azure`	Microsoft Azure Blob 存储	`azure://container/data?versionid=YYYY-MM-DDThh:mm:ss`
`gs`	Google Cloud Storage	`gs://bucket/data#1360887697105000`

另一种理解 dvc import-url 命令的方式是：它相当于生成一个具有外部依赖的管道阶段的快捷方式。

这在外部依赖文档中有进一步讨论，其中为每种方案都展示了替代方法。

而不是：

$ dvc import-url https://data.dvc.org/get-started/data.xml data.xml

可以使用 dvc stage add，例如（HTTP URL）：

$ dvc stage add -n download_data \
                -d https://data.dvc.org/get-started/data.xml \
                -o data.xml \
                wget https://data.dvc.org/get-started/data.xml -O data.xml

$ dvc repro

dvc import-url 会生成一个导入.dvc文件，而 dvc stage add 会在 dvc.yaml 中创建一个普通阶段。

选项

--no-exec - 创建导入 .dvc 文件但不访问 url（假定数据源有效）。当你需要快速定义项目导入并在稍后导入数据时，此选项非常有用（可使用 dvc update 完成操作）。
--no-download - 创建导入.dvc文件，包含外部依赖的哈希值，但不下载相关数据。如果你需要跟踪远程数据的变化但暂时不想占用本地存储空间，这会很有用。之后可以使用 dvc pull 下载数据，但如果 url 不再与哈希值匹配，则会失败。可以使用 dvc update --no-download 更新文件哈希。
--to-remote - 导入目标文件，但既不将其移入工作区，也不缓存到本地。而是直接传输到远程存储（除非用 -r 指定其他远程存储，否则为默认远程）。使用 dvc pull 可将数据拉取到本地。
-r <name>, --remote <name> - 指定 dvc remote 的名称（只能与 --to-remote 一起使用）。
-j <number>, --jobs <number> - DVC 从源下载数据时的并行级别。默认值为 4 * cpu_count()。使用更多任务可能加快操作速度。
-f, --force - 当使用 --out 指定本地目标文件或目录时，如果这些路径已存在，操作将失败。使用此标志会强制执行操作，导致命令覆盖现有的本地文件/目录。
--fs-config <name>=<value> - 针对目标 URL 的 dvc remote 配置选项。
--version-aware - 在导入文件时捕获当前版本的云版本控制信息。DVC 始终会从源拉取版本化数据，而不会推送额外副本到远程存储。
-h, --help - 打印使用说明/帮助信息，然后退出。
-q, --quiet - 不向标准输出写入任何内容。如果没有问题则以 0 退出，否则以 1 退出。
-v, --verbose - 显示详细的跟踪信息。

示例

为了说明这些示例，我们将使用入门指南中介绍的项目。

点击并展开以设置示例

如果还没有该项目，请先克隆我们的示例仓库。然后进入该仓库并检出 Get Started 中的 3-config-remote 标签对应的部分。

$ git clone https://github.com/iterative/example-get-started
$ cd example-get-started
$ git checkout 3-config-remote

示例：从网络跟踪文件

在 快速入门 的“版本控制基础”部分开头，一个更高级的替代方法是使用 dvc import-url：

$ dvc import-url https://data.dvc.org/get-started/data.xml \
                 data/data.xml
Importing 'https://data.dvc.org/get-started/data.xml' -> 'data/data.xml'
...
To track the changes with git, run:

	git add data.xml.dvc data/.gitignore

让我们看看 data.xml.dvc 文件的变化：

+md5: c4d6740ee09950bb532d418b8ae0b52e
+frozen: true
+deps:
+- etag: '"f432e270cd634c51296ecd2bc2f5e752-5"'
+  path: https://data.dvc.org/get-started/data.xml
 outs:
 - md5: a304afb96060aad90176268345e10355
   path: data.xml
   cache: true

.dvc 文件中的 etag 字段包含从 HTTP 请求中记录的 ETag。如果导入的文件在线上发生更改，其 ETag 也会不同。该元数据使 DVC 能够判断是否需要重新下载该文件。

有关上述格式的更多细节，请参阅 .dvc 文件说明。

尝试此示例后（尤其是如果你打算继续尝试下一个示例），你可能希望退出并删除 example-get-started/ 目录。

示例：检测外部文件变更

如果一个已导入的文件在其源位置定期更新怎么办？项目目标可能包括基于更新后的数据源重新生成某些结果。管道的重新执行可以由外部依赖项的变更触发。

让我们再次使用快速入门项目，模拟一个外部数据源的更新。（请记住按照示例中的说明准备工作区）

为了说明这种情况，我们使用一个位于工作区之外的本地文件系统目录（在实际场景中，数据文件可能位于远程服务器上）。运行以下命令：

$ mkdir /tmp/dvc-import-url-example
$ cd /tmp/dvc-import-url-example/
$ wget https://data.dvc.org/get-started/data.xml
$ cd - # go back to the project

在生产系统中，你可能会有一个流程来更新数据文件。但我们这里没有，因此在此我们将设置一个“数据存储”目录，以便我们可以编辑其中的数据文件。

$ dvc import-url /tmp/dvc-import-url-example/data.xml data/data.xml
Importing '../../../tmp/dvc-import-url-example/data.xml' -> 'data/data.xml'

检查 data.xml.dvc：

md5: fceb2bc076fabe99b483729c3ea2a897
frozen: true
deps:
  - md5: a304afb96060aad90176268345e10355
    path: /tmp/dvc-import-url-example/data.xml
outs:
  - md5: a304afb96060aad90176268345e10355
    path: data.xml

.dvc 文件几乎与前一个示例相同。区别在于依赖项（deps）现在引用了我们之前创建的数据存储目录中的本地文件。（其 path 包含指向数据存储的 URL。）并且我们不再使用 etag，而是使用了一个 md5 哈希值。这样做是为了方便我们编辑数据文件。

现在让我们手动重现 快速入门 中的数据处理部分。下载示例源代码压缩包并解压：

$ wget https://code.dvc.org/get-started/code.zip
$ unzip code.zip
$ rm -f code.zip

点击并展开以设置环境

让我们安装所需的依赖项。但在执行之前，我们强烈建议创建一个虚拟环境：

$ python3 -m venv .env
$ source .env/bin/activate
$ pip install -r src/requirements.txt

$ dvc stage add -n prepare \
                -d src/prepare.py -d data/data.xml \
                -o data/prepared \
                python src/prepare.py data/data.xml

$ dvc repro
Running command:
	python src/prepare.py data/data.xml
...

$ tree
.
├── README.md
├── data
│   ├── data.xml
│   ├── data.xml.dvc
│   └── prepared
│       ├── test.tsv
│       └── train.tsv
├── dvc.lock
├── dvc.yaml
├── params.yaml
└── src
    ├── evaluate.py
    ├── featurization.py
    ├── prepare.py
    ├── requirements.txt
    └── train.py

此时，DVC 认为所有内容都是最新的：

$ dvc status
Data and pipelines are up to date.

在数据存储目录中编辑 data.xml。你可以修改任意内容，只要它仍然是有效的 XML 文件即可，因为任何更改都会导致导入的 .dvc 文件中依赖文件的哈希值（md5）发生变化。完成修改后，我们可以运行 dvc update 来确保导入内容是最新的：

$ dvc update data.xml.dvc
Importing '.../tmp/dvc-import-url-example/data.xml' -> 'data/data.xml'

DVC 检测到外部数据源已更改，并更新了 .dvc 文件（即重新生成）。在这种情况下，还需要运行 dvc repro，以确保管道的其余结果也被重新生成：

$ dvc repro
Running stage 'prepare' with command:
	python src/prepare.py data/data.xml

示例：传输到远程存储

有时本地环境没有足够的空间来导入大型数据集，但你仍希望在项目中对其进行跟踪，以便日后可以将其拉取下来。

只要设置了能够处理数据的 dvc remote，就可以通过使用 --to-remote 标志来实现。它会创建一个导入的 .dvc 文件而不下载任何内容，而是将目标直接传输到远程存储。

让我们通过 HTTP 直接将一个 data.xml 文件“导入到远程”：

$ dvc import-url https://data.dvc.org/get-started/data.xml data.xml \
                 --to-remote
...
$ ls
data.xml.dvc

由于在工作区中创建了一个 .dvc 文件，因此每当有人需要实际下载数据时，他们都可以使用 dvc pull：

$ dvc pull data.xml.dvc
A       data.xml
1 file added

使用 dvc update --to-remote 在远程存储中更新导入的内容，而无需下载任何内容。

示例：跟踪云存储版本 ID

如果您的云存储路径已启用版本控制，DVC 可以使用云版本 ID 来管理数据。让我们从 S3 导入带有版本控制的数据：

$ dvc import-url --version-aware s3://mybucket/data
Importing 's3://mybucket/data' -> 'data'

检查 data.dvc 文件，注意它记录了每个文件的 version_id：

md5: 0c00504e8539cba57c523413d6f98df3
frozen: true
deps:
- path: s3://mybucket/data
  files:
  - size: 14445097
    version_id: LiVFgBb24qRRbn1o2DcAZhh4_M8Zy7FK
    etag: 22a1a2931c8370d3aeedd7183606fd7f
    relpath: data.xml
  ...
  - size: 6728772
    version_id: fLkcP.Dq0zl7CtKexohzyJCazSMk_R9C
    etag: 9ca281786366acca17632c27c5c5cc75
    relpath: prepared/train.tsv
outs:
- md5: 3ce9c43d5bead55bee0d3752fc1d68c5.dir
  size: 25115048
  nfiles: 5
  path: data
  push: false

DVC 知道您的云存储已经对这些文件进行了版本控制，因此不会将它们推送到 DVC 远程存储。

$ dvc push
Everything is up to date.

在执行 dvc pull 时，这些文件将从其原始源位置拉取，而不是从 DVC 远程存储拉取。