GDAL仮想ファイルシステム(圧縮、ネットワークホスト、など...): /vsimem, /vsizip, /vsitar, /vsicurl, ...

はじめに

GDALは"標準"ファイルシステム上にあるファイルにアクセスできます.つまり,Unix系システムの / 階層やWindowsの C:, D:などのドライブです.しかし,ほとんどのGDALラスターおよびベクタードライバはGDAL固有の抽象化を使用してファイルにアクセスします.これにより,メモリ内ファイル,圧縮ファイル(.zip, .gz, .tar, .tar.gzアーカイブ),暗号化ファイル,標準入力および出力(STDIN, STDOUT),ネットワーク上のファイル(公開アクセス可能なもの,または商用クラウドストレージサービスのプライベートバケット内のもの)など,標準でない種類のファイルにアクセスできます.

各特殊ファイルシステムにはプレフィックスがあり,ファイルを名前付ける一般的な構文は/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/... と一つのスラッシュで書いてもよいです. (ただし,ドキュメントを書く際は引き続き二つ使用してください.))

仮想ファイルシステムをサポートするドライバ

仮想ファイルシステムは,現在のほとんどのファイルベースのドライバである"大規模ファイルAPI"をサポートするGDALまたはOGRドライバでのみ使用できます.これらのフォーマットの完全なリストは, gdalinfo --formats または ogrinfo --formats を実行するときに'v'でマークされたドライバを見ることで取得できます.

注目すべき例外はHDF4ドライバです.

/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/...") 呼び出しはファイルの解凍されたサイズを返します. ZIPファイル内のディレクトリは通常のファイルシステムと同様に,通常のファイルと区別することができます.ディレクトリリストとファイル統計の取得は高速な操作です.

注: .zipファイルがそのルートにある単一のファイルを含む特定の場合には, /vsizip/path/to/the/file.zip とだけ記述するだけで動作します.

/zip/ ハンドラに固有の次の設定オプションがあります:

• CPL_SOZIP_ENABLED=[YES​/​NO​/​AUTO]: (GDAL >= 3.7) Defaults to AUTO. Determines whether the SOZip optimization should be enabled. If AUTO, SOZip will be enabled for uncompressed files larger than CPL_SOZIP_MIN_FILE_SIZE.

• CPL_SOZIP_MIN_FILE_SIZE=value: (GDAL >= 3.7) Defaults to 1M. Determines the minimum file size for SOZip to be automatically enabled.

例:

/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
/vsizip/{/vsizip/my.zip/subdir/subzip.zip}/subdir_in_subzip/my.shp  (alternate syntax for a nested .zip)

.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ユーティリティの独立モードに類似しています.デフォルトでは,入力ストリームは1MBのチャンクに分割されます(チャンクサイズは CPL_VSIL_DEFLATE_CHUNK_SIZE 設定オプションで調整でき, "x K" または "x M" のような値が使用できます),そして各チャンクは独立して圧縮されます(そして9バイトのマーカー 0x00 0x00 0xFF 0xFF 0x00 0x00 0x00 0xFF 0xFF で終了し,ストリームと辞書の完全なフラッシュを示し,各チャンクの独立したデコードを可能にします).これは圧縮率をわずかに低下させるため,非常に小さなチャンクサイズは避けるべきです. GDAL 3.7以降,この技術は SOZip (Seek-Optimized ZIP) に従って .zip ファイルを生成するために再利用されます.

読み取りおよび書き込み操作を交互に行うことはできません.新しいzipは,読み取りモードで再オープンする前に閉じる必要があります.

SOZip (Seek-Optimized ZIP)

GDAL (>= 3.7) は SOZip (Seek-Optimized ZIP) プロファイルに従う .zip ファイルの完全な読み取りおよび書き込みサポートを持っています.

• /vsizip/ 仮想ファイルシステムは,圧縮されたSOZip対応ファイル内での高速なランダムアクセスを実行するためにSOZipインデックスを使用します.

• ESRI Shapefile / DBF および GPKG -- GeoPackage vector ドライバは直接SOZip対応の .shz/.shp.zip または .gpkg.zip ファイルを生成できます.

• 新しいまたは既存のZIPファイルにファイルを圧縮して追加できる CPLAddFileInZip() C 関数は,SOZip最適化を有効にします(つまり,圧縮するファイルが1MBより大きい場合).SOZip最適化は, CPL_SOZIP_ENABLED 設定オプションをYESに設定することで強制できます.または,NOに設定することで完全に無効にできます.

• VSIGetFileMetadata() メソッドは, /vsizip/path/to/the/file.zip/path/inside/the/zip/file の形式のファイル名とドメイン = "ZIP" を指定して呼び出すことで,そのファイルにSOZipインデックスが利用可能かどうかの情報を取得できます.

• sozip 新しいコマンドラインユーティリティは,SOZip最適化されたZIPファイルを作成したり,既存のZIPファイルにファイルを追加したり, ZIPファイルの内容をリストしたり,SOZip最適化の状態を表示したり,SOZipファイルを検証したりするために使用できます.

/vsigzip/ (gzipped ファイル)

/vsigzip/ は,事前に解凍せずにGZip (.gz) ファイルを読み取ることができるファイルハンドラです.

GDALによって解凍された形式でgzippedファイルを表示するには, /vsigzip/path/to/the/file.gz 構文を使用する必要があります.ここで path/to/the/file.gz は相対または絶対です.

/vsigzip/ ハンドラに固有の次の設定オプションがあります:

• CPL_VSIL_GZIP_WRITE_PROPERTIES=[YES​/​NO]: Defaults to YES. If YES, when the file is located in a writable location, a file with extension .gz.properties is created with an indication of the uncompressed file size.

例:

/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/ファイルにも適用されます.

書き込み機能も利用できますが,読み取りおよび書き込み操作を交互に行うことはできません.

