Storage API

概念と使用法

ストレージバケット

サイトデータが格納されるストレージ標準で定義されているストレージシステムは、通常、オリジン ごとに 1 つの バケット で構成されます。

基本的に、すべてのウェブサイトは、データが格納される独自のストレージ領域を持っています。ただし、場合によっては、ユーザーエージェントが単一のオリジンのデータを複数の異なるバケットに格納することを決めることがあります。例えば、そのオリジンが複数のサードパーティオリジンに埋め込まれている場合です。

詳しくは、ブラウザーでは、異なるウェブサイトのデータをどのように区切るのか を見てください。

バケットモード

各サイトのストレージバケットには、そのバケットのデータ保持ポリシーを決める「モード」があります。モードには以下の 2 種類があります。

"best-effort"（最大限の努力）

ユーザーエージェントは、バケット内のデータをできる限り保とうとしますが、ストレージ容量が足らず、その圧迫を解消するためにバケットをクリアする必要が生じた場合でも、ユーザーへの警告は行いません。

"persistent"（永続的）

ユーザーエージェントはできる限りデータを保ち、"persistent"（永続的）とマークされたバケットの削除を考える前に、"best-effort"（ベストエフォート）のバケットをすべて消します。永続的なバケットの削除を考える必要が生じた場合、ユーザーエージェントはユーザーに通知し、必要に応じて 1 つまたは複数の永続的なバケットを消す手段を提供します。

navigator.storage.persist() メソッドを使うと、オリジンのストレージバケットモードを変えられます。このメソッドには "persistent-storage" ユーザー権限 が必要です。

if (navigator.storage && navigator.storage.persist) {
  navigator.storage.persist().then((persistent) => {
    if (persistent) {
      console.log("明示的なユーザー操作がない限り、ストレージは消されません");
    } else {
      console.log("ストレージが足らない時、UA によってストレージが消されるかもしれません"
    }
  });
}

navigator.storage.persisted() メソッドを使って、あるオリジンのストレージが永続的かどうかを確かめられます。

if (navigator.storage && navigator.storage.persist) {
  navigator.storage.persisted().then((persistent) => {
    if (persistent) {
      console.log("明示的なユーザー操作がない限り、ストレージは消されません");
    } else {
      console.log(
        "ストレージが足らない時、UA によってストレージが消されるかもしれません",
      );
    }
  });
}

詳しくは ブラウザーに格納されるデータは維持されるか を見てください。

クォータと使用量の推定

ユーザーエージェントは、選んだ任意のメカニズムを使って、特定のサイトが使えるストレージの最大量を決めます。この最大値がオリジンのクォータ（quota）です。サイトが使っているスペースの量は、その使用量（usage）と呼ばれます。これらの値は両方とも推定値です。正確でない理由は次のようにいくつかあります。

• ユーザーエージェントは、特定のオリジンが使うデータの正確なサイズを隠す方が良いです。これは、それらの値がFingerprinting (フィンガープリンティング)目的で使われるのを防ぐためです。
• 格納されたデータの物理的サイズを小さくするために重複排除、圧縮、およびその他の方法が使われることがあります。
• クォータは、オリジンが使えるスペースの控えめな概算値であり、オーバーランを防ぐためにデバイスで使えるスペースより小さくなければなりません。

特定のオリジンにおける推定クォータと使用量を調べるには、navigator.storage.estimate() メソッドを使います。このメソッドは Promise を返し、解決されると、これらの数を含むオブジェクトを受け取ります。例えば:

navigator.storage.estimate().then((estimate) => {
  // estimate.quota は見積もりクォータです
  // estimate.usage は見積もり使用バイト数です
});

オリジンが保存できるデータ量の詳しくは、どれだけのデータが格納できるか を見てください。

データ削除

データ削除とは、ユーザーエージェントがオリジンに保存されているデータを消すプロセスです。これは、 データの保存に使われているデバイスのストレージ容量が足りていない場合に起きます。

オリジンに保存されているデータをクリアする場合、オリジンのバケットは単一のエンティティとして扱われます。このオリジンに保存されているデータはすべてクリアされます。

バケットが "persistent" としてマークされている場合、データのオリジン自体またはユーザーが明示的に消さない限り、ユーザーエージェントによってバケットの内容はクリアされません。これには、ユーザーが 「キャッシュをクリア」 または 「最近の履歴をクリア」 オプションを選んだ場合などが含まれます。ユーザーには、永続的なサイトストレージバケットを消すための許可を具体的に求められます。

詳しくは データが退去されるのはいつか を見てください。

インターフェイス

StorageManager

永続化の権限を管理し、使えるストレージ容量を推定するためのインターフェイスを提供します。

他のインターフェイスへの拡張

Navigator.storage 読取専用

サイトやアプリごとに、永続化の権限を管理し、使えるストレージ容量を推定するために使われるシングルトンの StorageManager オブジェクトを返します。

WorkerNavigator.storage 読取専用

永続化の権限を管理し、使えるストレージ容量を推定するための StorageManager インターフェイスを返します。

仕様書

ブラウザーの互換性

関連情報

• Permissions API の使用
• web.dev のウェブ向けのストレージ
• web.dev の永続ストレージ
• Chrome の Web ストレージとクォータの概念 (英語)