bring-your-own-uploader.md 9.6 KB
title: 独自アップローダーの持ち込み metaTitle: 独自アップローダーの持ち込み | Sugar
description: Sugarに独自のアップローダーを持ち込む方法。
Sugarは拡張可能なアーキテクチャを持ち、最小限の労力で新しいアップロード方法の実装を簡単に可能にします。アップロードロジックはuploadコマンドから分離されており、Rustトレイトを実装することで新しい方法をアップロードフローにプラグインでき、*自由形式*と並列アップロード方法の両方をサポートします：
Uploader: このトレイトは、アップロードの実行方法を完全に制御する必要があるアップロード方法によって直接実装される必要があります。ParallelUploader: このトレイトはスレッドロジックを抽象化し、方法が単一アセット（ファイル）のアップロードロジックに集中できるようにします。
異なるトレイトの使用は、以下のアップロードアーキテクチャの概要で説明されています：
アップローダーを実装するために、最初のステップはアップロードプロセスの完全な制御が必要か、あなたの方法が並列アップロードをサポートするかを決定することです。これにより、実装するトレイトが決まります。実装するトレイトに関係なく、アップロードが必要なアセット（ファイル）はAssetInfo構造体で表現されます：
pub struct AssetInfo {
/// Id of the asset in the cache.
pub asset_id: String,
/// Name (file name) of the asset.
pub name: String,
/// Content of the asset - either a file path or the string
/// representation of its content.
pub content: String,
/// Type of the asset.
pub data_type: DataType,
/// MIME content type.
pub content_type: String,
}
AssetInfoは物理ファイルを表現でき、その場合contentはファイルの名前に対応します；またはメモリ内アセットを表現でき、その場合contentはアセットの内容に対応します。
例えば、画像ファイルの場合、contentはファイルシステム上のファイルのパスを含みます。jsonメタデータファイルの場合、contentにはjsonメタデータの文字列表現が含まれます。
トレイト
トレイト実装の詳細は、Sugarのソースコードで見つけることができます。
Uploader
Uploaderトレイトは、アセット（ファイル）のアップロード方法を完全に制御できます。単一の関数を定義します：
async fn upload(
&self,
sugar_config: &SugarConfig,
cache: &mut Cache,
data_type: DataType,
assets: &mut Vec<AssetInfo>,
progress: &ProgressBar,
interrupted: Arc<AtomicBool>,
) -> Result<Vec<UploadError>>;
ここで：
sugar_config- 現在のSugar設定cache- アセットキャッシュオブジェクト（変更可能）data_type- アップロードされるアセットのタイプassets- アップロードするアセットのベクター（変更可能）progress- コンソールにフィードバックを提供するプログレスバーへの参照interrupted- 通知を受信するための共有中断ハンドラーフラグへの参照
この関数は、各タイプのアセットを個別にアップロードするために呼び出されます—例：画像用に一度、メタデータ用に一度、存在する場合はアニメーションアセット用に一度。アセットをアップロードした後、その情報はcacheオブジェクトで更新され、sync_file関数を使用してキャッシュをファイルシステムに保存する必要があります。大きなコレクションの場合、キャッシュをファイルシステムに同期するのは遅くなる可能性があるため、アップロードプロセスの遅延を避けるために実用的な頻度で行い、同時にユーザーがアップロードを中止した場合の情報損失の可能性を最小限に抑える必要があります。
実装は、ユーザーがCtrl+Cを押してアップロードプロセスを中止するタイミングを制御するためにinterruptedパラメータを使用することが期待されています—これは大きなアップロードに有用です。キャッシュに保存された情報は再アップロードされません。uploadコマンドは既にアップロードされたアセットをフィルターアウトし、アセットのベクターには含まれません。progressはコンソールに表示されるプログレスバーへの参照であり、1つのアセットがアップロードされたことを示すためにprogress.inc(1)関数を呼び出してアップロードの進行状況の視覚的フィードバックを提供するために使用される必要があります。
すべてのファイルが正常にアップロードされると、uploadメソッドは空のVecを返します；エラーの場合、Vecにはユーザーに表示されるUploadErrorのリストが含まれます。
ParallelUploader
ParallelUploadは、同時アップロードをサポートするためにUploaderトレイトのupload関数のスレッド対応実装を提供し、スレッドロジックを抽象化して単一アセット（ファイル）のアップロードロジックに集中します。したがって、アセットを並列にアップロードできる方法は、簡略化されたupload_asset関数を実装する必要があります：
fn upload_asset(
&self,
asset: AssetInfo
) -> JoinHandle<Result<(String, String)>>;
upload_asset関数はJoinHandleオブジェクトを返す必要があります。ほとんどの場合、この関数はtokio::spawnからの値を返します。この関数にはアセットをアップロードするロジックのみを含める必要があります—中断制御とキャッシュ同期はParallelUploadトレイトによって自動的に行われます。
Prepare
すべてのアップロード方法は、追加のトレイトPrepareを実装する必要があります。その理由は、指定されたメディア/メタデータファイルのアップロード用にメソッドを準備することです。例：
- ファイルがサイズ制限を超えていないかチェック；
- アップロード用のストレージ容量があるかチェック；
- アップロード用の資金をチェック/追加。
このトレイトは単一の関数を定義します：
async fn prepare(
&self,
sugar_config: &SugarConfig,
asset_pairs: &HashMap<isize, AssetPair>,
asset_indices: Vec<(DataType, &[isize])>,
) -> Result<()>;
ここで：
sugar_config- 現在のSugar設定asset_pairs-indexからAssetPairへのマッピングasset_indices- アップロードされるアセットペアインデックスの情報を含むベクター、タイプ別にグループ化
asset_pairsにはアセットの完全な情報が含まれていますが、asset_indicesで指定されたアセットのみがアップロードされます—例：インデックス1がDataType::Imageインデックス配列にのみ存在する場合、アセット1の画像のみがアップロードされます。
設定
アップロード方法のロジックを実装した後、あなたの方法をSugarの設定ファイルに統合する必要があります。まず、アップロード方法を識別するためにUploadMethod enumに新しい値を追加する必要があります。次に、設定ファイルで指定されたときにUploaderオブジェクトを作成するためにinitialize ファクトリーメソッドを変更する必要があります。
アップロード方法が追加のパラメータを必要とする場合、ConfigData structを変更する必要があります。例えば、awsアップロード方法では、ユーザーがアップロード用のバケット名を指定する必要があります。ConfigData構造体にはaws_s3_bucketフィールドがあり、これは設定ファイルのawsS3Bucketプロパティに対応します。
アップロード方法トレイト実装を完了し、その詳細をSugarの設定ファイルに追加すると、アセットのアップロードに使用する準備が整います。
{% callout %}
実装をSugarのコードベースに追加するために、SugarのリポジトリにPRを提出することを忘れないでください。
{% /callout %}
次のステップ
Sugarには現在6つのアップロード方法があります—アセットのアップロードの動作方法と独自のアップロード方法を実装するためのデザインアイデアの詳細については、そのソースコードを確認してください。