GDAL虚拟文件系统（压缩、网络托管等）：/vsimem，/vsizip，/vsitar，/vsicurl。。。

介绍

GDAL可以访问位于“标准”文件系统上的文件，即类Unix系统上的/hierarchy或C:，D:，等等。。。Windows上的驱动器。但是大多数GDAL栅格和矢量驱动程序使用GDAL特定的抽象来访问文件。这使得访问不太标准的文件类型成为可能，例如内存文件、压缩文件（.zip、.gz、.tar、.tar.gz存档）、加密文件、存储在网络上的文件（公共访问或商业云存储服务的私有存储桶中）等。

每个特殊的文件系统都有一个前缀，命名文件的一般语法是/vsiPREFIX/。。。

例子：

gdalinfo /vsizip/my.zip/my.tif

链锁

可以链接多个文件系统处理程序。

# ogrinfo a shapefile in a zip file on the internet:

ogrinfo -ro -al -so /vsizip//vsicurl/https://raw.githubusercontent.com/OSGeo/gdal/master/autotest/ogr/data/shp/poly.zip

# ogrinfo a shapefile in a zip file on an ftp:

ogrinfo -ro -al -so /vsizip//vsicurl/ftp://user:password@example.com/foldername/file.zip/example.shp

（注意也可以说/vsizip/vsicurl/。）。。。用一个斜杠。（但在编写文档时，请仍然使用两个。）

支持虚拟文件系统的驱动程序

虚拟文件系统只能与GDAL或OGR驱动程序一起使用，这些驱动程序支持“大文件API”，它现在是绝大多数基于文件的驱动程序。这些格式的完整列表可以在运行 gdalinfo --formats 或 ogrinfo --formats .

值得注意的例外是netCDF、HDF4和HDF5驱动程序。

/vsizip/（.zip档案）

/vsizip/是一个文件处理程序，它允许在不预先解压缩的情况下动态读取ZIP文件。

要指向zip文件中的文件，文件名必须为 /vsizip/path/to/the/file.zip/path/inside/the/zip/file 在哪里 path/to/the/file.zip 是相对的或绝对的 path/inside/the/zip/file 是存档中文件的相对路径。

要使用.zip作为目录，可以使用 /vsizip/path/to/the/file.zip 或 /vsizip/path/to/the/file.zip/subdir . 目录列表可用于 VSIReadDir() . 一 VSIStatL() （“/vsizip/…”）调用将返回文件的未压缩大小。对于常规文件系统，可以使用VSI ISDIR（stat.st_mode）宏将ZIP文件中的目录与常规文件区分开来。获取目录列表和文件统计信息是快速操作。

注意：在.zip文件包含位于其根目录下的单个文件的特定情况下，仅提及 /vsizip/path/to/the/file.zip 会工作。

实例：

/vsizip/my.zip/my.tif  (relative path to the .zip)
/vsizip//home/even/my.zip/subdir/my.tif  (absolute path to the .zip)
/vsizip/c:\users\even\my.zip\subdir\my.tif

.kmz、.ods和.xlsx扩展名也被检测为zip兼容存档的有效扩展名。

从GDAL 2.2开始，提供了一种替代语法，以便启用链接，而不依赖于.zip扩展名，例如： /vsizip/{{/path/to/the/archive}}/path/inside/the/zip/file . 注意 /path/to/the/archive 也可以使用这种替代语法。

还提供写功能。它们允许创建一个新的zip文件，并将新文件添加到已经存在（或刚刚创建）的zip文件中。

创建新的zip文件：

fmain = VSIFOpenL("/vsizip/my.zip", "wb");
subfile = VSIFOpenL("/vsizip/my.zip/subfile", "wb");
VSIFWriteL("Hello World", 1, strlen("Hello world"), subfile);
VSIFCloseL(subfile);
VSIFCloseL(fmain);

向现有zip添加新文件：

newfile = VSIFOpenL("/vsizip/my.zip/newfile", "wb");
VSIFWriteL("Hello World", 1, strlen("Hello world"), newfile);
VSIFCloseL(newfile);

从GDAL 2.4开始 GDAL_NUM_THREADS 配置选项可以设置为整数或 ALL_CPUS 启用单个文件的多线程压缩。这类似于独立模式下的pigz实用程序。默认情况下，输入流被分成1 MB的块（块大小可以使用 CPL_VSIL_DEFLATE_CHUNK_SIZE 配置选项，具有“x K”或“x M”等值，每个块独立压缩（并由九字节标记0x00 0x00 0xFF 0xFF 0x00 0x00 0x00 0xFF 0xFF终止，表示流和字典的完全刷新，允许对每个块进行潜在的独立解码）。这会稍微降低压缩率，因此应该避免非常小的块大小。

读写操作不能交叉进行。在以读取模式重新打开之前，必须先关闭新的zip。

/vsigzip/（gzip文件）

/vsigzip/是一个文件处理程序，它允许实时读取GZip（.gz）文件，而无需提前解压缩它们。

若要将gzip文件视为未经GDAL压缩的文件，必须使用 /vsigzip/path/to/the/file.gz 语法，在哪里 path/to/the/file.gz 是相对的或绝对的。

实例：

/vsigzip/my.gz # (relative path to the .gz)
/vsigzip//home/even/my.gz # (absolute path to the .gz)
/vsigzip/c:\users\even\my.gz

VSIStatL() 将返回未压缩的文件大小，但对大型文件执行此操作可能会很慢，因为它需要解压缩整个文件。在文件的末尾或在随机位置进行搜索，同样也很慢。为了加快这个过程，“快照”是在内存中内部创建的，以便能够以更快的方式查找已经解压缩的部分文件。这种快照机制也适用于/vsizip/文件。

当文件位于可写位置时，将创建扩展名为.gz.properties的文件，并指示未压缩的文件大小（可以通过设置 CPL_VSIL_GZIP_WRITE_PROPERTIES 配置选项到 NO ）

写功能也可用，但读写操作不能交错。

