저장소 액세스 프레임워크를 사용하여 파일 열기

Android 4.4(API 수준 19)에는 저장소 액세스 프레임워크(SAF)가 도입되었습니다. SAF는 사용자가 선호하는 문서 저장소 제공자 전체에서 문서, 이미지 및 각종 다른 파일을 탐색하고 여는 작업을 간편하게 해줍니다. 표준형의 사용하기 쉬운 UI를 사용하면 사용자가 각종 앱과 제공자에서 일관된 방식으로 파일을 탐색하고 최근 기록에 액세스할 수 있습니다.

클라우드 또는 로컬 저장소 서비스가 이 생태계에 참여하려면 서비스를 캡슐화하는 DocumentsProvider를 구현하면 됩니다. 제공자의 문서에 액세스해야 하는 클라이언트 앱의 경우 단 몇 줄의 코드만으로 SAF와 통합할 수 있습니다.

SAF에는 다음과 같은 항목이 포함됩니다.

  • 문서 제공자 - 일종의 콘텐츠 제공자로, 저장소 서비스(예: Google 드라이브)가 자신이 관리하는 파일을 나타내도록 허용합니다. 문서 제공자는 DocumentsProvider 클래스의 서브클래스로 구현됩니다. 문서 제공자 스키마는 일반적인 파일 계층 구조에 기초하지만 문서 제공자가 물리적으로 데이터를 저장하는 방식은 개발자가 결정합니다. Android 플랫폼에는 여러 가지 내장된 문서 제공자(예: 다운로드, 이미지, 동영상)가 포함됩니다.
  • 클라이언트 앱 - 일종의 맞춤 앱으로, ACTION_CREATE_DOCUMENT, ACTION_OPEN_DOCUMENT, ACTION_OPEN_DOCUMENT_TREE 인텐트 작업을 호출하고 문서 제공자에서 반환한 파일을 수신합니다.
  • 선택도구 - 일종의 시스템 UI로, 사용자가 클라이언트 앱의 검색 기준을 만족하는 모든 문서 제공자의 문서에 액세스할 수 있습니다.

SAF가 제공하는 기능을 몇 가지 예로 들면 다음과 같습니다.

  • 사용자가 하나의 앱뿐만 아니라 모든 문서 제공자에서 콘텐츠를 탐색할 수 있습니다.
  • 앱이 문서 제공자가 소유한 문서에 장기적, 지속적 액세스 권한을 가질 수 있습니다. 이 액세스 권한을 통해 사용자가 제공자에서 파일을 추가, 편집, 저장 및 삭제할 수 있습니다.
  • 여러 개의 사용자 계정을 지원하며 USB 저장소 제공자와 같은 임시 루트도 지원합니다. 이는 드라이브가 연결되어 있을 때만 나타납니다.

개요

SAF는 DocumentsProvider 클래스의 서브클래스인 콘텐츠 제공자를 중심으로 작동합니다. 데이터는 문서 제공자 내에서 일반적인 파일 계층으로 구조화됩니다.

데이터 모델

그림 1. 문서 제공자 데이터 모델. 루트 하나가 하나의 문서를 가리키고, 이는 다시 트리 전체를 팬아웃하기 시작합니다.

다음 내용을 참고하세요.

  • 각 문서 제공자는 하나 이상의 '루트'를 보고합니다. 이 루트는 문서 트리를 탐색하는 시작 지점입니다. 각 루트는 고유한 COLUMN_ROOT_ID가 있고 루트 아래에 있는 콘텐츠를 나타내는 문서(디렉터리)를 가리킵니다. 기본적으로 루트는 동적으로 움직여 다중 계정, 임시 USB 저장소 기기 또는 사용자 로그인/로그아웃과 같은 사용 사례를 지원합니다.
  • 각 루트 아래에 문서가 하나씩 있습니다. 문서는 1부터 N까지의 문서를 가리키는데, 이는 각각 1부터 N까지의 문서를 가리킬 수 있습니다.
  • 각 저장소 백엔드는 고유한 COLUMN_DOCUMENT_ID로 개별 파일과 디렉터리를 참조하는 방법으로 표시합니다. 문서 ID는 고유해야 하며 한 번 발행되고 나면 변경되지 않습니다. 이들은 기기 재부팅을 통괄하여 영구적인 URI 허가에 사용되기 때문입니다.
  • 문서는 열 수 있는 파일이거나(특정 MIME 유형으로) 추가 문서가 들어 있는 디렉터리일 수 있습니다(MIME_TYPE_DIR MIME 유형으로).
  • 각 문서는 COLUMN_FLAGS에서 설명한 바와 같이 여러 가지 기능이 있습니다. 예: FLAG_SUPPORTS_WRITE, FLAG_SUPPORTS_DELETE, FLAG_SUPPORTS_THUMBNAIL 동일한 COLUMN_DOCUMENT_ID는 여러 디렉터리에 포함될 수 있습니다.

제어 흐름

