Android 4.4（API レベル 19）は、ストレージ アクセス フレームワーク（SAF）を採用しています。SAF を利用することで、ユーザーは希望するドキュメント ストレージ プロバイダ全体を通じてドキュメント、画像などのファイルを参照して開くことができます。標準の使いやすい UI により、アプリやプロバイダを通じて一貫性のある方法でファイルを参照したり、最近使用したファイルにアクセスしたりできます。
サービスをカプセル化する DocumentsProvider を実装することで、クラウドやローカル ストレージ サービスをエコシステムに参加させることができます。プロバイダのドキュメントへのアクセスが必要なクライアント アプリは、数行のコードだけで SAF と統合できます。
SAF には次の項目が含まれます。
- ドキュメント プロバイダ: ストレージ サービス（Google ドライブなど）に管理するファイルの公開を許可するコンテンツ プロバイダです。ドキュメント プロバイダは
DocumentsProviderクラスのサブクラスとして実装されます。document-provider スキーマは従来のファイル階層に基づくものですが、ドキュメント プロバイダが物理的にどのようにデータを格納するかはその設定次第です。Android プラットフォームには、ダウンロード、画像、動画などの組み込みのドキュメント プロバイダがいくつか用意されています。 - クライアント アプリ:
ACTION_CREATE_DOCUMENT、ACTION_OPEN_DOCUMENT、ACTION_OPEN_DOCUMENT_TREEインテント アクションを呼び出し、ドキュメント プロバイダが返したファイルを受け取るカスタムアプリです。 - 選択ツール: クライアント アプリの検索条件を満たす、すべてのドキュメント プロバイダのドキュメントにアクセスできるシステム UI です。
SAF には次の機能があります。
- ユーザーは 1 つのアプリだけでなく、すべてのドキュメント プロバイダのコンテンツを参照できます。
- アプリからドキュメント プロバイダが所有するドキュメントへの、長期間の永続的なアクセスを可能にします。このアクセスにより、ユーザーはプロバイダ上でのファイルの追加、編集、保存、削除が可能になります。
- 複数のユーザー アカウントと USB ストレージ プロバイダなどの一時的なルートをサポートします。一時的なルートはドライブを接続した場合にのみ表示されます。
概要
SAF は、DocumentsProvider クラスのサブクラスであるコンテンツ プロバイダを中心に展開します。ドキュメント プロバイダ内では、データは従来のファイル階層として構造化されています。
次の点にご注意ください。
- 各ドキュメント プロバイダは、ドキュメントのツリーを検索する出発点となる 1 つ以上のルートを報告します。各ルートは一意の
COLUMN_ROOT_IDを持ち、そのルートの下にあるコンテンツを表すドキュメント（ディレクトリ）を指しています。ルートは、複数のアカウント、一時的な USB ストレージ デバイス、ユーザーのログインとログアウトなどのユースケースに対応するために、動的に設計されています。 - 各ルートの下にはドキュメントが 1 つだけあります。そのドキュメントは 1～N 個のドキュメントを指し、さらにそれぞれのドキュメントも 1～N 個のドキュメントを指すことができます。
- 各ストレージ バックエンドは、一意の
COLUMN_DOCUMENT_IDを使って参照することにより、個々のファイルやディレクトリを表示します。ドキュメント ID は、デバイスを再起動しても変わらない永続的な URI の付与に使用されるため、一意でなければならず、一度発行すると変更できません。 - ドキュメントには、開くことができるファイル（特定の MIME タイプを持つもの）か、追加のドキュメント（
MIME_TYPE_DIRMIME タイプを持つもの）を含むディレクトリのいずれかを設定できます。 - 各ドキュメントはさまざまな機能を持つことができ、
COLUMN_FLAGSを使って記述します。たとえば、FLAG_SUPPORTS_WRITE、FLAG_SUPPORTS_DELETE、FLAG_SUPPORTS_THUMBNAILといった機能です。同じCOLUMN_DOCUMENT_IDを複数のディレクトリに含めることができます。
制御フロー
ドキュメント プロバイダのデータモデルは従来のファイル階層に基づいています。ただし、DocumentsProvider API を使用してアクセスできる限り、任意の方法で物理的にデータを格納できます。たとえば、データにタグベースのクラウド ストレージを使用できます。
図 2 は、写真アプリが格納されたデータに SAF を使ってアクセスする方法を表しています。
次の点にご注意ください。
- SAF では、プロバイダとクライアントは直接やり取りできません。クライアントが、ファイルを操作（ファイルの読み取り、編集、作成、削除）するための権限を要求します。
- アプリ（この例では写真アプリ）がインテント
ACTION_OPEN_DOCUMENTまたはACTION_CREATE_DOCUMENTを起動すると、やり取りが開始されます。 インテントには、条件をさらに絞り込むためのフィルタを含めることができます。たとえば、「image」の MIME タイプを持ち、開くことができるすべてのファイルを取得する、のように設定できます。 - インテントが起動すると、システムの選択ツールが登録済みの各プロバイダに移動し、一致するコンテンツのルートをユーザーに表示します。
- 選択ツールは、基盤となるドキュメント プロバイダが大きく異なる場合でも、ドキュメントにアクセスするための標準的なインターフェースをユーザーに提供します。たとえば、図 2 には、Google ドライブ プロバイダ、USB プロバイダ、クラウド プロバイダが示されています。
図 3 では、ユーザーが画像の検索で開いた選択ツールからダウンロード フォルダを選択しています。クライアント アプリで使用可能なすべてのルートも表示されています。
ユーザーがダウンロード フォルダを選択すると、画像が表示されます。図 4 は、このプロセスの結果を表しています。ユーザーはプロバイダとクライアント アプリがサポートする方法で、画像を操作できる状態になりました。
クライアント アプリを作成する
Android 4.3 以前では、別のアプリからファイルを取得する場合、アプリは ACTION_PICK や ACTION_GET_CONTENT などのインテントを呼び出す必要があります。その後、ユーザーはファイルを選択するアプリを 1 つ選択します。選択されたアプリはユーザーが使用可能なファイルを参照して選択するためのユーザー インターフェースを提供する必要があります。
Android 4.4（API レベル 19）以降では、ACTION_OPEN_DOCUMENT インテントを使用するという選択肢もあります。このインテントではシステム制御の選択ツール UI が表示され、ユーザーはそこから他のアプリで利用可能なすべてのファイル参照できます。ユーザーは、この 1 つの UI から、サポートされるすべてのアプリのファイルを選択できます。
Android 5.0（API レベル 21）以降では、ACTION_OPEN_DOCUMENT_TREE インテントも使用できます。このインテントでは、ユーザーがアクセスするクライアント アプリのディレクトリを選択することができます。
注: ACTION_OPEN_DOCUMENT は ACTION_GET_CONTENT の代わりとなるものではありません。どちらを使用するかは、アプリのニーズによって異なります。
- アプリでデータの読み取りまたはインポートを行う場合は、
ACTION_GET_CONTENTを使用します。この方法を使用すると、アプリは、画像ファイルなどのデータのコピーをインポートします。 - アプリからドキュメント プロバイダが所有するドキュメントへの、長期間の永続的なアクセスを可能にするには、
ACTION_OPEN_DOCUMENTを使用します。ドキュメント プロバイダに格納されている画像をユーザーが編集するための、写真編集アプリなどの例が挙げられます。
システムの選択ツール UI を使用してファイルとディレクトリの参照をサポートする方法については、ドキュメントや他のファイルにアクセスする方法に関するガイドをご覧ください。
参考情報
ドキュメント プロバイダについて詳しくは、以下のリソースをご利用ください。