Storage Access Framework: 개념, 작동 방식 및 Android에서의 파일 접근

Storage Access Framework란?

Storage Access Framework는 시스템 대화상자를 통해 문서를 선택하고 생성하기 위한 통합 인터페이스를 제공하는 Android SDK의 일부입니다. SAF는 파일의 물리적 위치를 추상화합니다: 앱은 파일이 로컬 디스크, Google Drive 또는 Dropbox 중 어디에서 읽히는지 알지 못합니다.

SAF 아키텍처는 세 가지 구성 요소로 이루어집니다: 요청을 시작하는 클라이언트 앱, 표준 파일 선택 대화상자인 시스템 선택기, 특정 저장소의 파일에 대한 접근을 구현하는 콘텐츠 제공자인 DocumentProvider입니다. 사용자는 데이터 소스에 관계없이 통합된 인터페이스를 봅니다.

SAF는 Android 4.4(API 19)부터 사용 가능합니다. 처음에는 문서만 지원했지만 Android 5.0에서 ACTION_OPEN_DOCUMENT_TREE를 통한 디렉토리 지원이 추가되었습니다. Android 10부터 SAF는 앱별 저장소 외부의 파일에 접근하는 권장 방법이 되었습니다.

SAF 작동 방식: 시스템 선택기와 URI

SAF는 ACTION_OPEN_DOCUMENT 작업으로 Intent를 통해 시스템 파일 선택 대화상자를 시작합니다. 사용자는 내부 저장소, Google Drive, Dropbox 및 기타 등록된 제공자의 목록을 봅니다. 파일을 선택한 후, 시스템은 임시 접근 권한이 있는 content URI를 반환합니다.

content URI 형식은 content://com.android.externalstorage.documents/document/primary/Download/file.pdf입니다. file:// URI와 달리 content URI는 실제 파일 경로를 노출하지 않으며 DocumentProvider를 통해 작동합니다. 앱은 얻은 URI를 사용하여 ContentResolver.openInputStream을 통해 파일을 읽습니다.

시스템 선택기는 MIME 유형별로 파일의 검색, 정렬 및 필터링을 자동으로 지원합니다. 개발자는 Intent.putExtra(Intent.EXTRA_MIME_TYPES, arrayOf("application/pdf", "image/*"))를 통해 필요한 유형을 지정하고, 선택기는 관련 파일만 표시합니다.

URI 접근 수명 주기

기본적으로 URI는 앱 재시작 또는 장치 재부팅까지 유효합니다. 장기 접근을 위해 앱은 takePersistableUriPermission을 요청합니다. 이렇게 하면 대화상자를 통해 다시 선택하지 않고도 이후 실행에서 파일을 읽을 수 있습니다.

ACTION_OPEN_DOCUMENT 및 ACTION_CREATE_DOCUMENT

SAF는 파일 작업을 위한 세 가지 주요 작업(열기, 생성, 폴더 트리 선택)을 제공합니다. ACTION_OPEN_DOCUMENT는 기존 파일을 선택하기 위해 시스템 선택기를 엽니다. ACTION_CREATE_DOCUMENT는 새 파일을 생성합니다. 사용자는 대화상자에 이름을 입력하고 앱은 쓰기용 URI를 받습니다.

ACTION_OPEN_DOCUMENT_TREE는 전체 디렉토리를 선택하고 그 안의 모든 파일에 대한 접근을 얻을 수 있습니다. 이는 파일 관리자, 백업 앱 및 동기화 도구에서 사용됩니다. 앱은 디렉토리 URI를 받고 DocumentFile을 통해 콘텐츠를 재귀적으로 열거할 수 있습니다.

각 작업에 대해 MIME 유형은 EXTRA_MIME_TYPES를 통해 지정됩니다. 여러 유형("application/pdf", "image/*", "text/plain")을 지정할 수 있습니다. 유형이 지정되지 않으면 선택기가 모든 파일을 표시합니다.

