Google은 흑인 공동체를 위한 인종 간 평등을 진전시키기 위해 노력하고 있습니다. Google에서 어떤 노력을 하고 있는지 확인하세요.

Android 저장소 사용 사례 및 권장사항

사용자가 파일을 더욱 세밀하게 제어하도록 하고 파일이 복잡해지는 것을 제한하기 위해 Android 10에는 범위 지정 저장소라는 앱의 새로운 저장소 패러다임이 도입되었습니다. 범위 지정 저장소는 앱이 기기 외부 저장소에서 파일을 저장하고 파일에 액세스하는 방식을 변경합니다. 범위 지정 저장소를 지원하도록 앱을 이전하려면 이 가이드에 설명된 일반적인 저장소 사용 사례 권장사항을 따르세요. 사용 사례는 미디어 파일 처리미디어가 아닌 파일 처리라는 두 카테고리로 구성됩니다.

Android에서 파일을 저장하고 액세스하는 방법에 관한 자세한 내용은 저장소 교육 가이드를 참조하세요.

미디어 파일 처리

이 섹션에서는 미디어 파일(동영상, 이미지, 오디오 파일)을 처리하는 일반적인 사용 사례와 앱에서 사용할 수 있는 대략적인 접근 방식을 설명합니다. 다음 표에는 이러한 각 사용 사례가 요약되어 있으며 추가 세부정보가 포함된 각 섹션으로 연결되는 링크도 포함되어 있습니다.

사용 사례 요약
모든 이미지 또는 동영상 파일 표시 모든 Android 버전에 동일한 접근 방식을 사용합니다.
특정 폴더의 이미지 또는 동영상 표시 모든 Android 버전에 동일한 접근 방식을 사용합니다.
사진의 위치 정보에 액세스 앱에서 범위 지정 저장소를 사용하는 경우 한 가지 접근 방식을 사용합니다. 앱에서 범위 지정 저장소를 선택 해제하는 경우 다른 접근 방식을 사용합니다.
단일 작업으로 여러 미디어 파일 수정 또는 삭제 Android 11에서는 한 가지 접근 방식을 사용합니다. Android 10의 경우 범위 지정 저장소를 선택 해제하고 대신 Android 9 이하의 접근 방식을 사용합니다.
이미 존재하는 단일 이미지 가져오기 모든 Android 버전에 동일한 접근 방식을 사용합니다.
단일 이미지 캡처 모든 Android 버전에 동일한 접근 방식을 사용합니다.
다른 앱과 미디어 파일 공유 모든 Android 버전에 동일한 접근 방식을 사용합니다.
특정 앱과 미디어 파일 공유 모든 Android 버전에 동일한 접근 방식을 사용합니다.
직접 파일 경로를 사용하는 코드 또는 라이브러리에서 파일에 액세스 Android 11에서는 한 가지 접근 방식을 사용합니다. Android 10의 경우 범위 지정 저장소를 선택 해제하고 대신 Android 9 이하의 접근 방식을 사용합니다.

여러 폴더의 이미지 또는 동영상 파일 표시

query() API를 사용하여 미디어 컬렉션을 쿼리합니다. 미디어 파일을 필터링 또는 정렬하려면 projection, selection, selectionArgs, sortOrder 매개변수를 조정합니다.

특정 폴더의 이미지 또는 동영상 표시

다음과 같은 접근 방식을 사용합니다.

  1. 앱 권한 요청에 설명된 권장사항에 따라 READ_EXTERNAL_STORAGE 권한을 요청합니다.
  2. 디스크에 있는 미디어 항목의 절대 파일 시스템 경로가 포함된 MediaColumns.DATA 값에 기반하여 미디어 파일을 검색합니다.

사진의 위치 정보에 액세스

앱에서 범위 지정 저장소를 사용한다면 미디어 저장소 가이드의 사진 위치 정보 섹션의 단계를 따릅니다.

단일 작업으로 여러 미디어 파일 수정 또는 삭제

앱이 실행되는 Android 버전에 기반하여 로직을 통합합니다.

Android 11에서 실행

다음과 같은 접근 방식을 사용합니다.

  1. MediaStore.createWriteRequest() 또는 MediaStore.createTrashRequest()를 사용하여 앱의 쓰기 또는 삭제 요청의 대기 중인 인텐트를 만든 다음 이 인텐트를 호출하여 파일 집합의 수정 권한을 요청하는 메시지를 사용자에게 표시합니다.
  2. 사용자의 응답을 평가합니다.

    • 권한이 부여되면 수정 또는 삭제 작업을 진행합니다.
    • 권한이 부여되지 않으면 앱의 기능에 권한이 왜 필요한지 사용자에게 설명합니다.

Android 11에서 사용할 수 있는 이러한 메서드를 사용하여 일괄 작업을 실행하는 방법을 자세히 알아보세요.

