ファイルとディレクトリー項目 API の紹介

この入門ページでは、ファイルとディレクトリー項目 API における重要な概念と用語について解説しています。全体像を把握し、重要な概念の方向性を示すものです。また、無視するとセキュリティエラーが発生する制限についても記述しています。この API で使用される用語については、用語集の節を参照してください。

ファイルとディレクトリー項目 API のリファレンス文書については、リファレンスのランディングページとそのサブページを見てください。

仕様は現在も定義されており、変更される可能性があります。

ファイルとディレクトリー項目APIには、非同期と同期の両方のバージョンのインターフェイスが含まれています。非同期APIは、未解決の操作によってUIがブロックされるのを避けたい場合に使用できます。一方、同期APIは、よりシンプルなプログラミングモデルで使用できますが、ウェブワーカー と共に使用しなければなりません。

ファイルとディレクトリー項目APIは、以下の理由から重要なAPIです。

• アプリにオフライン機能や大きなバイナリー blob を伴うストレージ機能を持たせることができる。
• アプリがバックグラウンドで資産を先読みし、ローカルにキャッシュすることで、パフォーマンスを向上させることができます。
• ウェブアプリケーションのユーザーが、ローカルのファイルディレクトリーにあるバイナリーファイルを直接編集できるようになります。
• ファイルシステムを使用することに慣れているユーザーにとって、すでに慣れ親しんだストレージAPIを提供することができます。

このアプリで作成する機能の例については、サンプルの使用例の節を参照してください。

ファイルとディレクトリー項目 API は、IndexedDB などの他のストレージ API に代わるものです。この API は、以下の理由から、blob を扱うアプリに適した選択肢です。

• ファイルとディレクトリー項目 API は、データベースでは対応できない用途のために、クライアント側のストレージを提供します。変更可能な大きなデータの塊を扱いたい場合、ファイルとディレクトリー項目 API は、データベースよりもはるかに効率的なストレージソリューションです。
• Firefox は IndexedDB の blob ストレージに対応していますが、Chrome は現在対応していません（Chrome は IndexedDB の blob ストレージに対応するために実装している最中です）。アプリで Chrome を対象とし、Blob を格納するためには、ファイルとディレクトリー項目 API と App Cache だけが選択肢となります。しかし、AppCache ストレージはローカルで変更可能なものではなく、クライアント側できめ細かく管理することができません。
• Chrome では、ファイルとディレクトリー項目 API とクォータ管理 APIを使用して、より多くのストレージを要求したり、ストレージのクォータを開発したりすることができます。

ファイルとディレクトリー項目 API を使用する例として、以下のようなものがあります。

• 持続的アップローダーを使用するアプリ
• アップロードするファイルや ディレクトリーを選択すると、そのファイルをローカルのサンドボックスにコピーして、一度に塊をアップロードすることができます。
  • ブラウザーが閉じられたり、クラッシュしたり、接続が中断されたり、コンピューターがシャットダウンされるなど、中断した後にアプリがアップロードを再開することができます。
• 動画ゲームなど、メディア資産を大量に扱うアプリ
• このアプリは、1 つまたは複数の大きな tarball をダウンロードし、ローカルでディレクトリー構造に展開します。
• アプリはバックグラウンドで資産を先読みするので、ユーザーはダウンロードを待つことなく、次のタスクやゲームレベルに進むことができます。
• オフラインアクセスまたはローカルキャッシュを備えた音声エディターや写真エディター（パフォーマンスとスピードに優れています）。
• アプリは、ファイルに対して配置することができます（例えば、ファイル全体ではなく、 ID3/EXIF タグだけを上書きすることができます）。
• オフライン動画ビューアー
  • アプリは、後で見るために大きなファイル（1GB 以上）をダウンロードすることができます。
  • アプリは、部分的にダウンロードされたファイルにアクセスすることができます（アプリが残りのコンテンツをまだダウンロードしている場合や、電車に乗るために実行したためにアプリがダウンロードを完了しなかった場合でも、DVD の最初の章を見ることができます）。
• オフラインのウェブメールクライアント
  • クライアントは、添付ファイルをダウンロードし、格納するために、添付ファイルを保存します。
  • クライアントは、後でアップロードするために添付ファイルをキャッシュします。

ファイルとディレクトリー項目 API を使用し始める前に、いくつかの概念を理解する必要があります。

この API はローカルのファイルシステムへのアクセル権を与えるものではなく、またサンドボックスも実際のファイルシステムの一部ではありません。実際には、サンドボックスは仮想化されたファイルシステムであり、ウェブアプリケーションからは本格的なファイルシステムのように見えます。ブラウザー外部のローカルファイルシステムとは必ずしも関係がありません。

すなわち、ウェブアプリケーションとデスクトップアプリが同時に同じファイルを共有することができないということです。この API は、ウェブアプリケーションがブラウザー外の、デスクトップアプリケーションも作業することができるファイルにアクセスすることを許可するものではありません。しかし、ウェブアプリケーションからデスクトップアプリにファイルをエクスポートすることは可能です。例えば、ファイル API を使用して blob を作成し、iframe を blob にリダイレクトして、ダウンロードマネージャーを呼び出すことができます。

アプリケーションは、一時的または持続的なストレージをリクエストすることができます。一時的なストレージは、ブラウザーから与えられるだけなので取得しやすいですが、制限があり、空間がなくなるとブラウザーが削除することができます。一方、持続的なストレージは、ユーザーによってのみ削除可能な大きな空間を提供するかもしれませんが、そのためにはユーザーから許可を得る必要があります。