从GDAL 2.4开始 GDAL_NUM_THREADS 配置选项可以设置为整数或 ALL_CPUS 启用单个文件的多线程压缩。这类似于独立模式下的pigz实用程序。默认情况下，输入流被分成1 MB的块（块大小可以使用 CPL_VSIL_DEFLATE_CHUNK_SIZE 配置选项，具有“x K”或“x M”等值，每个块独立压缩（并由九字节标记0x00 0x00 0xFF 0xFF 0x00 0x00 0x00 0xFF 0xFF终止，表示流和字典的完全刷新，允许对每个块进行潜在的独立解码）。这会稍微降低压缩率，因此应该避免非常小的块大小。

/vsitar/（.tar、.tgz存档）

/vsitar/是一个文件处理程序，它允许动态读取常规的未压缩的.tar或压缩的.tgz或.tar.gz存档，而不必预先解压缩它们。

若要指向.tar、.tgz.tar.gz文件中的文件，文件名的格式必须为 /vsitar/path/to/the/file.tar/path/inside/the/tar/file 在哪里 path/to/the/file.tar 是相对的或绝对的 path/inside/the/tar/file 是存档中文件的相对路径。

要使用.tar作为目录，可以使用 /vsizip/path/to/the/file.tar 或 /vsitar/path/to/the/file.tar/subdir . 目录列表可用于 VSIReadDir() . 一 VSIStatL() （“/vsitar/…”）调用将返回文件的未压缩大小。使用VSI ISDIR（stat.st_mode）宏可以将TAR文件中的目录与常规文件系统中的常规文件区分开来。获取目录列表和文件统计信息是快速操作。

注意：在.tar文件包含位于其根目录下的单个文件的特定情况下，仅提及 /vsitar/path/to/the/file.tar 会工作。

实例：

/vsitar/my.tar/my.tif # (relative path to the .tar)
/vsitar//home/even/my.tar/subdir/my.tif # (absolute path to the .tar)
/vsitar/c:\users\even\my.tar\subdir\my.tif

从GDAL 2.2开始，提供了一种替代语法，以便启用链接，而不依赖于.tar扩展，例如： /vsitar/{/path/to/the/archive}/path/inside/the/tar/file . 注意 /path/to/the/archive 也可以使用这种替代语法。

基于网络的文件系统

A generic /vsicurl/ file system handler exists for online resources that do not require particular signed authentication schemes. It is specialized into sub-filesystems for commercial cloud storage services, such as /vsis3/, /vsigs/, /vsiaz/, /vsioss/ or /vsiswift/.

When reading of entire files in a streaming way is possible, prefer using the /vsicurl_streaming/, and its variants for the above cloud storage services, for more efficiency.

How to set credentials ?

Cloud storage services require setting credentials. For some of them, they can be provided through configuration files (~/.aws/config, ~/.boto, ..) or through environment variables / configuration options.

Starting with GDAL 3.5, VSISetCredential() can be used to set configuration options with a granularity at the level of a file path, which makes it easier if using the same virtual file system but with different credentials (e.g. different credentials for bucket "/vsis3/foo" and "/vsis3/bar")

Starting with GDAL 3.5, credentials can be specified in a GDAL configuration file, either in a specific one explicitly loaded with CPLLoadConfigOptionsFromFile(), or one of the default automatically loaded by CPLLoadConfigOptionsFromPredefinedFiles().

