Firebase용 Cloud Storage를 사용하면 Firebase에서 제공하고 관리하는 Cloud Storage 버킷에 파일을 빠르고 손쉽게 업로드할 수 있습니다.
파일 업로드
Cloud Storage에 파일을 업로드하려면 우선 파일 이름을 포함하여 파일의 전체 경로를 가리키는 참조를 만듭니다.
// Create a storage reference from our app
final storageRef = FirebaseStorage.instance.ref();
// Create a reference to "mountains.jpg"
final mountainsRef = storageRef.child("mountains.jpg");
// Create a reference to 'images/mountains.jpg'
final mountainImagesRef = storageRef.child("images/mountains.jpg");
// While the file names are the same, the references point to different files
assert(mountainsRef.name == mountainImagesRef.name);
assert(mountainsRef.fullPath != mountainImagesRef.fullPath);
적절한 참조를 만들었으면 putFile()
, putString()
또는 putData()
메서드를 호출하여 Cloud Storage에 파일을 업로드합니다.
Cloud Storage 버킷의 루트를 가리키는 참조로는 데이터를 업로드할 수 없습니다. 참조는 하위 URL을 가리켜야 합니다.
파일에서 업로드
파일을 업로드하려면 먼저 기기 내 위치의 절대 경로를 가져와야 합니다. 예를 들어 파일이 애플리케이션의 문서 디렉터리 내에 있으면 공식 path_provider
패키지를 사용하여 파일 경로를 생성하고 putFile()
에 전달합니다.
Directory appDocDir = await getApplicationDocumentsDirectory();
String filePath = '${appDocDir.absolute}/file-to-upload.png';
File file = File(filePath);
try {
await mountainsRef.putFile(file);
} on firebase_core.FirebaseException catch (e) {
// ...
}
문자열에서 업로드
putString()
메서드를 사용하여 데이터를 원시, base64
, base64url
또는 data_url
인코딩 문자열로 업로드할 수 있습니다. 예를 들어 데이터 URL로 인코딩된 텍스트 문자열을 업로드하려면 다음을 실행합니다.
String dataUrl = 'data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==';
try {
await mountainsRef.putString(dataUrl, format: PutStringFormat.dataUrl);
} on FirebaseException catch (e) {
// ...
}
원시 데이터 업로드
문자열이나 File
를 업로드하는 방법이 실용적이지 않은 경우 하위 수준 유형 데이터를 Uint8List
형식으로 업로드할 수 있습니다. 이러한 경우 데이터로 putData()
메서드를 호출합니다.
try {
// Upload raw data.
await mountainsRef.putData(data);
} on firebase_core.FirebaseException catch (e) {
// ...
}
다운로드 URL 가져오기
파일을 업로드한 후 Reference
에서 getDownloadUrl()
메서드를 호출하면 파일 다운로드 URL을 가져올 수 있습니다.
await mountainsRef.getDownloadURL();
파일 메타데이터 추가
파일을 업로드할 때 메타데이터를 포함할 수도 있습니다.
이 메타데이터에는 contentType
(통칭 MIME 유형)과 같은 일반적인 파일 메타데이터 속성이 포함됩니다. putFile()
메서드는 File
확장자에서 MIME 유형을 자동으로 추론하지만 메타데이터에 contentType
을 지정하면 자동으로 감지된 유형을 재정의할 수 있습니다. contentType
을 제공하지 않고 Cloud Storage가 파일 확장자에서 기본값을 추론할 수 없으면 Cloud Storage에서 application/octet-stream
을 사용합니다. 파일 메타데이터 사용을 참조하세요.
try {
await mountainsRef.putFile(file, SettableMetadata(
contentType: "image/jpeg",
));
} on firebase_core.FirebaseException catch (e) {
// ...
}
업로드 관리
업로드 시작과 더불어 pause()
, resume()
, cancel()
메서드를 사용하여 업로드를 일시중지, 재개, 취소할 수 있습니다. 일시중지 및 재개 이벤트는 각각 pause
및 progress
상태 변경을 발생시킵니다. 업로드를
취소하면 업로드 취소를 알리는 오류와 함께 업로드가
실패하게 됩니다.
final task = mountainsRef.putFile(largeFile);
// Pause the upload.
bool paused = await task.pause();
print('paused, $paused');
// Resume the upload.
bool resumed = await task.resume();
print('resumed, $resumed');
// Cancel the upload.
bool canceled = await task.cancel();
print('canceled, $canceled');
업로드 진행률 모니터링
태스크의 이벤트 스트림을 리슨하여 업로드 태스크 성공, 실패, 진행 또는 일시중지를 처리할 수 있습니다.
이벤트 유형 | 일반적인 용도 |
---|---|
TaskState.running |
데이터가 전송될 때 주기적으로 내보내며 업로드/다운로드 표시기에 데이터를 입력하는 데 사용할 수 있습니다. |
TaskState.paused |
태스크가 일시중지될 때마다 내보냅니다. |
TaskState.success |
태스크가 성공적으로 완료되면 내보냅니다. |
TaskState.canceled |
태스크가 취소될 때마다 내보냅니다. |
TaskState.error |
업로드가 실패하면 내보냅니다. 네트워크 시간 초과, 승인 실패, 작업 취소 등의 이유로 실패할 수 있습니다. |
mountainsRef.putFile(file).snapshotEvents.listen((taskSnapshot) {
switch (taskSnapshot.state) {
case TaskState.running:
// ...
break;
case TaskState.paused:
// ...
break;
case TaskState.success:
// ...
break;
case TaskState.canceled:
// ...
break;
case TaskState.error:
// ...
break;
}
});
오류 처리
업로드 시 오류가 발생하는 이유는 로컬 파일이 없는 경우, 사용자에게 원하는 파일을 업로드할 권한이 없는 경우 등 다양합니다. 오류의 자세한 내용은 문서의 오류 처리 섹션을 참조하세요.
전체 예시
다음은 업로드, 진행률 모니터링, 오류 처리를 보여주는 예시입니다.
final appDocDir = await getApplicationDocumentsDirectory();
final filePath = "${appDocDir.absolute}/path/to/mountains.jpg";
final file = File(filePath);
// Create the file metadata
final metadata = SettableMetadata(contentType: "image/jpeg");
// Create a reference to the Firebase Storage bucket
final storageRef = FirebaseStorage.instance.ref();
// Upload file and metadata to the path 'images/mountains.jpg'
final uploadTask = storageRef
.child("images/path/to/mountains.jpg")
.putFile(file, metadata);
// Listen for state changes, errors, and completion of the upload.
uploadTask.snapshotEvents.listen((TaskSnapshot taskSnapshot) {
switch (taskSnapshot.state) {
case TaskState.running:
final progress =
100.0 * (taskSnapshot.bytesTransferred / taskSnapshot.totalBytes);
print("Upload is $progress% complete.");
break;
case TaskState.paused:
print("Upload is paused.");
break;
case TaskState.canceled:
print("Upload was canceled");
break;
case TaskState.error:
// Handle unsuccessful uploads
break;
case TaskState.success:
// Handle successful uploads on complete
// ...
break;
}
});
이제 파일 업로드가 끝났으므로 Cloud Storage에서 다운로드하는 방법을 알아보세요.