GDAL 2.4以降, GDAL_NUM_THREADS 設定オプションを整数または ALL_CPUS に設定することで,単一ファイルのマルチスレッド圧縮を有効にすることができます.これはpigzユーティリティの独立モードに類似しています.デフォルトでは,入力ストリームは1MBのチャンクに分割されます(チャンクサイズは CPL_VSIL_DEFLATE_CHUNK_SIZE 設定オプションで調整でき, "x K" または "x M" のような値が使用できます),そして各チャンクは独立して圧縮されます(そして9バイトのマーカー 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/...") 呼び出しはファイルの解凍されたサイズを返します. TARファイル内のディレクトリは通常のファイルと同様に,VSI_ISDIR(stat.st_mode) マクロで区別できます.ディレクトリリストとファイル統計の取得は高速な操作です.

注: .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 はこの代替構文を使用することもできます.

/vsi7z/ (.7z アーカイブ)

Added in version 3.7.

/vsi7z/ は,事前に解凍せずに7zアーカイブを読み取ることができるファイルハンドラです.このファイルシステムは読み取り専用です.ディレクトリリストと VSIStatL() は,上記のファイルシステムと同様に利用できます.

これには,`libarchive <https://libarchive.org/>`__ に対してGDALがビルドされていることが必要です(および実用的な使用のためにlibarchiveがLZMAサポートを持っていることが必要です).

7zファイル内のファイルを指すには,ファイル名は /vsi7z/path/to/the/file.7z/path/inside/the/7z/file の形式である必要があります.ここで path/to/the/file.7z は相対または絶対であり, path/inside/the/7z/file はアーカイブ内のファイルへの相対パスです.

この仮想ファイルシステムによって認識されるデフォルトの拡張子は次のとおりです: 7z, lpk (Esri ArcGIS Layer Package), lpkx, mpk (Esri ArcGIS Map Package), mpkx および ppkx (Esri ArcGIS Pro Project Package).

これらの拡張子に依存せずに連鎖を可能にし,代替構文が利用可能です.例えば, /vsi7z/{/path/to/the/archive}/path/inside/the/archive. /path/to/the/archive はこの代替構文を使用することもできます.

大きな圧縮ファイル内でのランダムシークは,後方シークが必要な場合に効率的ではありません(解凍はファイルの先頭から再開されます).パフォーマンスは,連続した読み取りで最も良くなります.

/vsirar/ (.rar アーカイブ)

Added in version 3.7.

/vsirar/ は,事前に解凍せずに RAR アーカイブを読み取ることができるファイルハンドラです.このファイルシステムは読み取り専用です.ディレクトリリストと VSIStatL() は,上記のファイルシステムと同様に利用できます.

これには,`libarchive <https://libarchive.org/>`__ に対してGDALがビルドされていることが必要です(および実用的な使用のためにlibarchiveがLZMAサポートを持っていることが必要です).

RARファイル内のファイルを指すには,ファイル名は /vsirar/path/to/the/file.rar/path/inside/the/rar/file の形式である必要があります.ここで path/to/the/file.rar は相対または絶対であり, path/inside/the/rar/file はアーカイブ内のファイルへの相対パスです.

この仮想ファイルシステムによって認識されるデフォルトの拡張子は次のとおりです: rar

これらの拡張子に依存せずに連鎖を可能にし,代替構文が利用可能です.例えば, /vsirar/{/path/to/the/archive}/path/inside/the/archive. /path/to/the/archive はこの代替構文を使用することもできます.

大きな圧縮ファイル内でのランダムシークは,後方シークが必要な場合に効率的ではありません(解凍はファイルの先頭から再開されます).パフォーマンスは,連続した読み取りで最も良くなります.

ネットワークベースのファイルシステム

特定の署名認証スキームを必要としないオンラインリソース用の一般的な /vsicurl/ ファイルシステムハンドラが存在します.これは, /vsis3/, /vsigs/, /vsiaz/, /vsioss/ または /vsiswift/ のような商用クラウドストレージサービス用のサブファイルシステムに特化しています.

ファイル全体をストリーミング方式で読み取ることが可能な場合,効率を上げるために, /vsicurl_streaming/ および上記のクラウドストレージサービス用のその他のバリアントを使用することをお勧めします.

資格情報の設定方法は？

クラウドストレージサービスでは,資格情報の設定が必要です.それらのうちのいくつかについては,設定ファイル(~/.aws/config, ~/.boto, ..) または環境変数/設定オプションを通じて提供できます.

GDAL 3.6以降, VSISetPathSpecificOption() を使用して,ファイルパスのレベルで設定オプションを設定できます.これにより,同じ仮想ファイルシステムを使用しても異なる資格情報(例: バケット "/vsis3/foo" と "/vsis3/bar" の異なる資格情報)を使用する場合に簡単になります.

GDAL 3.5以降,資格情報(またはパス固有のオプション)は, CPLLoadConfigOptionsFromFile() で明示的にロードされる特定の設定ファイル,または CPLLoadConfigOptionsFromPredefinedFiles() によって自動的にロードされるデフォルトの設定ファイルのいずれかに, GDAL設定ファイル で指定できます.

それらは [credentials] セクションの下に配置する必要があり,各パスプレフィックスについては,その名前が [. で始まる相対的なサブセクションの下に配置する必要があります(例: [.some_arbitrary_name]),そして最初のキーは 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

ネットワーク/クラウド対応性とファイルフォーマット

ほとんどのGDALラスターおよびベクトルファイルシステムは, /vsicurl/ およびその他の派生仮想ファイルシステムを使用してリモートでアクセスできますが,パフォーマンスはフォーマットに大きく依存し,特定のフォーマットでも特定のデータ配置に依存します.パフォーマンスはまた,ファイルへの特定のアクセスパターンにも依存します.

ラスターファイルのインタラクティブな可視化のためには,ファイルは理想的には次の特性を持つべきです:

• 正方形のタイルでタイリングされているべきです

• ファイル内にタイルの位置のインデックスがあるべきです

• オーバービュー/ピラミッドがあるべきです

TIFF/GeoTIFF

COG -- Cloud Optimized GeoTIFF generator ドライバによって生成されたクラウド最適化GeoTIFFファイルは,ネットワークアクセスに適しています.より一般的には,オーバービューを持つタイルGeoTIFFファイルが適しています.

JPEG2000

JPEG2000は,その目的に適したレイアウトを使用し,最適化されたJPEG200ライブラリを使用している場合を除いて,一般的にネットワークアクセスには適していません.

JPEG2000ファイルには,さまざまな種類があります: シングルタイル vs タイル,異なる進行順序(これはシングルタイルアクセスに特に重要です),およびオプションのマーカーがあります

OpenJPEGライブラリ(JP2OpenJPEG -- JPEG2000 driver based on OpenJPEG library ドライバを介して使用可能)は,書かれた時点で,ピクセルクエリの関心領域に参加する各タイルパートを全体で取り込む必要があります(したがって,シングルタイルファイルの場合,ファイル全体を取り込む必要があります).また,タイルインデックスの相当物であるTLM (Tile-Part length) マーカーを使用しません,またはタイル内のパケットのインデックスであるPLT (Packed Length, tile-part header) を使用しません. Kakaduライブラリ(JP2KAK -- JPEG 2000 (based on Kakadu SDK) ドライバを介して使用可能)は,これらのマーカーを使用して取り込むバイト数を制限できます(ただし,シングルタイルラスタの場合,パフォーマンスがまだ低下する可能性があります).

dump_jp2.py Pythonスクリプトを使用して,指定されたJPEG200ファイルの特性を確認できます.出力で調査するのに興味のあるフィールドは次のとおりです:

• タイルサイズ(SIZ マーカーの XTsiz および YTsiz フィールドで指定される)

• TLM マーカーの存在

• the presence of PLT markers

/vsicurl/ (http/https/ftp ファイル: ランダムアクセス)

/vsicurl/ は,事前にファイル全体をダウンロードすることなく,HTTP/FTPウェブプロトコルを介して利用可能なファイルのランダム読み取りを可能にするファイルシステムハンドラです.これには,libcurlを利用してGDALがビルドされている必要があります.

認識されるファイル名は, /vsicurl/http[s]://path/to/remote/resource または /vsicurl/ftp://path/to/remote/resource の形式であり, path/to/remote/resource はリモートリソースのURLです.

ogrinfo を使用してインターネット上のシェープファイルを読み取る例:

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エンコードされています.現在サポートされているオプションは次のとおりです:

• use_head=yes/no: HTTP HEADリクエストを送信できるかどうか.デフォルトはYES.このオプションを設定すると, CPL_VSIL_CURL_USE_HEAD 設定オプションの動作が上書きされます.

• max_retry=number: デフォルトは0.このオプションを設定すると, GDAL_HTTP_MAX_RETRY 設定オプションの動作が上書きされます.

• retry_delay=number_in_seconds: デフォルトは30.このオプションを設定すると, GDAL_HTTP_RETRY_DELAY 設定オプションの動作が上書きされます.

• retry_codes=``ALL`` またはカンマ区切りのHTTPエラーコードのリスト.このオプションを設定すると, GDAL_HTTP_RETRY_CODES 設定オプションの動作が上書きされます. (GDAL >= 3.10)

• list_dir=yes/no: ファイルが存在するディレクトリのファイルリストを読み取る試みを行うかどうか.デフォルトはYESです.

• useragent=value: HTTP UserAgent header

• referer=value: HTTP Referer header

• cookie=value: HTTP Cookie header

• header_file=value: 1つまたは複数の "Header: Value" 行を含むファイル名

• unsafessl=yes/no

• low_speed_time=value

• low_speed_limit=value

• proxy=value

• proxyauth=value

• proxyuserpwd=value

• pc_url_signing=yes/no: Microsoft Planetary Computer の URL署名メカニズム(https://planetarycomputer.microsoft.com/docs/concepts/sas/) を使用するかどうか. (GDAL >= 3.5.2). GDAL 3.9以降,これは VSICURL_PC_URL_SIGNING というパス固有のオプション( cf VSISetPathSpecificOption()) を YES に設定することでも設定できます.

• pc_collection=name: Planetary Computer URL署名のデータセットのコレクション名. pc_url_signing=yes の場合のみ使用されます. (GDAL >= 3.5.2)

部分ダウンロード(サーバーがランダム読み取りをサポートしている必要があります)は,デフォルトで16 KBの粒度で行われます.GDAL 2.3以降,チャンクサイズは,バイト単位の値で CPL_VSIL_CURL_CHUNK_SIZE 設定オプションで設定できます.ドライバが連続読み取りを検出すると,ダウンロードパフォーマンスを向上させるために,チャンクサイズを CPL_VSIL_CURL_CHUNK_SIZE の128倍(デフォルトで2 MB)まで徐々に増やします.

さらに,すべてのダウンロードコンテンツ間で共有される16 MBのグローバル最近使用されたキャッシュが使用され,ファイルハンドルが閉じられ再オープンされると,プロセスの寿命中または VSICurlClearCache() が呼び出されるまで,キャッシュ内のコンテンツが再利用される可能性があります. GDAL 2.3以降,このグローバルLRUキャッシュのサイズは,設定オプション CPL_VSIL_CURL_CACHE_SIZE (バイト単位) を設定することで変更できます.

連続読み取りを最適化するために CPL_VSIL_CURL_CHUNK_SIZE の値を増やす場合, CPL_VSIL_CURL_CACHE_SIZE の値も CPL_VSIL_CURL_CHUNK_SIZE の値の128倍に増やすことをお勧めします.

GDAL 2.3以降, GDAL_INGESTED_BYTES_AT_OPEN 設定オプションを設定して,ファイルを開いたときにGET呼び出しで読み取るバイト数を強制することができます(Cloud optimized 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以降,追加のHTTPヘッダーを送信するために, GDAL_HTTP_HEADER_FILE 設定オプションを設定して,"key: value" HTTPヘッダーを含むテキストファイルのファイル名を指定できます.

代替として,GDAL 3.6以降, GDAL_HTTP_HEADERS 設定オプションを使用してヘッダーを指定することもできます. CPL_CURL_VERBOSE=YES は, --debug と組み合わせて,それらを表示することができます.

Starting with GDAL 3.10, the Authorization header is no longer automatically forwarded when redirections are followed. That behavior can be configured by setting the CPL_VSIL_CURL_AUTHORIZATION_HEADER_ALLOWED_IF_REDIRECT configuration option.

GDAL 2.3以降, GDAL_HTTP_MAX_RETRY (試行回数) および GDAL_HTTP_RETRY_DELAY (秒単位) 設定オプションを設定することで,HTTPエラー429, 502, 503または504の場合にリクエストの再試行が行われます.

GDAL 3.6以降,以下の設定オプションでTCP keep-alive機能を制御できます(詳細な説明については,https://daniel.haxx.se/blog/2020/02/10/curl-ootw-keepalive-time/ を参照してください):

• GDAL_HTTP_TCP_KEEPALIVE = YES/NO. TCP keep-alive を有効にするかどうか.デフォルトはNOです

• GDAL_HTTP_TCP_KEEPIDLE = integer, 秒単位. Keep-alive アイドル時間. デフォルトは60です.GDAL_HTTP_TCP_KEEPALIVE=YES の場合のみ考慮されます.

• GDAL_HTTP_TCP_KEEPINTVL = integer, 秒単位. Keep-alive プローブ間の間隔時間. デフォルトは60です.GDAL_HTTP_TCP_KEEPALIVE=YES の場合のみ考慮されます.

GDAL 3.7以降,以下の設定オプションでSSLクライアント証明書のサポートを制御できます:

• GDAL_HTTP_SSLCERT = filename. SSLクライアント証明書のファイル名. Cf https://curl.se/libcurl/c/CURLOPT_SSLCERT.html

• GDAL_HTTP_SSLCERTTYPE = string. SSL証明書の形式: "PEM" または "DER". Cf https://curl.se/libcurl/c/CURLOPT_SSLCERTTYPE.html

• GDAL_HTTP_SSLKEY = filename. TLSおよびSSLクライアント証明書のプライベートキーファイル. Cf https://curl.se/libcurl/c/CURLOPT_SSLKEY.html

• GDAL_HTTP_KEYPASSWD = string. プライベートキーのパスフレーズ. Cf https://curl.se/libcurl/c/CURLOPT_KEYPASSWD.html

一般的には,設定オプションを介して利用可能な CPLHTTPFetch() のオプションが利用可能です.GDAL 3.7以降,上記の設定オプションは, VSISetPathSpecificOption() でパス固有のオプションとしても指定できます.

ファイルは,設定オプション VSI_CACHE を TRUE に設定することでRAMにキャッシュできます.キャッシュサイズはデフォルトで25 MBですが,設定オプション VSI_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 メンバーに,ファイルの性質-ファイルまたはディレクトリ-を st_mode メンバーに返します(後者は現時点ではFTPリソースでのみ信頼できます).

VSIReadDir() は,ApacheやMicrosoft IISなどの最も一般的なWebサーバーが返すHTMLディレクトリリストを解析できるはずです.

/vsicurl_streaming/ (http/https/ftp ファイル: ストリーミング)

/vsicurl_streaming/ は,HTTP/FTPウェブプロトコルを介してストリーミングされたファイルのランダム読み取りを可能にするファイルシステムハンドラです.これには,libcurlを利用してGDALがビルドされている必要があります.

このファイルハンドラはファイル内のランダムオフセットにシークできますが,これは効率的ではありません.効率的なランダムアクセスが必要で,かつサーバーが範囲ダウンロードをサポートしている場合は,代わりに /vsicurl/ ファイルシステムハンドラを使用する必要があります.

認識されるファイル名は, /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 はシステムの場所にファイルを使用します).

ファイルは,設定オプション VSI_CACHE を TRUE に設定することでRAMにキャッシュできます.キャッシュサイズはデフォルトで25 MBですが,設定オプション VSI_CACHE_SIZE (バイト単位) を設定することで変更できます.

VSIStatL() は,サイズを st_size メンバーに,ファイルの性質-ファイルまたはディレクトリ-を st_mode メンバーに返します(後者は現時点ではFTPリソースでのみ信頼できます).

/vsis3/ (AWS S3 ファイル)

/vsis3/ は,AWS S3バケットで利用可能な(主に非公開の)ファイルのランダム読み取りを可能にするファイルシステムハンドラです.これには,libcurlを利用してGDALがビルドされている必要があります.

また,ファイルの順次書き込みも可能です.その場合,シークや読み取り操作は許可されません.したがって,GTiffドライバを使用してGeoTIFFファイルに直接書き込むことはサポートされません.ただし,GDAL 3.2以降, CPL_VSIL_USE_TEMP_FILE_FOR_RANDOM_WRITE 設定オプションを YES に設定すると,ランダム書き込みアクセスが可能になります( CPL_TMPDIR 設定オプションで制御される一時ローカルファイルの作成が含まれます). VSIUnlink() によるファイルの削除もサポートされています. GDAL 2.3以降, VSIMkdir() でディレクトリの作成, VSIRmdir() で(空の)ディレクトリの削除も可能です.

認識されるファイル名は, /vsis3/bucket/key の形式です.ここで, bucket はS3バケットの名前であり,``key`` はS3オブジェクトの"key"であり,サブディレクトリを含む可能性のあるファイル名です.

/vsicurl/ の一般的な情報が適用されます.

/vsis3/ ハンドラに固有の以下の設定オプションがあります:

• AWS_NO_SIGN_REQUEST=[YES​/​NO]: Determines whether to disable request signing.

• AWS_ACCESS_KEY_ID=value: Access key ID used for authentication. If using temporary credentials, AWS_SESSION_TOKEN must be set.

• AWS_SECRET_ACCESS_KEY=value: Secret access key associated with AWS_ACCESS_KEY_ID.

• AWS_SESSION_TOKEN=value: Session token used for validation of temporary credentials (AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY)

• CPL_AWS_CREDENTIALS_FILE=<filename>: Location of an AWS credentials file. If not specified, the standard location of ~/.aws/credentials will be checked.

• AWS_DEFAULT_PROFILE=value: Defaults to default. Name of AWS profile.

• AWS_PROFILE=value: (GDAL >= 3.2) Defaults to default. Name of AWS profile.

• AWS_CONFIG_FILE=value: Location of a config file that may provide credentials and the AWS region. if not specified the standard location of ~/.aws/credentials will be checked.

• AWS_ROLE_ARN=value: (GDAL >= 3.6) Amazon Resource Name (ARN) specifying the role to use for authentication via the AssumeRoleWithWebIdentity API.

• AWS_WEB_IDENTITY_TOKEN_FILE=<filename>: (GDAL >= 3.6)

  Duplicate explicit target name: "assumerolewithwebidentity api".

  認証に使用するアイデンティティトークンファイルへのパス. AssumeRoleWithWebIdentity API を介した認証に使用されます.

• AWS_REGION=value: Defaults to us-east-1. Set the AWS region to which requests should be sent. Overridden by AWS_DEFAULT_REGION.

• AWS_DEFAULT_REGION=value: Set the AWS region to which requests should be sent.

• AWS_REQUEST_PAYER=requester: Set to requester to access a Requester Pays bucket and acknowledge associated charges.

• AWS_S3_ENDPOINT=value: Defaults to s3.amazonaws.com. Allows the use of /vsis3/ with non-AWS remote object stores that use the AWS S3 protocol.

• AWS_HTTPS=[YES​/​NO]: Defaults to YES. If YES, AWS resources will be accessed using HTTPS. If NO, HTTP will be used.

• AWS_VIRTUAL_HOSTING=[TRUE​/​FALSE]: Defaults to TRUE. Select the method of accessing a bucket. If TRUE, identifies the bucket via a virtual bucket host name, e.g.: mybucket.cname.domain.com. If FALSE, identifies the bucket as the top-level directory in the URI, e.g.: cname.domain.com/mybucket

• VSIS3_CHUNK_SIZE=<MB>: Defaults to 50. Set the chunk size for multipart uploads.

• CPL_VSIL_CURL_IGNORE_GLACIER_STORAGE=[YES​/​NO]: Defaults to YES. When listing a directory, ignore files with GLACIER storage class. Superseded by CPL_VSIL_CURL_IGNORE_STORAGE_CLASSES.

• CPL_VSIL_CURL_IGNORE_STORAGE_CLASSES=value: Defaults to GLACIER\,DEEP_ARCHIVE. Comma-separated list of storage class names that should be ignored when listing a directory. If set to empty, objects of all storage classes are retrieved).

• CPL_VSIS3_USE_BASE_RMDIR_RECURSIVE=[YES​/​NO]: (GDAL >= 3.2) Defaults to NO. If YES, recursively delete objects to avoid using batch deletion.

• CPL_VSIS3_CREATE_DIR_OBJECT=[YES​/​NO]: Defaults to YES. Determines whether to allow VSIMkdir() to create an empty object to model an empty directory.

複数の認証方法が可能であり,以下の順序で試行されます:

1. AWS_NO_SIGN_REQUEST=YES 設定オプションが設定されている場合,リクエスト署名が無効になります.このオプションは,パブリックアクセス権を持つバケットに使用できます. GDAL 2.3以降で利用可能です.

2. AWS_SECRET_ACCESS_KEY および AWS_ACCESS_KEY_ID 設定オプションを設定できます.一時的な資格情報が使用される場合は, AWS_SESSION_TOKEN 設定オプションを設定する必要があります.

3. GDAL 2.3以降, "aws"コマンドラインユーティリティやBoto3がサポートするのと同様の資格情報を提供する代替方法を使用できます.上記の環境変数が提供されていない場合, ~/.aws/credentials または %UserProfile%/.aws/credentials ファイルが読み込まれます(CPL_AWS_CREDENTIALS_FILE で指定されたファイル).プロファイルは, AWS_DEFAULT_PROFILE 環境変数で指定するか, GDAL 3.2以降では AWS_PROFILE 環境変数で指定することができます(デフォルトプロファイルは "default" です).

4. 資格情報とAWSリージョンを取得するために.``~/.aws/config`` または %UserProfile%/.aws/config ファイルも使用できます(AWS_CONFIG_FILE で指定されたファイル)

5. GDAL 3.6以降, AWS_ROLE_ARN および AWS_WEB_IDENTITY_TOKEN_FILE が定義されている場合,webアイデンティティトークンベースのAWS STSアクションAssumeRoleWithWebIdentityに対する資格情報メカニズムに依存します(参照.: https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html)

6. 上記のいずれの方法も成功しない場合,EC2インスタンスでGDALが使用されるときにインスタンスプロファイル資格情報が取得されます(cf /vsis3/ とAWSインスタンスメタデータサービス(IMDS))

書き込み時には,S3マルチパートアップロードAPIを使用してファイルがアップロードされます.チャンクのサイズはデフォルトで50 MBに設定されており,50 MBずつの10000パーツで500 GBまでのファイルを作成できます.より大きなファイルが必要な場合は, VSIS3_CHUNK_SIZE 設定オプションの値を大きな値に増やします(MBで表されます).プロセスが終了し,ファイルが正しく閉じられない場合,マルチパートアップロードは開いたままになり,Amazonはパーツストレージの料金を請求します.他の手段で自分で中止する必要があります.たとえば,s3cmdユーティリティを使用して"ghost"アップロードを中止します.チャンクサイズより小さいファイルの場合,マルチパートアップロードAPIの代わりに単純なPUTリクエストが使用されます.

GDAL 3.1以降, VSIRename() 操作がサポートされています(最初に元のファイルをコピーしてから削除します)

GDAL 3.1以降, VSIRmdirRecursive() 操作がサポートされています(バッチ削除メソッドを使用). CPL_VSIS3_USE_BASE_RMDIR_RECURSIVE 設定オプションをYES に設定すると,バッチ削除をサポートしていないS3ライクなAPIを使用する場合に使用できます(GDAL >= 3.2).GDAL 3.6以降,これは GDAL configuration file でパス固有のオプションとして設定できます

CPL_VSIS3_CREATE_DIR_OBJECT 設定オプションを NO に設定すると, VSIMkdir() 操作がスラッシュで終わるディレクトリ名の空のオブジェクトを作成するのを防ぎます.デフォルトでは,GDALはそのようなオブジェクトを作成します.空のディレクトリをモデル化できるためですが,このような空のオブジェクトを想定していないアプリケーションとの互換性問題が発生する可能性があります.

GDAL 3.5以降,IAMロールの仮定を使用するプロファイルが処理されます(参照: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html).このようなプロファイルでは,``role_arn`` および source_profile キーワードが必要です.オプションの external_id,``mfa_serial`` および role_session_name を指定できます. credential_source は現在サポートされていません.

/vsis3/ とAWSインスタンスメタデータサービス(IMDS)

EC2インスタンスでは,GDALはAWS S3の認証トークンを取得するために IMDSv2 プロトコルを優先して使用し,失敗した場合はIMDSv1にフォールバックします.ただし,最近のAmazon Linuxインスタンスでは,IMDSv1にアクセスできなくなっているため,IMDSv2を正しく構成する必要があります(IMDSv1が利用可能であっても,誤って構成されたIMDSv2は認証ステップで遅延を引き起こします).

EC2インスタンス内のDockerインスタンスで実行する場合,インスタンスの追加構成が必要な既知の問題があります.たとえば, ホップリミットを2に増やす必要があります

これを行う方法はいくつかあります.1つの方法は,次のコマンドを実行することです:

aws ec2 modify-instance-metadata-options \
    --instance-id <instance_id> \
    --http-put-response-hop-limit 2 \
    --http-endpoint enabled

別の方法は,AutoScalingGroup LaunchTemplate に HttpPutResponseHopLimit メタデータを設定することです: - https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_InstanceMetadataOptionsRequest.html

別の可能性は,ホストネットワーキングでDockerコンテナを起動することです(--network=host),ただし,これによりコンテナの隔離が破られ,ホストのすべてのポートがコンテナに公開されるため,`セキュリティ上の問題 <https://stackoverflow.com/a/57051970/40785>`__ が発生します.

/vsis3/ のMinioでの設定

次の設定オプションを設定して, Minio Dockerイメージ にアクセスできます

• AWS_VIRTUAL_HOSTING=FALSE

• AWS_HTTPS=NO

• AWS_S3_ENDPOINT="localhost:9000"

• AWS_REGION="us-east-1"

• AWS_SECRET_ACCESS_KEY="your_secret_access_key"

• AWS_ACCESS_KEY_ID="your_access_key"

/vsis3_streaming/ (AWS S3 files: streaming)

/vsis3_streaming/ は,AWS S3バケットで利用可能な(主に非公開の)ファイルのランダム読み取りを可能にするファイルシステムハンドラです.これには,libcurlを利用してGDALがビルドされている必要があります.

認識されるファイル名は, /vsis3_streaming/bucket/key の形式です.ここで, bucket はS3バケットの名前であり,``key`` はS3オブジェクトの"key"であり,サブディレクトリを含む可能性のあるファイル名です.

認証オプションおよび読み取り専用機能は, /vsis3/ と同じです

Added in version 2.1.

/vsigs/ (Google Cloud Storage ファイル)

/vsigs/ は,Google Cloud Storageバケットで利用可能な(主に非公開の)ファイルのランダム読み取りを可能にするファイルシステムハンドラです.これには,libcurlを利用してGDALがビルドされている必要があります.

GDAL 2.3以降,ファイルの順次書き込みも可能です.その場合,シークや読み取り操作は許可されません.したがって,GTiffドライバを使用してGeoTIFFファイルに直接書き込むことはサポートされません.ただし,GDAL 3.2以降, CPL_VSIL_USE_TEMP_FILE_FOR_RANDOM_WRITE 設定オプションを YES に設定すると,ランダム書き込みアクセスが可能になります( CPL_TMPDIR 設定オプションで制御される一時ローカルファイルの作成が含まれます). VSIUnlink() によるファイルの削除, VSIMkdir() によるディレクトリの作成, VSIRmdir() による(空の)ディレクトリの削除も可能です.

認識されるファイル名は, /vsigs/bucket/key の形式です.ここで, bucket はバケットの名前であり,``key`` はオブジェクトの"key"であり,サブディレクトリを含む可能性のあるファイル名です.

/vsicurl/ の一般的な情報が適用されます.

/vsigs/ ハンドラに固有の以下の設定オプションがあります:

• GS_NO_SIGN_REQUEST=[YES​/​NO]: (GDAL >= 3.4) If YES, request signing is disabled.

• GS_SECRET_ACCESS_KEY=value: Secret for AWS-style authentication (HMAC keys).

• GS_ACCESS_KEY_ID=value: Access ID for AWS-style authentication (HMAC keys).

• GS_OAUTH2_REFRESH_TOKEN=value: OAuth2 refresh token. This refresh token can be obtained with the gdal_auth.py script (gdal_auth.py -s storage or gdal_auth.py -s storage-rw).

• GS_OAUTH2_CLIENT_ID=value: Client ID to be used when requesting GS_OAUTH2_REFRESH_TOKEN.

• GS_OAUTH2_CLIENT_SECRET=value: Client secret to be used when requesting GS_OAUTH2_REFRESH_TOKEN.

• GS_OAUTH2_PRIVATE_KEY=value: Private key for OAuth2 authentication. Alternatively, the key may be saved in a file and referenced with GS_OAUTH2_PRIVATE_KEY_FILE.

• GS_OAUTH2_PRIVATE_KEY_FILE=<filename>: Location of private key file for OAuth2 authentication.

• GS_OAUTH2_CLIENT_EMAIL=value: Client email for OAuth2 authentication, to be used with GS_OAUTH2_PRIVATE_KEY or GS_OAUTH2_PRIVATE_KEY_FILE.

• GS_OAUTH2_SCOPE=value: Permission scope associated with OAuth2 authentication using GOOGLE_APPLICATION_CREDENTIALS.

• CPL_GS_CREDENTIALS_FILE=value: Defaults to ~/.boto. Location of configuration file providing gs_secret_access_key and gs_access_key_id.

• GS_USER_PROJECT=value: (GDAL >= 3.4) Google Project id (see https://cloud.google.com/storage/docs/xml-api/reference-headers#xgooguserproject) to charge for requests against Requester Pays buckets.

複数の認証方法が可能であり,以下の順序で試行されます:

1. GS_NO_SIGN_REQUEST=YES 設定オプションが設定されている場合,リクエスト署名が無効になります.このオプションは,パブリックアクセス権を持つバケットに使用できます. GDAL 3.4以降で利用可能です.

2. GS_SECRET_ACCESS_KEY および GS_ACCESS_KEY_ID 設定オプションを設定できます.AWSスタイルの認証に使用できます

3. The GDAL_HTTP_HEADER_FILE configuration option to point to a filename of a text file with "key: value" headers. Typically, it must contain a "Authorization: Bearer XXXXXXXXX" line.

4. (GDAL >= 3.7) GDAL_HTTP_HEADERS 設定オプションも設定できます.少なくとも"Authorization:" で始まる行を含む必要があります.

5. (GDAL >= 2.3) GS_OAUTH2_REFRESH_TOKEN 設定オプションを設定して,OAuth2クライアント認証を使用できます.http://code.google.com/apis/accounts/docs/OAuth2.html このリフレッシュトークンは, gdal_auth.py -s storage または gdal_auth.py -s storage-rw スクリプトで取得できます.注意:デフォルトのGDALアプリケーション資格情報の代わりに, GS_OAUTH2_CLIENT_ID および GS_OAUTH2_CLIENT_SECRET 設定オプションを定義できます(gdal_auth.pyと後続の /vsigs の実行の両方で定義する必要があります)

6. (GDAL >= 2.3) GOOGLE_APPLICATION_CREDENTIALS 設定オプションを設定して,OAuth2サービスアカウント資格情報を含むJSONファイルを指定できます(type: service_account),特にプライベートキーとクライアントメールを指定します.https://developers.google.com/identity/protocols/OAuth2ServiceAccount でこの認証方法の詳細を確認してください.バケットは,サービスアカウントに"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" に変更できます.

7. (GDAL >= 3.4.2) GOOGLE_APPLICATION_CREDENTIALS 設定オプションを設定して,OAuth2ユーザー資格情報を含むJSONファイルを指定できます(type: authorized_user).

8. (GDAL >= 2.3) 前の方法の変種. GS_OAUTH2_PRIVATE_KEY (または GS_OAUTH2_PRIVATE_KEY_FILE および GS_OAUTH2_CLIENT_EMAIL ) を設定して,OAuth2サービスアカウント認証を使用できます.この認証方法の詳細については,https://developers.google.com/identity/protocols/OAuth2ServiceAccount を参照してください. GS_OAUTH2_PRIVATE_KEY 設定オプションには, -----BEGIN PRIVATE KEY----- で始まるプライベートキーをインライン文字列として含める必要があります.代替として, GS_OAUTH2_PRIVATE_KEY_FILE 設定オプションを設定して,そのようなプライベートキーを含むファイル名を示すことができます.バケットは,サービスアカウントに"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" に変更できます.

9. (GDAL >= 2.3) "gsutil" コマンドラインユーティリティやBoto3サポートで使用されるのと同様の資格情報を提供する別の方法が使用できます.上記の環境変数が提供されていない場合,gs_secret_access_key および gs_access_key_id エントリをAWSスタイルの認証に使用するために,:file:~/.boto または UserProfile%/.boto ファイルが読み込まれます(CPL_GS_CREDENTIALS_FILE で指定されたファイル).見つからない場合,OAuth2クライアント認証のための gs_oauth2_refresh_token (およびオプションで client_id および client_secret) エントリを探します.

10. (GDAL >= 2.3) 最後に,上記のいずれの方法も成功しない場合,コードは現在のマシンがGoogle Compute Engineインスタンスであるかどうかを確認し,そうであればそれに関連付けられた権限を使用します(VMに関連付けられたデフォルトのサービスアカウントを使用します).マシンをGCEインスタンスとして検出するように強制するには(たとえば,ブートログにアクセスできないコンテナで実行されるコードの場合), CPL_MACHINE_IS_GCE を YES に設定できます.

GDAL 3.1以降, Rename() 操作がサポートされています(最初に元のファイルをコピーしてから削除します).

Added in version 2.2.

/vsigs_streaming/ (Google Cloud Storage ファイル: ストリーミング)

/vsigs_streaming/ は,Google Cloud Storageバケットで利用可能な(主に非公開の)ファイルのランダム読み取りを可能にするファイルシステムハンドラです.これには,libcurlを利用してGDALがビルドされている必要があります.

認識されるファイル名は, /vsigs_streaming/bucket/key の形式です.ここで, bucket はバケットの名前であり,``key`` はオブジェクトの"key"であり,サブディレクトリを含む可能性のあるファイル名です.

認証オプションおよび読み取り専用機能は, /vsigs/ と同じです

Added in version 2.2.

/vsiaz/ (Microsoft Azure Blob ファイル)

/vsiaz/ は,Microsoft Azure Blobコンテナで利用可能な(主に非公開の)ファイルのランダム読み取りを可能にするファイルシステムハンドラです.これには,libcurlを利用してGDALがビルドされている必要があります.

Azure Data Lake Storage Gen2 用の関連ファイルシステムについては, /vsiadls/ を参照してください.

ファイルの順次書き込みも可能です.その場合,シークや読み取り操作は許可されません.したがって,GTiffドライバを使用してGeoTIFFファイルに直接書き込むことはサポートされません.ただし,GDAL 3.2以降, CPL_VSIL_USE_TEMP_FILE_FOR_RANDOM_WRITE 設定オプションを YES に設定すると,ランダム書き込みアクセスが可能になります( CPL_TMPDIR 設定オプションで制御される一時ローカルファイルの作成が含まれます).ファイルサイズが4 MB未満の場合,ブロック ブロブが作成されます.それを超えると,追加ブロブが作成されます(最大ファイルサイズは195 GBです).

Deletion of files with VSIUnlink(), creation of directories with VSIMkdir() and deletion of (empty) directories with VSIRmdir() are also possible. Note: when using VSIMkdir(), a special hidden .gdal_marker_for_dir empty file is created, since Azure Blob does not natively support empty directories. If that file is the last one remaining in a directory, VSIRmdir() will automatically remove it. This file will not be seen with VSIReadDir(). If removing files from directories not created with VSIMkdir(), when the last file is deleted, its directory is automatically removed by Azure, so the sequence VSIUnlink("/vsiaz/container/subdir/lastfile") followed by VSIRmdir("/vsiaz/container/subdir") will fail on the VSIRmdir() invocation.

認識されるファイル名は, /vsiaz/container/key の形式です.ここで, container はコンテナの名前であり,``key`` はオブジェクトの"key"であり,サブディレクトリを含む可能性のあるファイル名です.

/vsicurl/ の一般的な情報が適用されます.

/vsiaz/ ハンドラに固有の以下の設定オプションがあります:

• AZURE_NO_SIGN_REQUEST=[YES​/​NO]: (GDAL >= 3.2) Controls whether requests are signed.

• AZURE_STORAGE_CONNECTION_STRING=value: Credential string provided in the Access Key section of the administrative interface, containing both the account name and a secret key.

• AZURE_STORAGE_ACCESS_TOKEN=value: (GDAL >= 3.5) Access token typically obtained using Microsoft Authentication Library (MSAL).

• AZURE_STORAGE_ACCOUNT=value: Specifies storage account name.

• AZURE_STORAGE_ACCESS_KEY=value: Specifies secret key associated with AZURE_STORAGE_ACCOUNT.

• AZURE_STORAGE_SAS_TOKEN=value: (GDAL >= 3.2) Shared Access Signature.

• AZURE_IMDS_OBJECT_ID=value: (GDAL >= 3.8) object_id of the managed identity you would like the token for, when using Azure Instance Metadata Service (IMDS) authentication in a Azure Virtual Matchine. Required if your VM has multiple user-assigned managed identities. This option may be set as a path-specific option with VSISetPathSpecificOption()

• AZURE_IMDS_CLIENT_ID=value: (GDAL >= 3.8) client_id of the managed identity you would like the token for, when using Azure Instance Metadata Service (IMDS) authentication in a Azure Virtual Matchine. Required if your VM has multiple user-assigned managed identities. This option may be set as a path-specific option with VSISetPathSpecificOption()

• AZURE_IMDS_MSI_RES_ID=value: (GDAL >= 3.8) msi_res_id (Azure Resource ID) of the managed identity you would like the token for, when using Azure Instance Metadata Service (IMDS) authentication in a Azure Virtual Matchine. Required if your VM has multiple user-assigned managed identities. This option may be set as a path-specific option with VSISetPathSpecificOption()

複数の認証方法が可能であり,以下の順序で試行されます:

1. The AZURE_STORAGE_CONNECTION_STRING configuration option

2. The AZURE_STORAGE_ACCOUNT configuration option is set to specify the account name AND

   1. (GDAL >= 3.5) AZURE_STORAGE_ACCESS_TOKEN 設定オプションを設定して,アクセストークンを指定します.このアクセストークンは,通常,Microsoft Authentication Library (MSAL) を使用して取得されます.このアクセストークンは,"Authorization: Bearer ${AZURE_STORAGE_ACCESS_TOKEN}" ヘッダーに含まれます.

   2. The AZURE_STORAGE_ACCESS_KEY configuration option is set to specify the secret key.

   3. AZURE_NO_SIGN_REQUEST=YES 設定オプションを設定して,リクエスト署名を無効にします.このオプションは,パブリックアクセス権を持つアカウントに使用できます. GDAL 3.2以降で利用可能です.

   4. AZURE_STORAGE_SAS_TOKEN 設定オプション(AZURE_SAS は GDAL < 3.5 の場合) を設定して,共有アクセス署名を指定します.このSASは /vsiaz/ ファイルシステムハンドラによって構築されたURLに追加されます.その値はすでにURLエンコードされている必要があり,先頭に '?' または '&' 文字を含めてはいけません(たとえば,有効なものは "st=2019-07-18T03%3A53%3A22Z&se=2035-07-19T03%3A53%3A00Z&sp=rl&sv=2018-03-28&sr=c&sig=2RIXmLbLbiagYnUd49rgx2kOXKyILrJOgafmkODhRAQ%3D" のようになります).GDAL 3.2以降で利用可能です.

   5. 現在のマシンは,それに割り当てられたAzure Active Directory権限を持つAzure仮想マシンです(https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/qs-configure-portal-windows-vm を参照してください). GDAL 3.3以降で利用可能です.

   Azure Active Directory Workload Identity を使用した認証(AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_FEDERATED_TOKEN_FILE および AZURE_AUTHORITY_HOST 環境変数を使用)は,通常,Azure Kubernetes 用に利用できます. GDAL 3.7.2以降で利用可能です.

3. GDAL 3.5以降, "az" コマンドラインユーティリティの 設定ファイル <https://github.com/MicrosoftDocs/azure-docs-cli/blob/main/docs-ref-conceptual/azure-cli-configuration.md> を使用できます. [storage] セクションの次のキーが次の優先順位で使用されます:connection_string, account + key または account + sas_token

GDAL 3.1以降, VSIRename() 操作がサポートされています(最初に元のファイルをコピーしてから削除します)

GDAL 3.3以降, VSIGetFileMetadata() および VSISetFileMetadata() 操作がサポートされています.

Added in version 2.3.

/vsiaz_streaming/ (Microsoft Azure Blob ファイル: ストリーミング)

/vsiaz_streaming/ は,Microsoft Azure Blobコンテナ,バケットで利用可能な(主に非公開の)ファイルのランダム読み取りを可能にするファイルシステムハンドラです.これには,libcurlを利用してGDALがビルドされている必要があります.

認識されるファイル名は, /vsiaz_streaming/container/key の形式です.ここで, container はコンテナの名前であり,``key`` はオブジェクトの"key"であり,サブディレクトリを含む可能性のあるファイル名です.

認証オプションおよび読み取り専用機能は, /vsiaz/ と同じです

Added in version 2.3.

/vsiadls/ (Microsoft Azure Data Lake Storage Gen2)

/vsiadls/ は,Microsoft Azure Data Lake Storageファイルシステムで利用可能な(主に非公開の)ファイルのランダム読み取りを可能にするファイルシステムハンドラです.これには,libcurlを利用してGDALがビルドされている必要があります.

/vsiaz/ と同様の機能を持ち,特に認証のために同じ設定オプションを使用します./vsiaz/ に対する利点は,ディレクトリの実際の管理とUnixスタイルのACLサポートです.一部の機能には,Azureストレージで階層サポートをオンにする必要があります.その ドキュメント を参照してください.

/vsiaz/ に対する主な強化点は次のとおりです:

• 本当のディレクトリサポート(空のディレクトリを持つために /vsiaz/ で使用される人工的な .gdal_marker_for_dir 空ファイルは不要です)

• One-call recursive directory deletion with VSIRmdirRecursive()

• Atomic renaming with VSIRename()

• VSIGetFileMetadata() で "STATUS" および "ACL" メタデータドメインをサポート

• VSISetFileMetadata() で "PROPERTIES" および "ACL" メタデータドメインをサポート

Added in version 3.3.

/vsioss/ (Alibaba Cloud OSS ファイル)

/vsioss/ は,Alibaba Cloud Object Storage Service (OSS) バケットで利用可能な(主に非公開の)ファイルのランダム読み取りを可能にするファイルシステムハンドラです.これには,libcurlを利用してGDALがビルドされている必要があります.

ファイルの順次書き込みも可能です.その場合,シークや読み取り操作は許可されません.したがって,GTiffドライバを使用してGeoTIFFファイルに直接書き込むことはサポートされません.ただし,GDAL 3.2以降, CPL_VSIL_USE_TEMP_FILE_FOR_RANDOM_WRITE 設定オプションを YES に設定すると,ランダム書き込みアクセスが可能になります( CPL_TMPDIR 設定オプションで制御される一時ローカルファイルの作成が含まれます).ファイルの削除は VSIUnlink() でもサポートされます.ディレクトリの作成は VSIMkdir() で,(空の)ディレクトリの削除は VSIRmdir() でも可能です.

認識されるファイル名は, /vsioss/bucket/key の形式です.ここで, bucket はOSSバケットの名前であり,``key`` はOSSオブジェクトの"key"であり,サブディレクトリを含む可能性のあるファイル名です.

/vsicurl/ の一般的な情報が適用されます.

/vsioss/ ハンドラに固有の以下の設定オプションがあります:

• OSS_SECRET_ACCESS_KEY=value: (required) Secret access key for authentication.

• OSS_ACCESS_KEY_ID=value: (required) Access key ID for authentication.

• OSS_ENDPOINT=value: Defaults to oss-us-east-1.aliyuncs.com. Endpoint URL containing the region associated with the bucket.

• VSIOSS_CHUNK_SIZE=<MB>: Defaults to 50. Chunk size used with multipart upload API.

The OSS_SECRET_ACCESS_KEY and OSS_ACCESS_KEY_ID configuration options must be set. The OSS_ENDPOINT configuration option should normally be set to the appropriate value, which reflects the region attached to the bucket. If the bucket is stored in another region than oss-us-east-1, the code logic will redirect to the appropriate endpoint.

書き込み時には,OSSマルチパートアップロードAPIを使用してファイルがアップロードされます.チャンクのサイズはデフォルトで50 MBに設定されており,50 MBずつの10000パーツで500 GBまでのファイルを作成できます.より大きなファイルが必要な場合は, VSIOSS_CHUNK_SIZE 設定オプションの値を大きな値に増やします(MBで表されます).プロセスが終了し,ファイルが正しく閉じられない場合,マルチパートアップロードは開いたままになり,Alibabaがパーツストレージの料金を請求します.他の手段で自分で中止する必要があります.チャンクサイズより小さいファイルの場合,マルチパートアップロードAPIの代わりに単純なPUTリクエストが使用されます.

Added in version 2.3.

/vsioss_streaming/ (Alibaba Cloud OSS ファイル: ストリーミング)

/vsioss_streaming/ は,Alibaba Cloud Object Storage Service (OSS) バケットで利用可能な(主に非公開の)ファイルのランダム読み取りを可能にするファイルシステムハンドラです.これには,libcurlを利用してGDALがビルドされている必要があります.

認識されるファイル名は, /vsioss_streaming/bucket/key の形式です.ここで, bucket はバケットの名前であり,``key`` はオブジェクトの"key"であり,サブディレクトリを含む可能性のあるファイル名です.

認証オプションおよび読み取り専用機能は, /vsioss/ と同じです

Added in version 2.3.

/vsiswift/ (OpenStack Swift Object Storage)

/vsiswift/ は,OpenStack Swift Object Storage (swift) バケットで利用可能な(主に非公開の)ファイルのランダム読み取りを可能にするファイルシステムハンドラです.これには,libcurlを利用してGDALがビルドされている必要があります.

ファイルの順次書き込みも可能です.その場合,シークや読み取り操作は許可されません.したがって,GTiffドライバを使用してGeoTIFFファイルに直接書き込むことはサポートされません.ただし,GDAL 3.2以降, CPL_VSIL_USE_TEMP_FILE_FOR_RANDOM_WRITE 設定オプションを YES に設定すると,ランダム書き込みアクセスが可能になります( CPL_TMPDIR 設定オプションで制御される一時ローカルファイルの作成が含まれます).ファイルの削除は VSIUnlink() でもサポートされます.ディレクトリの作成は VSIMkdir() で,(空の)ディレクトリの削除は VSIRmdir() でも可能です.

認識されるファイル名は, /vsiswift/bucket/key の形式です.ここで, bucket はswiftバケットの名前であり,``key`` はswiftオブジェクトの"key"であり,サブディレクトリを含む可能性のあるファイル名です.

/vsicurl/ の一般的な情報が適用されます.

/vsioss/ ハンドラに固有の以下の設定オプションがあります:

• SWIFT_STORAGE_URL=value: Storage URL.

• SWIFT_AUTH_TOKEN=value: Value of the x-auth-token authorization

• SWIFT_AUTH_V1_URL=value: URL for Auth V1 authentication.

• SWIFT_USER=value: User name for Auth V1 authentication.

• SWIFT_KEY=value: Key for Auth V1 authentication.

3つの認証方法が可能であり,以下の順序で試行されます:

1. The SWIFT_STORAGE_URL and SWIFT_AUTH_TOKEN configuration options are set respectively to the storage URL (e.g http://127.0.0.1:12345/v1/AUTH_something) and the value of the x-auth-token authorization token.

2. SWIFT_AUTH_V1_URL, SWIFT_USER および SWIFT_KEY 設定オプションは,それぞれ,Auth V1認証のエンドポイント(e.g 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#authentication を参照してください.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. Keystone v3 を介したアプリケーション資格情報認証, GDAL (>= 3.3.1) は,以下のオプションを使用してアプリケーション資格情報認証をサポートしています:

   • 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-upload を参照してください).大きなオブジェクトについての詳細は,https://docs.openstack.org/swift/latest/api/large_objects.html を参照してください.

Added in version 2.3.

/vsiswift_streaming/ (OpenStack Swift Object Storage: ストリーミング)

/vsiswift_streaming/ は,OpenStack Swift Object Storage (swift) バケットで利用可能な(主に非公開の)ファイルのランダム読み取りを可能にするファイルシステムハンドラです.これには,libcurlを利用してGDALがビルドされている必要があります.

認識されるファイル名は, /vsiswift_streaming/bucket/key の形式です.ここで, bucket はバケットの名前であり,``key`` はオブジェクトの"key"であり,サブディレクトリを含む可能性のあるファイル名です.

認証オプションおよび読み取り専用機能は, /vsiswift/ と同じです

Added in version 2.3.

/vsihdfs/ (Hadoop ファイルシステム)

/vsihdfs/ は,HDFSへの読み取りアクセスを提供するファイルシステムハンドラです.このハンドラは,Javaサポートを持つGDALでビルドされていることを必要とします(CMake FindJNI) および HDFS サポート.このハンドラのサポートは現在,Unix系システムのみで利用可能です.

注: HTTP REST API (webHdfs) のサポートも /vsiwebhdfs/ (Web Hadoop ファイルシステム REST API) で利用可能です

通常,LD_LIBRARY_PATH および CLASSPATH 環境変数は以下のように設定する必要があります.

HADOOP_HOME=$HOME/hadoop-3.3.5
LD_LIBRARY_PATH=$HADOOP_HOME/lib/native:$LD_LIBRARY_PATH
CLASSPATH=$HADOOP_HOME/etc/hadoop:$HADOOP_HOME/share/hadoop/common/*:$HADOOP_HOME/share/hadoop/common/lib/*:$HADOOP_HOME/share/hadoop/hdfs/*

CLASSPATH を適切に定義しないと,ネイティブ libhdfs でハードクラッシュが発生します.

関連するHadoopドキュメントリンク:

• C API libhdfs

• HDFS Users Guide

• Hadoop: Setting up a Single Node Cluster

認識されるファイル名は, /vsihdfs/hdfsUri の形式です.ここで, hdfsUri は有効な HDFS URI です.

例:

/vsihdfs/file:/home/user//my.tif  (a local file accessed through HDFS)
/vsihdfs/hdfs://localhost:9000/my.tif  (a file stored in HDFS)

Added in version 2.4.

/vsiwebhdfs/ (Web Hadoop ファイルシステム REST API)

/vsiwebhdfs/ は,HDFSへの読み取りおよび書き込みアクセスを提供するファイルシステムハンドラです.これは,HDFSのHTTP REST APIを介して行われます.

認識されるファイル名は, /vsiwebhdfs/http://hostname:port/webhdfs/v1/path/to/filename の形式です.

例:

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

ファイルの順次書き込みも可能です.その場合,シークや読み取り操作は許可されません.したがって,GTiffドライバを使用してGeoTIFFファイルに直接書き込むことはサポートされません.ただし,GDAL 3.2以降, CPL_VSIL_USE_TEMP_FILE_FOR_RANDOM_WRITE 設定オプションを YES に設定すると,ランダム書き込みアクセスが可能になります( CPL_TMPDIR 設定オプションで制御される一時ローカルファイルの作成が含まれます).ファイルの削除は VSIUnlink() でもサポートされます.ディレクトリの作成は VSIMkdir() で,(空の)ディレクトリの削除は VSIRmdir() でも可能です.

/vsicurl/ の一般的な情報が適用されます.

以下の設定オプションが利用可能です:

• WEBHDFS_USERNAME=value: User name (when security is off).

• WEBHDFS_DELEGATION=value: Hadoop delegation token (when security is on).

• WEBHDFS_DATANODE_HOST=value: For APIs using redirect, substitute the redirection hostname with the one provided by this option (normally resolvable hostname should be rewritten by a proxy)

• WEBHDFS_REPLICATION=<integer>: Replication value used when creating a file

• WEBHDFS_PERMISSION=<integer>: Permission mask (to provide as decimal number) when creating a file or directory

このファイルシステムハンドラは,ファイルの順次書き込みも可能です(その場合,シークや読み取り操作は許可されません)

Added in version 2.4.

/vsistdin/ (標準入力ストリーミング)

/vsistdin/ は,標準入力ストリームから読み取りを可能にするファイルハンドラです.

ファイル名構文は /vsistdin/ のみである必要があります(例えば, /vsistdin/path/to/f.csv ではなく, "/vsistdin?buffer_limit=value" はOKです.)

利用可能なファイル操作は,もちろん Read() および forward Seek() に制限されます.ファイルの最初の1MBでの完全なシークが可能であり,これはキャッシュされているため, /vsistdin/ を閉じて再度開き,同じプロセス内でこの最初の1MB内での読み取りが複数回可能です.

インメモリキャッシュのサイズは, CPL_VSISTDIN_BUFFER_LIMIT 設定オプションで制御できます:

• CPL_VSISTDIN_BUFFER_LIMIT=value: (GDAL >= 3.6) Defaults to 1MB. Specifies the size of the /vsistdin in bytes (or using a MB or GB suffix, e.g. "1GB"), or -1 for unlimited.

The "/vsistdin?buffer_limit=value" syntax can also be used.

/vsistdin ファイル名は他のファイルシステムと組み合わせることができます.例えば,潜在的に大きなZIPファイルをgdal_translateにストリーミングするためにファイルを読み取るには:

cat file.tif.zip | gdal_translate /vsizip/{/vsistdin?buffer_limit=-1}/path/to/some.tif out.tif

/vsistdout/ (標準出力ストリーミング)

/vsistdout/ は,標準出力ストリームへの書き込みを可能にするファイルハンドラです.

ファイル名構文は /vsistdout/ のみである必要があります.

利用可能なファイル操作は,もちろん Write() に制限されます.

このファイルシステムの変種として,出力関数を VSIStdoutSetRedirection() で定義できる /vsistdout_redirect/ ファイルシステムハンドラが存在します.

/vsimem/ (インメモリファイル)

/vsimem/ は,メモリブロックをファイルとして扱うことを可能にするファイルハンドラです.:file:/vsimem/ ベースパスの下のファイルシステムのすべての部分は,このドライバによって処理されます.

通常の VSI*L 関数を自由に使用して,メモリ配列を作成および破棄し,それらを実際のファイルシステムオブジェクトであるかのように扱うことができます.元のデータのコピーを複製せずに効率的にメモリファイルシステムオブジェクトを作成するためのいくつかの追加メソッドが存在し,またはメモリファイルに関連付けられたメモリブロックを"盗む"ためのメソッドが存在します. VSIFileFromMemBuffer() および VSIGetMemFileBuffer() を参照してください.

ディレクトリ関連の関数がサポートされています.

/vsimem/ ファイルは同じプロセス内で見えます.複数のスレッドが同じ基礎ファイルにアクセスできますが,異なるハンドルを使用している場合に限り,読み取りモードで同じ基礎ファイルに対して同時書き込みおよび読み取り操作はサポートされません(ロックは呼び出しコードの責任に任されます).

/vsisubfile/ (ファイルの一部)

/vsisubfile/ バーチャルファイルシステムハンドラは,ファイルのサブリージョンにアクセスし,それらを仮想ファイルシステム関数(VSIFOpenL() など)に独自のファイルとして扱うことを可能にします.

他のファイルのサブポーションを示すために特別なファイル名の形式が使用されます: /vsisubfile/<offset>[_<size>],<filename>.

サイズパラメータはオプションです.サイズパラメータがない場合,開始オフセットからのファイルの残りはサブファイルの一部として扱われます.それ以外の場合, <offset> から <size> バイトのみがサブファイルの一部として扱われます. <filename> 部分は通常のルールを使用して相対パスまたは絶対パスにすることができます.<offset> および <size> の値はバイト単位です.

例:

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

/vsimem/ や従来のファイルシステムハンドラとは異なり,新しいファイルの作成,ディレクトリのトラバース,および/vsisubfile/ エリア内のファイルの削除に対するファイルシステム操作の意味のあるサポートはありません. VSIStatL(), VSIFOpenL() および VSIFOpenL() によって返されるファイルハンドルに基づく操作のみが正常に動作します.

/vsisparse/ (スパースファイル)

/vsisparse/ バーチャルファイルハンドラは,他のファイルのデータチャンクから仮想ファイルを構成することを可能にします.仮想ファイルには,大きなスペースが一定の値に設定されている可能性があります.これにより,画像データが一定の値に設定された大きなファイルのように見えるファイル上でいくつかの操作をテストすることが可能になります.また,テストスイートに追加するテストファイルが大きすぎる場合や,データの大部分を無視できる場合にも便利です.理論的には,異なるファイルシステム上の複数のファイルを1つの大きな仮想ファイルとして扱うためにも使用できます.

/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>

値と意味がかなり明らかであることを願っています.

/vsicached/ (ファイルキャッシュ)

VSICreateCachedFile() 関数は,仮想ファイルハンドルを取得し,入力ファイルハンドル上の読み取り操作をキャッシュする新しいハンドルを返します.キャッシュはRAMベースであり,ファイルハンドルが閉じられるとキャッシュの内容が破棄されます.キャッシュは,32KBごとのブロックの最近使用されたリストです(デフォルトサイズ).

これは,遅いローカル/オペレーティングシステムマウントされたファイルシステムを介してアクセス可能なファイルに対して主に有用です.

これは,上記で言及されたファイルシステムのいくつか(標準ファイルシステム操作のデフォルトのものと, /vsicurl/ および他の関連するネットワークファイルシステム)で, VSI_CACHE 設定オプションが YES に設定されている場合に暗黙的に使用されます.

各ファイルのキャッシュのデフォルトサイズは25 MBです(キャッシュされる各ファイルに対して25 MB), および VSI_CACHE_SIZE 設定オプション(バイト単位の値)で制御できます.

The VSICachedFile class only handles read operations at that time, and will error out on write operations.

GDAL 3.8 から,特定のファイルをキャッシュするための /vsicached? バーチャルファイルシステムも存在します.

構文は次のようになります: /vsicached?[option_i=val_i&]*file=<filename> ここで,各オプション名と値( file の値を含む)がURLエンコードされています(実際には,アンパサンド文字に対してのみ必要です.スラッシュ文字をエンコード解除することが望ましいかもしれません). file オプションが最後に表示されるようにすることが重要です.これにより,サイドカーファイルを探そうとするコードや,ディレクトリコンテンツをリストアップしようとするコードが正常に動作します.

現在サポートされているオプションは次のとおりです:

• chunk_size=<value> where value is the` size of the chunk size in bytes. KB or MB suffixes can be also appended (without space after the numeric value). The maximum supported value is 1 GB.

• cache_size=<value> where value is the size of the cache size in bytes, for each file. KB or MB suffixes can be also appended.

例:

• /vsicached?chunk_size=1MB&file=/home/even/byte.tif

• /vsicached?file=./byte.tif

/vsicrypt/ (暗号化ファイル)

/vsicrypt/ は,ランダムアクセス機能を備えた暗号化ファイルの読み取り/作成/更新を可能にする特別なファイルハンドラがインストールされています.

Refer to VSIInstallCryptFileHandler() for more details.