They should be put under a [credentials] section, and for each path prefix, under a relative subsection whose name starts with [. (e.g. [.some_arbitrary_name]), and whose first key is path. ` .. code-block:

[credentials]

[.private_bucket]
path=/vsis3/my_private_bucket
AWS_SECRET_ACCESS_KEY=...
AWS_ACCESS_KEY_ID=...

[.sentinel_s2_l1c]
path=/vsis3/sentinel-s2-l1c
AWS_REQUEST_PAYER=requester

/vsicurl/（http/https/ftp文件：随机访问）

/vsicurl/是一个文件系统处理程序，它允许通过HTTP/FTP web协议随时随机读取可用的文件，而无需事先下载整个文件。它需要针对libcurl构建GDAL。

可识别的文件名的格式为 /vsicurl/http[s]://path/to/remote/resource 或 /vsicurl/ftp://path/to/remote/resource 在哪里 path/to/remote/resource 是远程资源的URL。

实例使用 ogrinfo 要在internet上读取形状文件，请执行以下操作：

ogrinfo -ro -al -so /vsicurl/https://raw.githubusercontent.com/OSGeo/gdal/master/autotest/ogr/data/poly.shp

从GDAL 2.3开始，可以使用以下语法在文件名中传递选项： /vsicurl?[option_i=val_i&]*url=http://... 其中每个选项的名称和值（包括“url”的值）都是url编码的。当前支持的选项有：

• useu head=yes/no：是否可以发出HTTP head请求。默认为“是”。设置此选项将覆盖 CPL_VSIL_CURL_USE_HEAD 配置选项。

• maxu retry=number：默认为0。设置此选项将覆盖 GDAL_HTTP_MAX_RETRY 配置选项。

• retry_delay=number_in_seconds：默认为30。设置此选项将覆盖 GDAL_HTTP_RETRY_DELAY 配置选项。

• list_dir=yes/no：是否应尝试读取文件所在目录的文件列表。默认为“是”。

默认情况下，部分下载（要求HTTP服务器支持随机读取）以16kb的粒度完成。从GDAL 2.3开始，可以使用 CPL_VSIL_CURL_CHUNK_SIZE 配置选项，值以字节为单位。如果驱动程序检测到顺序读取，它将逐步增加块大小，最大可达2 MB，以提高下载性能。从GDAL 2.3开始 GDAL_INGESTED_BYTES_AT_OPEN 可以将配置选项设置为在文件打开时强制一个GET调用中读取的字节数（可以帮助性能读取具有大标题的云优化geotiff）。

这个 GDAL_HTTP_PROXY （对于HTTP和HTTPS协议）， GDAL_HTTPS_PROXY （仅适用于HTTPS协议）， GDAL_HTTP_PROXYUSERPWD 和 GDAL_PROXY_AUTH 配置选项可用于定义代理服务器。使用的语法是Curl CURLOPT_PROXY ， CURLOPT_PROXYUSERPWD 和 CURLOPT_PROXYAUTH 选项。

从GDAL 2.1.3开始 CURL_CA_BUNDLE 或 SSL_CERT_FILE 配置选项可用于设置证书颁发机构（CA）捆绑文件的路径（如果未指定，curl将使用系统位置中的文件）。

从GDAL 2.3开始，可以通过设置 GDAL_HTTP_HEADER_FILE 用于指向带有“key:value”HTTP头的文本文件的文件名的配置选项。 CPL_CURL_VERBOSE 设置为 YES 当与之结合时，允许一个人看到他们和更多 --debug .

从GDAL 2.3开始 GDAL_HTTP_MAX_RETRY （尝试次数）和 GDAL_HTTP_RETRY_DELAY （以秒为单位）可以设置配置选项，以便在发生HTTP错误429、502、503或504时完成请求重试。

更普遍的选择 CPLHTTPFetch() 通过配置选项可用。

可以通过设置配置选项将文件缓存到RAM中 VSI_CACHE 到 TRUE . 缓存大小默认为25 MB，但可以通过设置配置选项进行修改 VSI_CACHE_SIZE （字节）。关闭文件句柄时，将丢弃该缓存中的内容。

此外，默认情况下，将启用在所有下载内容之间共享的全局最近最少使用的16 MB缓存，其中的内容可以在关闭并重新打开文件句柄之后、在进程的生命周期内或直到 VSICurlClearCache() 被称为。从GDAL 2.3开始，可以通过设置配置选项来修改全局LRU缓存的大小 CPL_VSIL_CURL_CACHE_SIZE （以字节为单位）。

从GDAL 2.3开始 CPL_VSIL_CURL_NON_CACHED 配置选项可以设置为如下值 /vsicurl/http://example.com/foo.tif:/vsicurl/http://example.com/some_directory ，以便在关闭文件句柄时，不再缓存与所述文件相关的所有缓存内容。这有助于处理在执行GDAL相关代码期间可以修改的资源。或者， VSICurlClearCache() 可以使用。

从GDAL 2.1开始， /vsicurl/ 将尝试在有效期内查询直接重定向到Amazon S3签名URL的URL，以尽量减少往返次数。通过设置配置选项可以禁用此行为 CPL_VSIL_CURL_USE_S3_REDIRECT 到 NO .

VSIStatL() 将返回st_size member中的大小和st_mode member中的file-nature-file或directory-in文件性质（后者目前只对FTP资源可靠）。

VSIReadDir() 应该能够解析最流行的web服务器（如Apache和Microsoft IIS）返回的HTML目录列表。

/vsicurl_streaming/（http/https/ftp文件：流式传输）

/vsicurl_streaming/是一个文件系统处理程序，它允许实时顺序读取通过HTTP/FTP web协议传输的文件，而无需事先下载整个文件。它需要针对libcurl构建GDAL。

Although this file handler is able seek to random offsets in the file, this will not be efficient. If you need efficient random access and that the server supports range downloading, you should use the /vsicurl/ file system handler instead.

可识别的文件名的格式为 /vsicurl_streaming/http[s]://path/to/remote/resource 或 /vsicurl_streaming/ftp://path/to/remote/resource 在哪里 path/to/remote/resource 是远程资源的URL。

这个 GDAL_HTTP_PROXY （对于HTTP和HTTPS协议）， GDAL_HTTPS_PROXY （仅适用于HTTPS协议）， GDAL_HTTP_PROXYUSERPWD 和 GDAL_PROXY_AUTH 配置选项可用于定义代理服务器。使用的语法是Curl CURLOPT_PROXY ， CURLOPT_PROXYUSERPWD 和 CURLOPT_PROXYAUTH 选项。

从GDAL 2.1.3开始 CURL_CA_BUNDLE 或 SSL_CERT_FILE 配置选项可用于设置证书颁发机构（CA）捆绑文件的路径（如果未指定，curl将使用系统位置中的文件）。

可以通过设置配置选项将文件缓存到RAM中 VSI_CACHE 到 TRUE . 缓存大小默认为25 MB，但可以通过设置配置选项进行修改 VSI_CACHE_SIZE （以字节为单位）。

VSIStatL() 将返回st_size member中的大小和st_mode member中的file-nature-file或directory-in文件性质（后者目前只对FTP资源可靠）。

/vsis3/（AWS S3文件）

/vsis3/是一个文件系统处理程序，它允许随时随机读取AWS S3存储桶中可用的（主要是非公共的）文件，而无需事先下载整个文件。它需要针对libcurl构建GDAL。

它还允许顺序写入文件。不允许进行寻道或读取操作，因此特别不支持使用GTiff驱动程序直接写入GeoTIFF文件，除非从gdal3.2开始 CPL_VSIL_USE_TEMP_FILE_FOR_RANDOM_WRITE 配置选项设置为 YES ，在这种情况下，可以进行随机写访问（包括创建临时本地文件，其位置由 CPL_TMPDIR 配置选项）。删除带有 VSIUnlink() 也支持。从GDAL 2.3开始，用 VSIMkdir() 和删除（空）目录 VSIRmdir() 也有可能。

可识别的文件名的格式为 /vsis3/bucket/key 在哪里 bucket 是S3 bucket的名称，并且 key 是S3对象“key”，即可能包含子目录的文件名。

The generalities of /vsicurl/ apply.

可以使用多种身份验证方法，并按以下顺序进行尝试：

1. 如果 AWS_NO_SIGN_REQUEST=YES 已设置配置选项，已禁用请求签名。此选项可用于具有公共访问权限的存储桶。从GDAL 2.3开始提供

2. 这个 AWS_SECRET_ACCESS_KEY 和 AWS_ACCESS_KEY_ID 可以设置配置选项。这个 AWS_SESSION_TOKEN 使用临时凭据时必须设置配置选项。

3. Starting with GDAL 2.3, alternate ways of providing credentials similar to what the "aws" command line utility or Boto3 support can be used. If the above mentioned environment variables are not provided, the ~/.aws/credentials or %UserProfile%/.aws/credentials file will be read (or the file pointed by CPL_AWS_CREDENTIALS_FILE). The profile may be specified with the AWS_DEFAULT_PROFILE environment variable, or starting with GDAL 3.2 with the AWS_PROFILE environment variable (the default profile is "default").

4. The ~/.aws/config or %UserProfile%/.aws/config file may also be used (or the file pointer by AWS_CONFIG_FILE) to retrieve credentials and the AWS region.

5. 如果上述方法均未成功，则在EC2实例上使用GDAL时将检索实例配置文件凭据。

这个 AWS_REGION （或） AWS_DEFAULT_REGION 从GDAL 2.3）开始，配置选项可以设置为支持的S3区域之一，默认为 us-east-1 .

从GDAL 2.2开始 AWS_REQUEST_PAYER 配置选项可以设置为“请求者”，以便于与请求者付费存储桶一起使用。

这个 AWS_S3_ENDPOINT 配置选项默认为s3.amazonaws.com。

这个 AWS_HTTPS 配置选项默认为 YES .

这个 AWS_VIRTUAL_HOSTING 配置选项默认为 TRUE . 这允许您配置访问Bucket的两种方式，有关更多详细信息，请参阅Bucket和主机名。- TRUE 值，通过虚拟bucket主机名标识bucket，例如：mybucket.cname.domain.com- FALSE 值，将bucket标识为URI中的顶级目录，例如：cname.domain.com/mybucket

在编写时，使用S3多部分上载API上载文件。默认情况下，块的大小设置为50MB，允许创建高达500GB的文件（10000个部分，每个部分50MB）。如果需要更大的文件，则增加 VSIS3_CHUNK_SIZE 将配置选项设置为更大的值（以MB表示）。如果进程被终止且文件未正确关闭，则多部分上载将保持打开状态，从而导致Amazon向您收取部件存储费用。对于小于块大小的文件，您必须使用其他方法中止自己的“ghost”上载（例如使用s3cmd实用程序），使用简单的PUT请求而不是多部分上载API。

Since GDAL 2.4, when listing a directory, files with GLACIER storage class are ignored unless the CPL_VSIL_CURL_IGNORE_GLACIER_STORAGE configuration option is set to NO. This option has been superseded in GDAL 3.5 per the CPL_VSIL_CURL_IGNORE_STORAGE_CLASSES configuration option that accept a comma-separated list of storage class names and defaults to GLACIER,DEEP_ARCHIVE (if set to empty, objects of all storage classes are retrieved).

从gdal3.1开始 VSIRename() 支持操作（先复制原始文件，然后删除）

从gdal3.1开始 VSIRmdirRecursive() 支持操作（使用批删除方法）。这个 CPL_VSIS3_USE_BASE_RMDIR_RECURSIVE 如果使用不支持批删除（GDAL>=3.2）的类似S3的API，配置选项可以设置为YES

Starting with GDAL 3.5, profiles that use IAM role assumption (see https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html) are handled. The role_arn and source_profile keywords are required in such profiles. The optional external_id, mfa_serial and role_session_name can be specified. credential_source is not supported currently.

2.1 新版功能.

/vsis3_streaming/（AWS S3文件：streaming）

/vsis3_streaming/是一个文件系统处理程序，它允许对AWS S3存储桶中可用的（主要是非公共的）文件进行动态顺序读取，而无需事先下载整个文件。它需要针对libcurl构建GDAL。

可识别的文件名的格式为 /vsis3_streaming/bucket/key 在哪里？ bucket 是S3 bucket的名称，并且 key 是S3对象“key”，即可能包含子目录的文件名。

Authentication options, and read-only features, are identical to /vsis3/

2.1 新版功能.

/vsigs/（谷歌云存储文件）

/vsigs/是一个文件系统处理程序，它允许即时随机读取Google云存储桶中可用的（主要是非公共的）文件，而无需事先下载整个文件。它需要针对libcurl构建GDAL。

从gdal2.3开始，它还允许顺序写入文件。不允许进行寻道或读取操作，因此特别不支持使用GTiff驱动程序直接写入GeoTIFF文件，除非从gdal3.2开始 CPL_VSIL_USE_TEMP_FILE_FOR_RANDOM_WRITE 配置选项设置为 YES ，在这种情况下，可以进行随机写访问（包括创建临时本地文件，其位置由 CPL_TMPDIR 配置选项）。删除带有 VSIUnlink() ，创建目录 VSIMkdir() 和删除（空）目录 VSIRmdir() 也有可能。

可识别的文件名的格式为 /vsigs/bucket/key 在哪里？ bucket 是桶的名字和 key 是对象“key”，即可能包含子目录的文件名。

The generalities of /vsicurl/ apply.

可以使用多种身份验证方法，并按以下顺序进行尝试：

1. If GS_NO_SIGN_REQUEST=YES configuration option is set, request signing is disabled. This option might be used for buckets with public access rights. Available since GDAL 3.4

2. 这个 GS_SECRET_ACCESS_KEY 和 GS_ACCESS_KEY_ID 可以为AWS样式的身份验证设置配置选项

3. 这个 GDAL_HTTP_HEADER_FILE 指向带有“key:value”标题的文本文件的文件名的配置选项。通常，它必须包含“授权：持票人xxxxxxxx”行。

4. （GDAL>=2.3）的 GS_OAUTH2_REFRESH_TOKEN 可以将配置选项设置为使用OAuth2客户端身份验证。请参见http://code.google.com/api/accounts/docs/OAuth2.html可以使用 gdal_auth.py -s storage 或 gdal_auth.py -s storage-rw 脚本说明：您可以定义 GS_OAUTH2_CLIENT_ID 和 GS_OAUTH2_CLIENT_SECRET 配置选项（需要同时为gdal_auth.py和/vsigs的后续执行定义）

5. (GDAL >= 2.3) The GOOGLE_APPLICATION_CREDENTIALS configuration option can be set to point to a JSON file containing OAuth2 service account credentials (type: service_account), in particular a private key and a client email. See https://developers.google.com/identity/protocols/OAuth2ServiceAccount for more details on this authentication method. The bucket must grant the "Storage Legacy Bucket Owner" or "Storage Legacy Bucket Reader" permissions to the service account. The GS_OAUTH2_SCOPE configuration option can be set to change the default permission scope from "https://www.googleapis.com/auth/devstorage.read_write" to "https://www.googleapis.com/auth/devstorage.read_only" if needed.

6. (GDAL >= 3.4.2) The GOOGLE_APPLICATION_CREDENTIALS configuration option can be set to point to a JSON file containing OAuth2 user credentials (type: authorized_user).

7. （GDAL>=2.3）以前方法的变体。这个 GS_OAUTH2_PRIVATE_KEY （或） GS_OAUTH2_PRIVATE_KEY_FILE) 和 GS_OAUTH2_CLIENT_EMAIL 可以设置为使用OAuth2服务帐户身份验证。有关此身份验证方法的详细信息，请参阅https://developers.google.com/identity/protocols/oauth2serviceccount。这个 GS_OAUTH2_PRIVATE_KEY 配置选项必须以内联字符串形式包含私钥，以开头 -----BEGIN PRIVATE KEY----- . 或者 GS_OAUTH2_PRIVATE_KEY_FILE 可以设置配置选项以指示包含此类私钥的文件名。bucket必须向服务帐户授予“Storage Legacy bucket Owner”或“Storage Legacy bucket Reader”权限。这个 GS_OAUTH2_SCOPE 如果需要，可以将配置选项设置为将默认权限范围从“https://www.googleapis.com/auth/devstorage.read_write”更改为“https://www.googleapis.com/auth/devstorage.read_only”。

8. （GDAL>=2.3）提供凭证的另一种方法，类似于“gsutil”命令行实用程序或Boto3支持。如果未提供上述环境变量，则 ~/.boto 或 UserProfile%/.boto 将读取文件（或由 CPL_GS_CREDENTIALS_FILE )用于AWS样式身份验证的gs_secret_access_key和gs_access_key_id条目。如果找不到，它将查找用于oauth2客户端身份验证的gs_oauth2_refresh_令牌（以及可选的客户端id和客户端机密）条目。

9. （GDAL>=2.3）最后，如果上述方法均未成功，代码将检查当前计算机是否是Google计算引擎实例，如果是，则使用与其关联的权限（使用与VM关联的默认服务帐户）。要强制将计算机检测为GCE实例（例如，在无法访问启动日志的容器中运行的代码），可以设置 CPL_MACHINE_IS_GCE 到 YES .

自GDAL 3.1以来，支持Rename（）操作（首先复制原始文件，然后将其删除）。

Starting with GDAL 3.4, the GS_USER_PROJECT configuration option can be set to a Google Project id (see https://cloud.google.com/storage/docs/xml-api/reference-headers#xgooguserproject) to charge for requests against Requester Pays buckets.

2.2 新版功能.

/vsigs_streaming/（谷歌云存储文件：streaming）

/vsigs_streaming/是一个文件系统处理程序，它允许实时顺序读取Google云存储桶中可用的文件（主要是非公共文件），而无需事先下载整个文件。它需要针对libcurl构建GDAL。

可识别的文件名的格式为 /vsigs_streaming/bucket/key 在哪里？ bucket 是桶的名字和 key 是对象“key”，即可能包含子目录的文件名。

Authentication options, and read-only features, are identical to /vsigs/

2.2 新版功能.

/vsiaz/（Microsoft Azure Blob文件）

/vsiaz/是一个文件系统处理程序，它允许即时随机读取Microsoft Azure Blob容器中可用的（主要是非公共的）文件，而无需事先下载整个文件。它需要针对libcurl构建GDAL。

See /vsiadls/ for a related filesystem for Azure Data Lake Storage Gen2.

它还允许顺序写入文件。不允许进行寻道或读取操作，因此特别不支持使用GTiff驱动程序直接写入GeoTIFF文件，除非从gdal3.2开始 CPL_VSIL_USE_TEMP_FILE_FOR_RANDOM_WRITE 配置选项设置为 YES ，在这种情况下，可以进行随机写访问（包括创建临时本地文件，其位置由 CPL_TMPDIR 配置选项）。如果文件大小低于4 MB，将创建块blob。除此之外，将创建一个append blob（最大文件大小为195gb）。

删除文件 VSIUnlink() ，创建目录 VSIMkdir() 和删除（空）目录 VSIRmdir() 也有可能。注意：使用时 VSIMkdir() ，一个特殊的隐藏 .gdal_marker_for_dir 已创建空文件，因为Azure Blob本机不支持空目录。如果该文件是目录中剩下的最后一个文件， VSIRmdir() 将自动删除它。此文件将不与一起显示 VSIReadDir() . 如果从未使用创建的目录中删除文件 VSIMkdir() ，当最后一个文件被删除时，其目录将被Azure自动删除，因此 VSIUnlink("/vsiaz/container/subdir/lastfile") 然后 VSIRmdir("/vsiaz/container/subdir") 会失败的 VSIRmdir() 召唤。

可识别的文件名的格式为 /vsiaz/container/key 在哪里 container 是容器的名称和 key 是对象“key”，即可能包含子目录的文件名。

The generalities of /vsicurl/ apply.

可以使用多种身份验证方法，并按以下顺序进行尝试：

1. 这个 AZURE_STORAGE_CONNECTION_STRING 配置选项，在管理界面的访问密钥部分提供。它包含帐户名和密钥。

2. 这个 AZURE_STORAGE_ACCOUNT 配置选项设置为指定帐户名和

   1. (GDAL >= 3.5) The AZURE_STORAGE_ACCESS_TOKEN configuration option is set to specify the access token, that will be included in a "Authorization: Bearer ${AZURE_STORAGE_ACCESS_TOKEN}" header. This access token is typically obtained using Microsoft Authentication Library (MSAL).

   2. 这个 AZURE_STORAGE_ACCESS_KEY 配置选项设置为指定密钥。

   3. 这个 AZURE_NO_SIGN_REQUEST=YES 设置配置选项，以便禁用任何请求签名。此选项可用于具有公共访问权限的帐户。从GDAL 3.2开始提供

   4. The AZURE_STORAGE_SAS_TOKEN configuration option (AZURE_SAS if GDAL < 3.5) is set to specify a Shared Access Signature. This SAS is appended to URLs built by the /vsiaz/ file system handler. Its value should already be URL-encoded and should not contain any leading '?' or '&' character (e.g. a valid one may look like "st=2019-07-18T03%3A53%3A22Z&se=2035-07-19T03%3A53%3A00Z&sp=rl&sv=2018-03-28&sr=c&sig=2RIXmLbLbiagYnUd49rgx2kOXKyILrJOgafmkODhRAQ%3D"). Available since GDAL 3.2

   5. 当前计算机是一个具有分配给它的Azure Active Directory权限的Azure虚拟机（请参阅）https://docs.microsoft.com/en-us/azure/active-directory/managed-identies-azure-resources/qs-configure-portal-windows-vm). 从GDAL 3.3开始提供

3. Starting with GDAL 3.5, the configuration file <https://github.com/MicrosoftDocs/azure-docs-cli/blob/main/docs-ref-conceptual/azure-cli-configuration.md> of the "az" command line utility can be used. The following keys of the [storage] section will be used in the following priority: connection_string, account + key or account + sas_token

从gdal3.1开始 VSIRename() 支持操作（先复制原始文件，然后删除）

Since GDAL 3.3, the VSIGetFileMetadata() and VSISetFileMetadata() operations are supported.

2.3 新版功能.

/vsiaz_流式处理/（Microsoft Azure Blob文件：流式处理）

/vsiaz_streaming/是一个文件系统处理程序，它允许实时顺序读取Microsoft Azure Blob容器、bucket中可用的文件（主要是非公共文件），而无需事先下载整个文件。它需要针对libcurl构建GDAL。

可识别的文件名的格式为 /vsiaz_streaming/container/key 在哪里？ container 是容器的名称和 key 是对象“key”，即可能包含子目录的文件名。

Authentication options, and read-only features, are identical to /vsiaz/

2.3 新版功能.

/vsiadls/（Microsoft Azure数据湖存储Gen2）

/vsiadls/是一个文件系统处理程序，允许动态随机读取Microsoft Azure Data Lake存储文件系统中可用的（主要是非公共）文件，而无需事先下载整个文件。它需要根据libcurl构建GDAL。

It has similar capabilities as /vsiaz/, and in particular uses the same configuration options for authentication. Its advantages over /vsiaz/ are a real management of directory and Unix-style ACL support. Some features require the Azure storage to have hierarchical support turned on. Consult its documentation

/vsiaz/的主要增强功能包括：

• 真正的目录支持（不需要人工 .gdal_marker_for_dir 用于/vsiaz/的空文件（要有空目录）

• 一次调用递归目录删除 VSIRmdirRecursive()

• 原子重命名 VSIRename()

• VSIGetFileMetadata() 对“ACL”和“STATUS”元数据的支持

• VSISetFileMetadata() 支持“属性”和“ACL”元数据域

3.3 新版功能.

/vsioss/（阿里云OSS文件）

/vsioss/是一个文件系统处理程序，允许在不预先下载整个文件的情况下，实时随机读取阿里云对象存储服务（OSS）存储桶中可用的（主要是非公开的）文件。它需要针对libcurl构建GDAL。

它还允许顺序写入文件。不允许进行寻道或读取操作，因此特别不支持使用GTiff驱动程序直接写入GeoTIFF文件，除非从gdal3.2开始 CPL_VSIL_USE_TEMP_FILE_FOR_RANDOM_WRITE 配置选项设置为 YES ，在这种情况下，可以进行随机写访问（包括创建临时本地文件，其位置由 CPL_TMPDIR 配置选项）。删除带有 VSIUnlink() 也支持。目录的创建 VSIMkdir() 和删除（空）目录 VSIRmdir() 也有可能。

可识别的文件名的格式为 /vsioss/bucket/key 在哪里？ bucket 是OSS bucket的名称，并且 key 是OSS对象“key”，即可能包含子目录的文件名。

The generalities of /vsicurl/ apply.

这个 OSS_SECRET_ACCESS_KEY 和 OSS_ACCESS_KEY_ID 必须设置配置选项。这个 OSS_ENDPOINT 配置选项通常应设置为适当的值，该值反映附属于bucket的区域。默认值是 oss-us-east-1.aliyuncs.com . 如果bucket存储在oss-us-east-1之外的另一个区域，那么代码逻辑将重定向到相应的端点。

在写入时，使用OSS multipart upload API上传文件。默认情况下，块的大小设置为50MB，允许创建高达500GB的文件（10000个部分，每个部分50MB）。如果需要更大的文件，则增加 VSIOSS_CHUNK_SIZE 将配置选项设置为更大的值（以MB表示）。如果进程被终止，文件未正确关闭，则多部分上传将保持打开状态，导致阿里巴巴向您收取部件存储费用。你得用其他方法自杀。对于小于块大小的文件，使用简单的PUT请求，而不是多部分上传API。

2.3 新版功能.

/vsioss_streaming/（阿里云OSS文件：streaming）

/vsioss_streaming/是一个文件系统处理程序，它允许实时顺序读取阿里云对象存储服务（OSS）存储桶中的文件（主要是非公共文件），而无需事先下载整个文件。它需要针对libcurl构建GDAL。

可识别的文件名的格式为 /vsioss_streaming/bucket/key 在哪里？ bucket 是桶的名字和 key 是对象“key”，即可能包含子目录的文件名。

Authentication options, and read-only features, are identical to /vsioss/

2.3 新版功能.

/vsiswift/（OpenStack Swift对象存储）

/vsiswift/是一个文件系统处理程序，它允许随时随机读取OpenStack Swift Object Storage（Swift）存储桶中可用的（主要是非公共的）文件，而无需事先下载整个文件。它需要针对libcurl构建GDAL。

它还允许顺序写入文件。不允许进行寻道或读取操作，因此特别不支持使用GTiff驱动程序直接写入GeoTIFF文件，除非从gdal3.2开始 CPL_VSIL_USE_TEMP_FILE_FOR_RANDOM_WRITE 配置选项设置为 YES ，在这种情况下，可以进行随机写访问（包括创建临时本地文件，其位置由 CPL_TMPDIR 配置选项）。删除带有 VSIUnlink() 也支持。目录的创建 VSIMkdir() 和删除（空）目录 VSIRmdir() 也有可能。

可识别的文件名的格式为 /vsiswift/bucket/key 在哪里？ bucket 是雨燕水桶的名字 key 是swift对象“key”，即可能包含子目录的文件名。

The generalities of /vsicurl/ apply.

可以使用三种身份验证方法，尝试的顺序如下：

1. 这个 SWIFT_STORAGE_URL 和 SWIFT_AUTH_TOKEN 配置选项分别设置为存储URL（例如http://127.0.0.1:12345/v1/AUTH_something）和x-AUTH-token授权令牌的值。

2. 这个 SWIFT_AUTH_V1_URL ， SWIFT_USER 和 SWIFT_KEY 配置选项分别设置为Auth V1身份验证的端点（例如http://127.0.0.1:12345/Auth/V1.0）、用户名和密钥/密码。此身份验证终结点将用于检索第一种身份验证方法中提到的存储URL和授权令牌。

3. Keystone v3的身份验证使用与python swiftclient相同的选项，请参见https://docs.openstack.org/python-swiftclient/latest/cli/index.html#身份验证更多细节。GDAL（>=3.1）支持以下选项：

   • OS_IDENTITY_API_VERSION=3

   • OS_AUTH_URL

   • OS_USERNAME

   • OS_PASSWORD

   • OS_USER_DOMAIN_NAME

   • OS_PROJECT_NAME

   • OS_PROJECT_DOMAIN_NAME

   • OS_REGION_NAME

4. Application Credential Authentication via Keystone v3, GDAL (>= 3.3.1) supports application-credential authentication with the following options:

   • OS_IDENTITY_API_VERSION=3

   • OS_AUTH_TYPE=v3applicationcredential

   • OS_AUTH_URL

   • OS_APPLICATION_CREDENTIAL_ID

   • OS_APPLICATION_CREDENTIAL_SECRET

   • OS_REGION_NAME

此文件系统处理程序还允许按顺序写入文件（不允许执行查找或读取操作）。

在某些版本的OpenStack Swift中，对大型（分段）文件的访问失败，除非它们显式标记为静态大型对象，而不是默认的动态大型对象。使用python-swiftclient，通过传递 --use-slo 标志（参见https://docs.openstack.org/python-swiftclient/latest/cli/index.html#swift-所有上传选项）。有关大型对象的详细信息，请参见https://docs.openstack.org/swift/latest/api/largeu objects.html。

2.3 新版功能.

/vsiswift_streaming/（OpenStack Swift对象存储：流）

/vsiswift_streaming/是一个文件系统处理程序，它允许实时顺序读取OpenStack Swift Object Storage（Swift）存储桶中可用的文件（主要是非公共文件），而无需事先下载整个文件。它需要针对libcurl构建GDAL。

可识别的文件名的格式为 /vsiswift_streaming/bucket/key 在哪里？ bucket 是桶的名字和 key 是对象“key”，即可能包含子目录的文件名。

Authentication options, and read-only features, are identical to /vsiswift/

2.3 新版功能.

/vsihdfs/（Hadoop文件系统）

/vsihdfs/ is a file system handler that provides read access to HDFS. This handler requires GDAL to have been built with Java support (--with-java) and HDFS support (--with-hdfs). Support for this handler is currently only available on Unix-like systems. Note: support for the HTTP REST API (webHdfs) is also available with /vsiwebhdfs/（Web Hadoop文件系统REST API）

可识别的文件名的格式为 /vsihdfs/hdfsUri 在哪里？ hdfsUri 是有效的HDFS URI。

实例：

/vsihdfs/file:/tmp/my.tif  (a local file accessed through HDFS)
/vsihdfs/hdfs:/hadoop/my.tif  (a file stored in HDFS)

2.4 新版功能.

/vsiwebhdfs/（Web Hadoop文件系统REST API）

/vsiwebhdfs/是一个文件系统处理程序，通过其HTTP REST API提供对HDFS的读写访问。

可识别的文件名的格式为 /vsiwebhdfs/http://hostname:port/webhdfs/v1/path/to/filename .

实例：

/vsiwebhdfs/http://localhost:50070/webhdfs/v1/mydir/byte.tif

它还允许顺序写入文件。不允许进行寻道或读取操作，因此特别不支持使用GTiff驱动程序直接写入GeoTIFF文件，除非从gdal3.2开始 CPL_VSIL_USE_TEMP_FILE_FOR_RANDOM_WRITE 配置选项设置为 YES ，在这种情况下，可以进行随机写访问（包括创建临时本地文件，其位置由 CPL_TMPDIR 配置选项）。删除带有 VSIUnlink() 也支持。目录的创建 VSIMkdir() 和删除（空）目录 VSIRmdir() 也有可能。

The generalities of /vsicurl/ apply.

以下配置选项可用：

• WEBHDFS_USERNAME =值：用户名（当安全性关闭时）。

• WEBHDFS_DELEGATION =值：Hadoop委派令牌（当安全性打开时）。

• WEBHDFS_DATANODE_HOST =值：对于使用重定向的API，将重定向主机名替换为此选项提供的主机名（通常可解析主机名应由代理重写）

• WEBHDFS_REPLICATION =int_value：创建文件时使用的复制值

• WEBHDFS_PERMISSION =int_value:创建文件或目录时的权限掩码（以十进制数字形式提供）

此文件系统处理程序还允许按顺序写入文件（然后不允许查找或读取操作）

2.4 新版功能.

/vsistdin/（标准输入流）

/vsistdin/是一个允许从标准输入流读取的文件处理程序。

文件名语法必须仅为 /vsistdin/ .

当然，可用的文件操作仅限于Read（）和forward Seek（）。可以在文件的前MB中进行完全查找，并将其缓存，以便关闭、重新打开 /vsistdin/ 在同一个过程中，在第一兆字节内可以多次读取。

/vsistdout/（标准输出流）

/vsistdout/是一个允许写入标准输出流的文件处理程序。

文件名语法必须仅为 /vsistdout/ .

当然，可用的文件操作仅限于Write（）。

此文件系统的变体存在于 /vsistdout_redirect/ 文件系统处理程序，其中输出函数可以用 VSIStdoutSetRedirection() .

/vsimem/（内存文件）

/vsimem/是一个文件处理程序，它允许将内存块视为文件。基本路径下的文件系统的所有部分 /vsimem/ 将由这个司机处理。

普通的VSI*L函数可以自由地用于创建和销毁内存数组，将它们视为真正的文件系统对象。另外还有一些方法可以有效地创建内存文件系统对象，而无需复制数据的原始副本，或者“窃取”与内存文件相关联的内存块。见 VSIFileFromMemBuffer() 和 VSIGetMemFileBuffer() .

支持与目录相关的函数。

/vsimem/文件在同一进程中可见。如果多个线程使用不同的句柄，则它们可以在读取模式下访问同一基础文件，但不支持对同一基础文件执行并发的写和读操作（锁定由调用代码负责）。

/vsisubfile/（部分文件）

/vsisubfile/virtual文件系统处理程序允许访问文件的子区域，并将它们作为文件单独处理到虚拟文件系统函数（VSIFOpenL（）等）。

文件名的特殊形式用于指示另一个文件的子部分： /vsisubfile/<offset>[_<size>],<filename> .

size参数是可选的。如果没有它，则从开始偏移量开始的文件的剩余部分将被视为子文件的一部分。否则，只有<offset>中的<size>字节被视为子文件的一部分。<filename>部分可以是使用普通规则的相对或绝对路径。<offset>和<size>值以字节为单位。

实例：

/vsisubfile/1000_3000,/data/abc.ntf
/vsisubfile/5000,../xyz/raw.dat

与/vsimem/或传统的文件系统处理程序不同，对于在/vsisubfile/区域中创建新文件、遍历目录和删除文件的文件系统操作没有有意义的支持。只有 VSIStatL() ， VSIFOpenL() 和基于返回的文件句柄的操作 VSIFOpenL() 操作正常。

/vsisparse/（稀疏文件）

/vsisparse/virtual文件处理程序允许虚拟文件由其他文件中的数据块组成，虚拟文件中的大空间可能设置为常量值。这样就可以在图像数据设置为常量的大文件上测试某些操作。如果要将测试文件添加到太大但可以忽略大部分数据的测试套件中，则此功能也很有用。理论上，它还可以用来将不同文件系统上的多个文件视为一个大型虚拟文件。

/vsisparse/引用的文件应该是XML控制文件，格式如下：

<VSISparseFile>
    <Length>87629264</Length>
    <SubfileRegion>  <!-- Stuff at start of file. -->
        <Filename relative="1">251_head.dat</Filename>
        <DestinationOffset>0</DestinationOffset>
        <SourceOffset>0</SourceOffset>
        <RegionLength>2768</RegionLength>
    </SubfileRegion>

    <SubfileRegion>  <!-- RasterDMS node. -->
        <Filename relative="1">251_rasterdms.dat</Filename>
        <DestinationOffset>87313104</DestinationOffset>
        <SourceOffset>0</SourceOffset>
        <RegionLength>160</RegionLength>
    </SubfileRegion>

    <SubfileRegion>  <!-- Stuff at end of file. -->
        <Filename relative="1">251_tail.dat</Filename>
        <DestinationOffset>87611924</DestinationOffset>
        <SourceOffset>0</SourceOffset>
        <RegionLength>17340</RegionLength>
    </SubfileRegion>

    <ConstantRegion>  <!-- Default for the rest of the file. -->
        <DestinationOffset>0</DestinationOffset>
        <RegionLength>87629264</RegionLength>
        <Value>0</Value>
    </ConstantRegion>
</VSISparseFile>

希望这些值和语义是相当明显的。

文件缓存

这不是一个正确的虚拟文件系统处理程序，而是一个C函数，它接受一个虚拟文件句柄并返回一个新句柄，该句柄缓存对输入文件句柄的读取操作。缓存是基于RAM的，当文件句柄关闭时，缓存的内容将被丢弃。缓存是最近最少使用的块列表，每个块32KB。

这个 VSICachedFile 类在那个时候只处理读操作，并且在写操作时出错。

这是用 VSICreateCachedFile() 函数，如果 VSI_CACHE 配置选项设置为 YES .

每个文件的默认缓存大小为25 MB（每个缓存的文件为25 MB），可以使用 VSI_CACHE_SIZE 配置选项（字节值）。

/vsicrypt/（加密文件）

/vsicrypt/是一个特殊的文件处理程序，它允许读取/创建/更新动态加密文件，并具有随机访问功能。

参照 VSIInstallCryptFileHandler() 了解更多详细信息。