ディレクトリツリー
デプロイエージェントやCIジョブは、ディレクトリ全体を必要とすることがよくあります。ゲームのビルド、ツール一式、設定のツリーなどです。arkvoryctl treeは、ディレクトリを1つのZIPアーティファクトとして公開し、それをフォルダーに取得し、フォルダーをそれと照合し、異なるファイルだけを修復します。アーティファクトは通常のZIPファイルです。コンソール、API、任意のZIPツールで読むことができ、バックアップでもほかのアーティファクトと同じように保存されます。
これらのコマンドは無料のコアに含まれます。必要な権限はアップロードとダウンロードと同じです。アップロードとダウンロードを参照してください。
ディレクトリを公開する
arkvoryctl tree push ./Build/Game --name game-1.4.zip --label release| オプション | 意味 |
|---|---|
--name NAME.zip | アーティファクトの名前。既定はフォルダー名に.zipを付けたものです。名前は.zipで終わる必要があります。 |
--label TAG | アーティファクトのラベル |
--file METADATA.json | ラベルとメタデータ（uploadと同じ） |
--compress | エントリを圧縮します（deflate）。指定しない場合、ファイルはそのまま格納されます。 |
結果には、アーティファクトのid、size、sha256と、entriesにファイル数が表示されます。
- 同じフォルダーからは同じアーカイブができます。 ファイルはパス順に並び、すべてのエントリの日付は1980-01-01になり、ファイルシステムの属性は1つだけ保持されます。所有者が実行できるファイルはモード755、それ以外のファイルは644になります。変更していないフォルダーをもう一度pushすると、同じバイト列と同じSHA-256になります。
- 中断。 アーカイブはフォルダーの隣（
.<folder>.arkvory-tree.zip）に作成され、チェックポイント付きでパートごとにアップロードされます。Ctrl+Cやネットワーク障害の後は、同じコマンドをもう一度実行してください。同じアーカイブを作成し、アップロードを再開します。成功後、両方のファイルは削除されます。 - 拒否されるもの。 フォルダー内のシンボリックリンク、ジャンクション、デバイス、パイプ（
tree_entry_unsupported）、Windowsで使えない名前（unsafe_name）、大文字と小文字だけが異なる2つの名前（case_collision）。空のフォルダーは保持されません。 - 格納か圧縮か。
--compressを指定しない場合、各ファイルのバイト列はアーカイブ内の連続した範囲になります。そのためサーバーは1つのファイルをバイト範囲で提供でき、修復では異なるファイルのバイト列だけが転送されます。--compressを指定するとアーカイブは小さくなり、修復するファイルはお使いのマシン上で展開されます。
ディレクトリを取得する
arkvoryctl tree pull 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11 ./Game- 空のフォルダーまたは存在しないフォルダーには、アーカイブ全体が取得されます。アーカイブはチェックポイント付きでフォルダーの隣にダウンロードされるため、中断したpullは止まったところから再開します。SHA-256の検証後、ファイルは対象の隣の新しいフォルダーに展開され、そのフォルダーが対象と置き換わります。
- ファイルのあるフォルダーは、ツリーと同じ内容になります。サーバーに目次がある場合、異なるファイルだけがそれぞれのバイト範囲でダウンロードされ、ツリーにないファイルは削除されます。目次がない場合はアーカイブ全体がダウンロードされ、展開したフォルダーが古いフォルダーと置き換わります。
親フォルダーは存在している必要があります。対象内のファイルは1回の操作で置き換えられます。隣の一時ファイルに書き込み、検証してから名前を変更します。ファイルを読むプログラムには、古いバージョンか新しいバージョンのどちらかが見えます。
ディレクトリを照合する
arkvoryctl tree verify 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11 ./Game結果には、missing（欠けている）ファイル、mismatched（サイズまたはSHA-256が異なる）ファイル、ツリーにないextra（余分な）ファイルが一覧され、それぞれの数がcountsに入ります。各一覧に表示されるパスは最大1000個です。欠けているファイルと異なるファイルがなければokはtrueです。余分なファイルは影響しません。終了コードは、okがtrueなら0、それ以外は5です。
ディレクトリを修復する
arkvoryctl tree repair 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11 ./Game修復は、欠けているファイルと異なるファイルをすべて書き直し、余分なファイルは残します。目次がある場合は、それらのファイルのエントリだけをダウンロードします。結果のfetchedBytesは、アーカイブから読み取ったバイト数を示します。目次がない場合は、最初にアーカイブ全体をダウンロードします。
目次
アーカイブが公開されると、サーバーのワーカーがそれを1回読み取り、各ファイルのパス、サイズ、SHA-256、アーカイブ内でのバイト列の位置を記録します。対象は、名前が.zipまたは.upackで終わるアーティファクトです。これが終わるまで、またはアーカイブにインデックスを作成できない場合、コマンドは代わりにアーカイブ全体を使います。
目次を持つサーバーは、GET /api/v1/capabilitiesのtreeでzip-treeを提供します（arkvoryctl doctorを参照）。古いサーバーでは、コマンドはアーカイブ全体を使います。目次そのものは操作getArtifactTreeです。statusはready、pending、またはreason付きのunavailableです。
reason | 意味 |
|---|---|
not_archive | アーティファクトの名前が.zipまたは.upackで終わっていない |
invalid_archive | ファイルが読み取り可能なZIPアーカイブではない |
unsafe_entry | パスがアーカイブの外を指している、またはエントリがリンクか特殊ファイルである |
encrypted_entry | エントリが暗号化されている |
duplicate_entry | 2つのエントリのパスが同じ（大文字と小文字を区別しない場合も含む） |
unsupported_method | エントリがstoredとdeflate以外の圧縮方式を使っている |
crc_mismatch | エントリのバイト列が、アーカイブ内のチェックサムと一致しない |
too_many_entries | エントリが100,000個を超える |
too_large | 展開後のサイズが100 GiBを超える |
ファイルの検証方法
- すべてのファイルは、配置される前に検証されます。 目次がある場合、サイズとSHA-256は、公開されたアーカイブからサーバーが計算した値と一致する必要があります。目次がない場合は、まずアーカイブ全体のSHA-256を検証し、次に各ファイルのサイズとCRC-32を検証します。一致しないとコマンドは
checksum_mismatch（終了コード5）で停止し、フォルダー内のファイルは元のまま残ります。 - フォルダーの外には何も書き込みません。 アーカイブとサーバーから読み取ったパスは、信頼できないデータとして扱われます。フォルダーの外を指すパスは
path_outside_rootで拒否されます。ファイルへの経路上にあるフォルダー内のリンクをたどることはありません。Windowsで使えない名前（CON、aux.txt、a:b、末尾のドットや空白）は、どのシステムでもunsafe_nameで拒否されます。そのため、ツリーはWindowsでもLinuxでも同じ意味になります。 - モード。 アーカイブから展開したファイルは、アーカイブで実行可能とされていればモード755、それ以外は644になります（LinuxとmacOS）。範囲で修復したファイルは、置き換え前のファイルのモードを引き継ぎます。
より高速な転送
tree pushのアーカイブ全体のアップロードとtree pullのアーカイブ全体のダウンロードは、uploadやdownloadと同じ転送を使います。サーバーが同じ拡張を提供している場合は、転送拡張を持つクライアントモジュールがこれらを担うことができます。アーカイブは通常のZIPのままで、そのSHA-256とすべてのファイルは上記のとおり検証されます。モジュールがない場合、またはサーバーが拡張を提供していない場合、arkvoryctlは独自の転送を使います。