キャッシュには一時的なストレージを使用し、ユーザーが作成したデータや固有のデータなど、アプリに保持させたいデータには永続的なストレージを使用します。

ウェブアプリケーションがディスクを使い切ってしまうのを防ぐために、ブラウザーはアプリごとにクォータを課し、ウェブアプリケーション間でストレージを割り当てることがあります。

ストレージ空間の付与や割り当て方法、ストレージを管理する方法は、ブラウザーによって異なるため、各ブラウザーのドキュメントを調べる必要があります。例えば Google Chrome では、仕様で定められている 5MB を超える一時的なストレージを許可し、クォータ管理 API に対応しています。Chrome 固有の実装については、Managing HTML Offline Storage を参照してください。

ファイルとディレクトリー項目 API には、非同期バージョンと同期バージョンがあります。どちらのバージョンの API も、同じ機能と性能を提供します。実際、いくつかの違いを除けば、ほとんど同じです。

ウェブワーカー

非同期 API は文書とウェブワーカーのどちらのコンテキストでも使用できますが、同期 API はウェブワーカーのみで使用するためのものです。

コールバック

非同期 API では値を返すことでデータを渡すのではなく、コールバック関数を渡す必要があります。処理を実行するためのリクエストを送信し、コールバックで通知を受け取ります。一方、同期 API は API メソッドが値を返すので、コールバックは使用しません。

非同期APIと同期 API のグローバルメソッド

非同期APIには、requestFileSystem() と resolveLocalFileSystemURL() というグローバルメソッドがあります。 これらのメソッドは Window オブジェクトとワーカーのグローバルスコープの両方のメンバーになります。一方、同期 API には、requestFileSystemSync() と resolveLocalFileSystemSyncURL() というメソッドが使用されます。 これらの同期メソッドは、ワーカーのグローバルスコープのみのメンバーであり、Window オブジェクトのメンバーではありません。

同期 API は、いくつかのタスクではよりシンプルにすることができます。直接的で順序通りのプログラミングモデルなので、コードが読みやすくなります。同期 API の欠点は、多少の制約があるウェブワーカーのやり取りが必要であることです。

非同期 API を使用する場合は、常にエラーコールバックを使用してください。メソッドのエラーコールバックはオプション引数ですが、健全性を保つためには、省略できないものです。なぜ呼び出しに失敗したのかを知りたいはずです。少なくとも、エラーメッセージを提供するようにエラーを処理し、何が起こっているのかが分かるようにしましょう。

ファイルとディレクトリー項目 API は、ウェブプラットフォーム上の他の API や要素と一緒に使用するように設計されています。例として、以下のいずれかを使用されることが多いようです。

• XMLHttpRequest （ファイルやブロブオブジェクトの send() メソッドなど）。
• ドラッグ & ドロップ API
• ウェブワーカー（ファイルとディレクトリー項目 API の同期版のため）
• input`要素（プログラムからファイルのリストを取得するためのもの）

ファイルシステム API は、大文字と小文字を区別し、保持します。

セキュリティ上の理由から、ブラウザーはファイルへのアクセスに制限を課しています。これを無視すると、セキュリティエラーが発生します。

オリジンとは、スクリプトが実行される文書の URL のドメイン、アプリケーション層プロトコル、ポート番号のことです。それぞれのオリジンには、関連するファイルシステムの集合があります。

ファイルシステムにはセキュリティ境界が設定されており、アプリケーションは異なるオリジンのデータにアクセスすることができません。これにより、アクセスや削除を防ぐことができ、プライベートなデータを保護することができます。例えば、http://www.example.com/app/ のアプリやページは、http://www.example.com/dir/ のファイルにアクセスできますが、これらは同じオリジンであるため、http://www.example.com:8080/dir/（異なるポート番号）やhttps://www.example.com/dir/（異なるプロトコル）のファイルを取得することはできません。

悪意のあるアプリが不正な実行ファイルを実行するのを防ぐため、ファイルとディレクトリー項目 API のサンドボックス内では実行ファイルを作成することはできません。

ファイルシステムはサンドボックス化されているため、ウェブアプリケーションが他のアプリケーションのファイルにアクセスすることはできません。また、ユーザーのハードディスク上の任意のフォルダー内（例えば、マイピクチャやマイドキュメント）へのファイルの読み書きはできません。

file:// からローカルにアプリを実行することはできません。実行すると、ブラウザーがエラーを発生するか、アプリが暗黙に失敗します。この制限は、Blob や FileReader を含む多くのファイル API にも適用されます。

テスト目的の場合、ブラウザーに --allow-file-access-from-files フラグを付けて起動することで、Chrome の制限を回避することができます。このフラグはこの目的のみに使用してください。

この節では、ファイルとディレクトリー項目 API で使用される用語の定義と説明をします。

blob

バイナリーラージオブジェクトの略。ブロブとは、単一のオブジェクトとして格納されるバイナリーデータの集合のこと。ウェブアプリケーションでバイナリーデータを参照するための汎用的な方法である。ブロブには画像や音声ファイルなどがあります。

Blob

Blob（大文字の B）とは、不変のデータ構造であり、Blob が参照するバイナリーデータを直接変更することができないことを意味しています。このため、Blob は非同期 API で渡されたときに予測可能な動作をします。

持続的なストレージ

持続的なストレージとは、ユーザーが消去したり、アプリが削除したりしない限り、ブラウザーに残るストレージのことです。

一時的なストレージは

一時的なストレージは、どのウェブアプリケーションでも利用できます。これは自動的なもので、リクエストされる必要はありませんが、ブラウザーは警告なしにストレージを削除することができます。

• ファイルとディレクトリー項目 API
• Read files in JavaScript (web.dev)