위에서 언급한 바와 같이, 문서 제공자 데이터 모델은 일반적인 파일 계층 구조를 기반으로 합니다. 그러나 DocumentsProvider API를 사용하여 이에 액세스할 수 있는 한, 데이터를 원하는 방식으로 물리적으로 저장할 수 있습니다. 예를 들어, 데이터를 저장하는 데 태그 기반 클라우드 스토리지를 사용할 수 있습니다.

그림 2는 사진 앱이 SAF를 사용하여 저장된 데이터에 액세스할 수 있는 방법을 보여줍니다.

앱

그림 2. 저장소 액세스 프레임워크 흐름

다음 내용을 참고하세요.

  • SAF에서는 제공자와 클라이언트가 직접 상호작용하지 않습니다. 클라이언트가 파일과 상호작용하기 위한 권한을 요청합니다(다시 말해, 파일을 읽고, 편집하거나 생성 또는 삭제할 권한을 말합니다).
  • 상호작용은 애플리케이션(이 예시에서는 사진 앱)이 인텐트 ACTION_OPEN_DOCUMENT 또는 ACTION_CREATE_DOCUMENT를 실행하면 시작됩니다. 인텐트에는 기준을 더욱 세분화하는 필터가 포함될 수 있습니다. 예를 들어 '열 수 있는 파일 중에서 '이미지' MIME 유형이 있는 파일을 모두 주세요'라고 할 수 있습니다.
  • 인텐트가 실행되면 시스템 선택도구가 등록된 각 제공자로 이동하여 사용자에게 일치하는 콘텐츠 루트를 보여 줍니다.
  • 선택도구는 사용자에게 문서에 액세스하는 데 쓰는 표준 인터페이스를 제공합니다. 이는 기본 문서 제공자 사이에 큰 차이가 있더라도 무관합니다. 예를 들어 그림 2는 Google 드라이브 제공자, USB 제공자와 클라우드 제공자를 나타낸 것입니다.

그림 3은 이미지를 검색하는 사용자가 다운로드 폴더를 선택한 선택도구를 보여 줍니다. 또한 클라이언트 앱에서 사용할 수 있는 모든 루트를 표시합니다.

시스템 선택도구의 폴더 선택 스크린샷

그림 3. 선택도구

사용자가 다운로드 폴더를 선택하면 이미지가 표시됩니다. 그림 4는 이 프로세스의 결과를 보여 줍니다. 이제 사용자는 제공자와 클라이언트 앱이 지원하는 방식으로 이러한 이미지와 상호작용할 수 있습니다.

다운로드 폴더 스크린샷

그림 4. 시스템 선택도구에 표시된, 다운로드 폴더에 저장된 이미지

클라이언트 앱 작성

Android 4.3 이하에서는 앱이 다른 앱에서 파일을 검색할 수 있게 하려면 ACTION_PICK 또는 ACTION_GET_CONTENT와 같은 인텐트를 호출해야 합니다. 그런 다음 사용자는 파일을 선택할 앱을 하나 선택해야 합니다. 선택한 앱은 사용자가 이용 가능한 파일에서 탐색하고 선택할 수 있는 사용자 인터페이스를 제공해야 합니다.

Android 4.4(API 수준 19) 이상에서는 ACTION_OPEN_DOCUMENT 인텐트를 사용하는 추가 옵션이 있습니다. 이 인텐트는 사용자가 다른 앱에서 제공한 모든 파일을 탐색할 수 있는 시스템 제어 선택도구 UI를 표시합니다. 이 하나의 UI에서 사용자는 지원되는 모든 앱의 파일을 선택할 수 있습니다.

Android 5.0(API 수준 21) 이상에서는 ACTION_OPEN_DOCUMENT_TREE 인텐트를 사용할 수도 있습니다. 이 인텐트로 사용자는 클라이언트 앱이 액세스할 디렉터리를 선택할 수 있습니다.

참고: ACTION_OPEN_DOCUMENTACTION_GET_CONTENT를 대체할 목적으로 만들어진 것이 아닙니다. 어느 것을 사용해야 할지는 각자의 앱에 필요한 것이 무엇인지에 좌우됩니다.

  • 앱이 단순히 데이터를 읽거나 가져오도록 하려면 ACTION_GET_CONTENT를 사용합니다. 이 방식을 사용하면 앱은 데이터 사본(예: 이미지 파일)을 가져오게 됩니다.
  • 앱이 문서 제공자가 소유한 문서에 장기적, 지속적 액세스 권한을 가지기를 바라는 경우에는 ACTION_OPEN_DOCUMENT를 사용합니다. 일례로 사용자에게 문서 제공자에 저장된 이미지를 편집할 수 있게 해주는 사진 편집 앱이 있습니다.

시스템 선택도구 UI를 사용하여 파일 및 디렉터리 탐색을 지원하는 방법에 관한 자세한 내용은 문서 및 기타 파일에 액세스하는 방법 가이드를 참고하세요.

추가 리소스

문서 제공자에 관한 자세한 내용은 다음 리소스를 참고하세요.

샘플

동영상