Arkvory

クライアントとプロトコル ​

Arkvoryのストレージとアクセスモデルは1つですが、そこに到達する方法は複数あります。それぞれの方法は、ツールがすでに対応しているクライアントまたはプロトコルです。どの方法でも、データはArkvoryのアーティファクトとして保存されます。そのため、どの方法を使っても、同じ権限、クォータ、SHA-256検証、保持ルール、バックアップ、ミラーが適用されます。

このページでは、Arkvoryと通信するすべての方法について、それぞれの用途と、受け付ける認証情報を説明します。作業に適したツールを選ぶときに使ってください。

概要 ​

方法アドレス用途認証情報
Webコンソールhttps://arkvory.example/console/ブラウザーでのリポジトリの閲覧、アップロードとダウンロード、ユーザー、キー、バックアップの管理ユーザー名とパスワードによるサインイン、またはサービスキー
arkvoryctlコマンドライン/api/v1CIスクリプト、再開可能なアップロードとダウンロード、パス指定ファイル、プロモーション、バックアップファイルまたは環境変数から読み込むキー（Bearerとして送信）
TypeScript SDK/api/v1TypeScriptまたはJavaScriptで作る独自のツール（Node.jsまたはブラウザー）コールバックから取得するキー（Bearerとして送信）
REST API/api/v1/...任意の言語での連携Authorization: Bearer <key>のみ
コンテナーレジストリ（OCI）/v2/Docker、Podman、Buildx、containerd、Helmチャート、ORASアーティファクトキーをパスワードにしたBasic（docker login）、またはBearer
Git LFS/lfs/<repository>gitリポジトリの大容量ファイル、UnityとUnreal向けのファイルロックキーをパスワードにしたBasic（gitの認証情報ヘルパー）、またはBearer
npmレジストリ/npm/<repository>/Unity Package Managerのスコープ付きレジストリ、npm publishとnpm installBearer（.npmrcの_authToken、.upmconfig.tomlのtoken）、またはBasicの_auth
パス指定のRawファイル/api/v1/repositories/<repository>/raw/<path>curl -TまたはPowerShellによる1回のリクエストAuthorization: Bearer <key>のみ
Webhookお客様の受信側 URLリポジトリが変わったときにデプロイやジョブを開始するすべてのリクエストの HMAC 署名

/v2、/lfs、/npm以下のルートは、それぞれのプロトコルの仕様に従います。これらは/api/v1のOpenAPIドキュメントには含まれず、エラーはそれぞれのクライアントが期待する形式で返されます。

認証情報 ​

公開されているヘルスチェックを除き、すべてのリクエストに認証情報が必要です。Arkvoryは次の種類を受け付けます。

種類形式入手元主な用途
個人用アクセストークンpat_...ユーザーがコンソールで作成します。スコープはreadまたはread-writeです。有効期限があります（既定は90日、最大365日）。開発者：ワークステーションでのUnity、git、Docker
サービスキーarkvory_...管理者がサービスアカウント向けに発行します。リポジトリごとに、許可する操作を正確に指定しますCI/CD、デプロイエージェント、ビルドサーバー
ファイルキー任意のシークレットサーバーのキーファイル（ARKVORY_KEYS_FILE）。リポジトリごとにreadまたはwriteを指定します。所有者のキーは管理も行えますインストールの所有者、従来の連携
セッションdps_...コンソールへのサインイン。12時間有効ですコンソールでの対話的な作業
ダウンロードリンク?token=付きのURL1つのアーティファクト向けに作成します。有効期間は60秒〜24時間ですキーを持たない相手に1つのファイルを渡す

プロトコルによって違うのは、キーの送り方だけです。

  • /api/v1、CLI、SDK、Rawファイルは、Authorization: Bearer <key>を使います。
  • /v2、/lfs、/npmは、HTTP Basicも受け付けます。ユーザー名は検証されません。パスワードがArkvoryのキーです。docker login、gitの認証情報ヘルパー、npmの_authは、この方法で認証情報を送信します。
  • 読み取り専用の個人用トークンが、データを変更することはありません。ただし、Git LFSのバッチリクエストはダウンロードの場合もPOSTであるため、Git LFSオブジェクトのダウンロードはできます。

トークンとキーの作成方法は、アカウントとキーを参照してください。ヘッダーの詳細は、認証を参照してください。

どれを使えばよいか ​

タスク推奨される方法
CIからビルドアーティファクトをアップロードし、ネットワーク障害の後に再開するarkvoryctl uploadまたはarkvoryctl put
CIからUPackパッケージを公開するarkvoryctl packages publish
「最新の1.4リリース」をサーバーにデプロイするarkvoryctl packages download --range ^1.4 --stage release
何もインストールせずに、シェルスクリプトから小〜中サイズのファイルをパス指定で置くcurl -TまたはPowerShellによるRawファイル
コンテナーイメージやHelmチャートを保存するコンテナーイメージ
ゲームのテクスチャ、モデル、レベルをgitホストの外に保管するGit LFS
プロジェクト間でUnityパッケージを共有するUnityとnpmのパッケージ
独自のツールやWebインターフェイスを作るTypeScript SDK
Python、Go、C#などの言語から連携するREST API
全体を確認する、ユーザー、キー、バックアップを管理するWebコンソール

選ぶときの目安は次のとおりです。

  • 大容量ファイル（数ギガバイト以上）：arkvoryctlまたはSDKを使います。パートに分けてアップロードし、中断後に続行します。単一のPUTリクエスト（Rawファイル、Git LFSオブジェクト、npm publish、Dockerのレイヤー）は、失敗すると0バイト目からやり直しになります。
  • ツールがすでにプロトコルに対応している場合：そのプロトコルを使います。Docker、git、Unityに追加のソフトウェアは不要です。
  • 機械が読み取るだけの場合：読み取り専用のトークン、または読み取り操作だけを持つサービスキーを与えます。

共通のルール ​

HTTPS：すべてのクライアントでHTTPSを使ってください。CLIとSDKは、ループバック（localhost、127.0.0.1、[::1]）を除き、平文のHTTPを拒否します。Dockerには、信頼された証明書が必要です。gitは、リクエストのたびにキーを送信します。HTTPSを参照してください。

同じストレージ：イメージのレイヤー、Git LFSオブジェクト、npmのtarball、Rawファイルは、すべてアーティファクトです。リポジトリのクォータとインストールの容量に計上され、保存時にSHA-256で検証され、バックアップにも含まれます。

読み取りゲートウェイとミラー：読み取りゲートウェイが受け付けるのは、GETとHEADだけです。ミラーは、別のインストールにあるリポジトリの読み取り専用コピーです。

方法読み取りゲートウェイではミラーでは
/api/v1、CLI、SDK読み取りのみ読み取り。変更は拒否されます（409 mirror_read_only）
コンテナーレジストリプルプル。プッシュは拒否されます
Git LFS非対応（バッチリクエストがPOSTのため）クローンとフェッチ。プッシュとロックは拒否されます
npmレジストリインストールと検索インストールと検索。公開は拒否されます
RawファイルGETとHEADGETとHEAD

読み取りゲートウェイとミラーを参照してください。

Arkvory · ProAnimaStudio