Android 10에서 실행

앱이 Android 10(API 수준 29)을 타겟팅하는 경우 범위 지정 저장소를 선택 해제하고 Android 9 이하의 접근 방식을 계속 사용하여 이 작업을 실행합니다.

Android 9 이하에서 실행

다음과 같은 접근 방식을 사용합니다.

  1. 앱 권한 요청에 설명된 권장사항에 따라 WRITE_EXTERNAL_STORAGE 권한을 요청합니다.
  2. MediaStore API를 사용하여 미디어 파일을 수정 또는 삭제합니다.

이미 존재하는 단일 이미지 가져오기

이미 존재하는 단일 이미지를 가져오려는 경우(예: 사용자 프로필의 사진으로 사용) 앱에서 작업에 자체 UI를 사용하거나 시스템 선택도구를 사용할 수 있습니다.

자체 사용자 인터페이스 표시

다음과 같은 접근 방식을 사용합니다.

  1. 앱 권한 요청에 설명된 권장사항에 따라 READ_EXTERNAL_STORAGE 권한을 요청합니다.
  2. query() API를 사용하여 미디어 컬렉션을 쿼리합니다.
  3. 앱의 맞춤 UI에 결과를 표시합니다.

시스템 선택도구 사용

사용자에게 가져올 이미지를 선택하라고 요청하는 ACTION_GET_CONTENT 인텐트를 사용합니다.

시스템 선택도구에서 사용자에게 선택하도록 표시하는 이미지 유형을 필터링하려는 경우 setType() 또는 EXTRA_MIME_TYPES를 사용하면 됩니다.

단일 이미지 캡처

앱에서 사용할 단일 이미지를 캡처하려면(예: 사용자 프로필의 사진으로 사용) ACTION_IMAGE_CAPTURE 인텐트를 사용하여 사용자에게 기기 카메라로 사진을 찍으라고 요청합니다. 시스템은 캡처된 사진을 MediaStore.Images 테이블에 저장합니다.

다른 앱과 미디어 파일 공유

insert() 메서드를 사용하여 MediaStore에 직접 기록을 추가합니다. 자세한 내용은 미디어 저장소 가이드의 항목 추가 섹션을 참조하세요.

특정 앱과 미디어 파일 공유

파일 공유 설정 가이드에 설명된 대로 Android FileProvider 구성요소를 사용합니다.

직접 파일 경로를 사용하는 코드 또는 라이브러리에서 파일에 액세스

앱이 실행되는 Android 버전에 기반하여 로직을 통합합니다.

Android 11에서 실행

다음과 같은 접근 방식을 사용합니다.

  1. 앱 권한 요청에 설명된 권장사항에 따라 READ_EXTERNAL_STORAGE 권한을 요청합니다.
  2. 직접 파일 경로를 사용하여 파일에 액세스합니다.

자세한 내용은 원시 경로를 사용하여 파일에 액세스를 참조하세요.

Android 10에서 실행

앱이 Android 10(API 수준 29)을 타겟팅하는 경우 범위 지정 저장소를 선택 해제하고 Android 9 이하의 접근 방식을 계속 사용하여 이 작업을 실행합니다.

Android 9 이하에서 실행

다음과 같은 접근 방식을 사용합니다.

  1. 앱 권한 요청에 설명된 권장사항에 따라 WRITE_EXTERNAL_STORAGE 권한을 요청합니다.
  2. 직접 파일 경로를 사용하여 파일에 액세스합니다.

미디어가 아닌 파일 처리

이 섹션에서는 미디어가 아닌 파일을 처리하는 일반적인 사용 사례와 앱에서 사용할 수 있는 대략적인 접근 방식을 설명합니다. 다음 표에는 이러한 각 사용 사례가 요약되어 있으며 추가 세부정보가 포함된 각 섹션으로 연결되는 링크도 포함되어 있습니다.

사용 사례 요약
문서 파일 열기 모든 Android 버전에 동일한 접근 방식을 사용합니다.
기존 저장소 위치의 기존 파일 이전 가능하면 파일을 범위 지정 저장소로 이전합니다. 필요한 경우 Android 10의 범위 지정 저장소를 선택 해제합니다.
다른 앱과 콘텐츠 공유 모든 Android 버전에 동일한 접근 방식을 사용합니다.
미디어가 아닌 파일 캐시 모든 Android 버전에 동일한 접근 방식을 사용합니다.

문서 파일 열기

ACTION_OPEN_DOCUMENT 인텐트를 사용하여 사용자에게 시스템 선택도구로 열 파일을 선택하라고 요청합니다. 시스템 선택도구에서 사용자에게 선택하도록 표시하는 파일 유형을 필터링하려는 경우 setType() 또는 EXTRA_MIME_TYPES를 사용하면 됩니다.

예를 들어 다음 코드를 사용하여 PDF, ODT 및 TXT 파일을 모두 찾을 수 있습니다.