Persistent URI permissions

Persistent URI permissions은 현재 세션이 종료된 후에도 파일에 대한 접근을 유지할 수 있는 SAF 메커니즘입니다. 이 플래그가 없으면 URI는 앱 재시작까지만 유효합니다. 앱은 READ 및 WRITE 플래그와 함께 FLAG_GRANT_PERSISTABLE_URI_PERMISSION 플래그를 요청합니다.

권한을 저장하려면 ContentResolver.takePersistableUriPermission 메서드를 사용합니다. 시스템은 URI를 특별한 레지스트리에 저장하고 다음 앱 실행 시 접근을 복원합니다. 앱이 URI에 대한 영구 접근 권한이 있는지 확인하려면 ContentResolver.persistedUriPermissions을 사용합니다.

사용자는 설정 → 앱 → 권한을 통해 저장된 권한을 취소할 수 있습니다. 앱은 파일에 대한 접근이 예기치 않게 손실되는 시나리오를 처리해야 합니다. 작업을 시작하기 전에 ContentResolver.openInputStream을 통해 접근을 확인하고 SecurityException을 올바르게 처리하는 것이 좋습니다.

코드 예제: SAF를 통한 파일 선택

SAF는 표준 Intent를 통해 시작됩니다. 코드는 최소화되어 있습니다: ACTION_OPEN_DOCUMENT로 Intent를 생성하고, MIME 유형을 지정하고, ActivityResultContracts.StartActivityForResult를 통해 시작합니다. 파일 선택 후, callback은 data.data에서 URI를 받고 이를 읽기에 사용합니다.

val pickFile = registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()
) { result ->
    result.data?.data?.let { uri ->
        val inputStream = contentResolver?.openInputStream(uri)
        // read from inputStream
    }
}

val intent = Intent(Intent.ACTION_OPEN_DOCUMENT).apply {
    addCategory(Intent.CATEGORY_OPENABLE)
    setType("application/pdf")
    putExtra(Intent.EXTRA_ALLOW_MULTIPLE, true)
}
pickFile.launch(intent)

ACTION_CREATE_DOCUMENT를 통한 파일 생성

새 파일을 쓰려면 ACTION_CREATE_DOCUMENT를 사용하세요. Intent는 MIME 유형과 EXTRA_TITLE을 통한 파일 이름을 받습니다. 폴더를 선택하고 확인한 후, 사용자는 URI를 반환하고 앱은 ContentResolver.openOutputStream을 통해 데이터를 씁니다. 시스템은 선택한 위치에 자동으로 파일을 생성합니다.

SAF 대 READ_EXTERNAL_STORAGE

SAF는 기존의 READ_EXTERNAL_STORAGE와 보안에 대한 근본적으로 다른 접근 방식에서 차이가 있습니다. 한 번에 전체 저장소에 대한 접근을 요청하는 대신 SAF는 특정 파일에만 접근을 요청합니다. 이는 공격 표면을 최소화하고 사용자 신뢰를 높입니다.

READ_EXTERNAL_STORAGE는 다른 앱의 사진과 문서를 포함하여 장치의 모든 파일에 대한 접근을 허용합니다. Android 10+에서는 이 접근 방식이 제한됩니다. 반면 SAF는 사용자가 선택한 파일에만 접근을 제공하며 각 파일에 대해 명시적 확인이 필요합니다. 배치 미디어 작업에는 MediaStore를, 개별 문서에는 SAF를 사용하세요.

SAF의 주요 단점은 각 파일을 개별적으로 선택해야 한다는 것입니다. 대량 작업(백업, 폴더 동기화)의 경우 ACTION_OPEN_DOCUMENT_TREE를 사용하여 선택한 디렉토리의 모든 파일에 대한 접근을 얻을 수 있습니다. 솔루션은 시나리오에 따라 다릅니다: SAF는 사용자 선택에 최적이고, MediaStore는 프로그래밍 방식 미디어 접근에 최적입니다.