アセットのアップロードとダウンロード

Umiは、UploaderInterfaceとDownloaderInterfaceインターフェースをそれぞれ介して、任意のファイルをアップロードおよびダウンロードできるようにします。

汎用ファイル

ファイルの定義は、ライブラリや、ブラウザーにいるかNodeサーバーにいるかによって異なるため、UmiはGenericFileと呼ばれるタイプを定義して、ファイルの共通タイプに合意できるようにします。

type GenericFile = {
  readonly buffer: Uint8Array;
  readonly fileName: string;
  readonly displayName: string;
  readonly uniqueName: string;
  readonly contentType: string | null;
  readonly extension: string | null;
  readonly tags: GenericFileTag[];
};

ご覧のとおり、そのコンテンツはUint8Arrayバッファーとして格納され、ファイル名、表示名、コンテンツタイプなどのいくつかのメタデータが含まれています。また、追加データをタグとして格納するシンプルなキー値ストレージも含まれています。これらは、アップローダーにファイルに関する追加情報を渡すためにも使用できます。

createGenericFileヘルパー関数を使用して、そのコンテンツとファイル名から新しいGenericFileインスタンスを作成できます。この関数は、ブラウザーがファイルを正しくレンダリングするのに役立つように、ファイルのMIMEタイプとして設定すべきcontentTypeも受け入れます。

特定の環境からファイルをGenericFileに、またその逆に変換するのに役立つように、Umiはいくつかの追加ヘルパーメソッドも提供します。

// 汎用ファイルを直接作成。
createGenericFile('some content', 'my-file.txt', { contentType: "text/plain" });

// ブラウザーファイルとの間で汎用ファイルを解析。
await createGenericFileFromBrowserFile(myBrowserFile);
createBrowserFileFromGenericFile(myGenericFile);

// JSONオブジェクトとの間で汎用ファイルを解析。
createGenericFileFromJson(myJson);
parseJsonFromGenericFile(myGenericFile);

アップローダーインターフェース

まず第一に、UploaderInterfaceは、一度に1つまたは複数のファイルをアップロードするために使用できるuploadメソッドを提供します。渡された順序でアップロードされたファイルを表すURIの配列を返します。

const [myUri, myOtherUri] = await umi.uploader.upload([myFile, myOtherFile]);

uploadメソッドは、アップロードをキャンセルするための中止signalやアップロードの進行状況を追跡するonProgressコールバックなど、アップロードプロセスを設定するためのいくつかのオプションも受け入れます。これらはすべてのアップローダーでサポートされているわけではないことに注意してください。

const myUris = await umi.uploader.upload(myFiles, {
  signal: myAbortSignal,
  onProgress: (percent) => {
    console.log(`${percent * 100}% uploaded...`);
  },
})

UploaderInterfaceは、JSONオブジェクトをファイルに変換してアップロードするuploadJsonメソッドも提供します。

const myUri = await umi.uploader.uploadJson({ name: 'John', age: 42 });

最後に、アップローダーがファイルのセットを保存するために料金を請求する場合、getUploadPriceメソッドを使用してそのコストを知ることができます。これは、任意の通貨と単位になることができるカスタムAmountオブジェクトを返します。

const price = await umi.uploader.getUploadPrice(myFiles);

ダウンローダーインターフェース

相互に、DownloaderInterfaceは、一度に1つまたは複数のファイルをダウンロードするために使用できるdownloadメソッドと、解析されたJSONファイルをダウンロードするために使用できるdownloadJsonメソッドを提供します。これらのメソッドは両方とも、中止signalを介してキャンセルできます。

// 1つまたは複数のファイルをダウンロード。
const [myFile, myOtherFile] = await umi.downloader.download([myUri, myOtherUri]);

// 中止シグナルを使用してダウンロード。
const myFiles = await umi.downloader.download(myUris, { signal: myAbortSignal });

// JSONファイルをダウンロード。
type Person = { name: string; age: number; };
const myJsonObject = await umi.downloader.downloadJson<Person>(myUri);

モックストレージ

Umiは、アップローダーとダウンローダーの両方として機能するモックストレージヘルパークラスを提供します。実際のストレージサービスを設定することなく、アプリケーションをテストするために使用できます。モックストレージにアップロードされたものは、後でダウンロードできるようにメモリにキャッシュされます。

モックストレージヘルパーはスタンドアロンパッケージとして利用可能で、個別にインストールする必要があります。

npm install @metaplex-foundation/umi-storage-mock

その後、提供されるプラグインをUmiインスタンスに登録して、使用を開始できます。

import { mockStorage } from '@metaplex-foundation/umi-storage-mock';

umi.use(mockStorage());
const [myUri] = await umi.uploader.upload([myFile]);
const [myDownloadedFile] = await umi.downloader.download([myUri]);
// myFileとmyDownloadedFileは同一です。