Kotlin

startActivityForResult(
        Intent(Intent.ACTION_OPEN_DOCUMENT).apply {
            addCategory(Intent.CATEGORY_OPENABLE)
            type = "*/*"
            putExtra(Intent.EXTRA_MIME_TYPES, arrayOf(
                    "application/pdf", // .pdf
                    "application/vnd.oasis.opendocument.text", // .odt
                    "text/plain" // .txt
            ))
        },
        REQUEST_CODE
      )

자바

Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
        intent.addCategory(Intent.CATEGORY_OPENABLE);
        intent.setType("*/*");
        intent.putExtra(Intent.EXTRA_MIME_TYPES, new String[] {
                "application/pdf", // .pdf
                "application/vnd.oasis.opendocument.text", // .odt
                "text/plain" // .txt
        });
        startActivityForResult(intent, REQUEST_CODE);

기존 저장소 위치의 기존 파일 이전

디렉터리가 앱별 디렉터리나 공개 공유 디렉터리가 아니라면 기존 저장소 위치로 간주됩니다. 앱이 기존 저장소 위치에서 파일을 만들거나 사용하면 범위 지정 저장소를 사용하여 액세스할 수 있는 위치로 앱 파일을 이전하고 필요한 앱 변경을 실행하여 범위 지정 저장소의 파일을 사용하는 것이 좋습니다.

데이터 이전을 위해 기존 저장소 위치 액세스 권한 유지

범위 지정 저장소를 사용하여 액세스할 수 있는 위치로 앱 파일을 이전하려면 앱은 기존 저장소 위치 액세스 권한을 유지해야 합니다. 사용해야 하는 접근 방식은 앱의 타겟 API 수준에 따라 다릅니다.

앱이 Android 11을 타겟팅하는 경우
  1. 사용자가 Android 11을 타겟팅하는 앱의 새 버전으로 업그레이드할 때 앱에서 사용자의 데이터를 이전할 수 있도록 preserveLegacyExternalStorage 플래그를 사용하여 기존 저장소 모델을 유지합니다.

  2. 앱이 계속해서 Android 10 기기의 기존 저장소 위치에 있는 파일에 액세스할 수 있도록 지속적으로 범위 지정 저장소를 선택 해제합니다.

앱이 Android 10을 타겟팅하는 경우

범위 지정 저장소를 선택 해제하여 여러 Android 버전에서 앱 동작을 더 쉽게 유지할 수 있습니다.

앱 데이터 이전

앱이 이전할 준비가 되면 다음 접근 방식을 사용합니다.

  1. 앱의 작업 파일이 /sdcard/ 디렉터리에 있는지 또는 그 하위 디렉터리에 있는지 확인합니다.
  2. 비공개 앱 파일을 /sdcard/ 아래 현재 위치에서 getExternalFilesDir() 메서드에서 반환하는 디렉터리로 이동합니다.
  3. 미디어가 아닌 공유 파일을 /sdcard/ 아래 현재 위치에서 Downloads/ 디렉터리의 앱 전용 하위 디렉터리로 이동합니다.
  4. /sdcard/ 디렉터리에서 앱의 기존 저장소 디렉터리를 삭제합니다.

다른 앱과 콘텐츠 공유

앱 파일을 다른 단일 앱과 공유하려면 FileProvider를 사용하세요. 모두 서로 파일을 공유해야 하는 앱의 경우 각 앱에 콘텐츠 제공업체를 사용한 다음 앱이 컬렉션에 추가될 때 데이터를 동기화하는 것이 좋습니다.

미디어가 아닌 파일 캐시

사용해야 하는 접근 방식은 캐시해야 하는 파일 유형에 따라 다릅니다.

범위 지정 저장소를 일시적으로 선택 해제

앱이 범위 지정 저장소와 완전히 호환되기 전에 다음 메서드 중 하나를 사용하여 일시적으로 선택 해제할 수 있습니다.

  • Android 9(API 수준 28) 이하를 타겟팅합니다.
  • Android 10(API 수준 29) 이상을 타겟팅하는 경우 앱의 매니페스트 파일에서 requestLegacyExternalStorage의 값을 true로 설정합니다.

    <manifest ... >
    <!-- This attribute is "false" by default on apps targeting
         Android 10 or higher. -->
      <application android:requestLegacyExternalStorage="true" ... >
        ...
      </application>
    </manifest>
    

Android 9 이하를 타겟팅하는 앱이 범위 지정 저장소를 사용할 때 어떻게 동작하는지 테스트하려면 requestLegacyExternalStorage의 값을 false로 설정하여 동작을 선택할 수 있습니다. Android 11 기기에서 테스트하는 경우 앱 호환성 플래그를 사용하여 범위 지정 저장소 유무에 상관없이 앱 동작을 테스트할 수도 있습니다.