웹에서 파일 업로드

Cloud Storage를 사용하면 Firebase가 제공하고 관리하는 Google Cloud Storage 버킷에 파일을 빠르고 손쉽게 업로드할 수 있습니다.

기본 Google App Engine 앱과 Firebase는 이 버킷을 공유하므로 공개 액세스를 구성하면 새로 업로드한 App Engine 파일도 공개적으로 액세스될 수 있습니다. 인증을 설정할 때 Storage 버킷에 대한 액세스를 다시 제한해야 합니다.

파일 업로드

Cloud Storage에 파일을 업로드하려면 우선 파일 이름을 포함하여 파일의 전체 경로를 가리키는 참조를 만듭니다.

// Create a root reference
var storageRef = firebase.storage().ref();

// Create a reference to 'mountains.jpg'
var mountainsRef = storageRef.child('mountains.jpg');

// Create a reference to 'images/mountains.jpg'
var mountainImagesRef = storageRef.child('images/mountains.jpg');

// While the file names are the same, the references point to different files
mountainsRef.name === mountainImagesRef.name            // true
mountainsRef.fullPath === mountainImagesRef.fullPath    // false

Blob 또는 File에서 업로드

적절한 참조를 만들었으면 put() 메소드를 호출합니다. put()은 자바스크립트 FileBlob API를 통해 파일을 가져와서 Cloud Storage에 업로드합니다.

var file = ... // use the Blob or File API
ref.put(file).then(function(snapshot) {
  console.log('Uploaded a blob or file!');
});

바이트 배열에서 업로드

FileBlob 유형 외에도 put()Uint8Array를 Cloud Storage에 업로드할 수 있습니다.

// Uint8Array
var bytes = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x2c, 0x20, 0x77, 0x6f, 0x72, 0x6c, 0x64, 0x21]);
ref.put(bytes).then(function(snapshot) {
  console.log('Uploaded an array!');
});

문자열에서 업로드

Blob, File 또는 Uint8Array를 사용할 수 없는 경우 putString() 메소드를 사용하여 raw, base64 , base64url 또는 data_url 인코딩 문자열을 Cloud Storage에 업로드 할 수 있습니다.

// Raw string is the default if no format is provided
var message = 'This is my message.';
ref.putString(message).then(function(snapshot) {
  console.log('Uploaded a raw string!');
});

// Base64 formatted string
var message = '5b6p5Y+344GX44G+44GX44Gf77yB44GK44KB44Gn44Go44GG77yB';
ref.putString(message, 'base64').then(function(snapshot) {
  console.log('Uploaded a base64 string!');
});

// Base64url formatted string
var message = '5b6p5Y-344GX44G-44GX44Gf77yB44GK44KB44Gn44Go44GG77yB';
ref.putString(message, 'base64url').then(function(snapshot) {
  console.log('Uploaded a base64url string!');
});

// Data URL string
var message = 'data:text/plain;base64,5b6p5Y+344GX44G+44GX44Gf77yB44GK44KB44Gn44Go44GG77yB';
ref.putString(message, 'data_url').then(function(snapshot) {
  console.log('Uploaded a data_url string!');
});

put()putString()은 Promise로 사용하거나 업로드 상태를 관리 및 모니터링하는 데 사용할 수 있는 UploadTask를 반환합니다.

참조는 파일의 전체 경로를 정의하므로 업로드하는 경로가 비어 있으면 안 됩니다.

파일 메타데이터 추가

파일을 업로드할 때 파일의 메타데이터를 지정할 수도 있습니다. 이 메타데이터는 name, size, contentType(통칭 MIME 형식) 등의 일반적인 파일 메타데이터 속성을 포함합니다. Cloud Storage는 파일이 디스크에 저장된 경우 파일 확장자에서 콘텐츠 유형을 자동으로 유추하지만, 메타데이터에 contentType을 지정하면 자동으로 감지된 유형을 재정의할 수 있습니다. contentType 메타데이터를 지정하지 않았으며 파일에 확장자가 없는 경우 기본값으로 application/octet-stream 유형이 사용됩니다. 파일 메타데이터의 자세한 내용은 파일 메타데이터 사용 섹션을 참조하세요.

// Create file metadata including the content type
var metadata = {
  contentType: 'image/jpeg',
};

// Upload the file and metadata
var uploadTask = storageRef.child('images/mountains.jpg').put(file, metadata);

업로드 관리

업로드 시작과 더불어 pause(), resume(), cancel() 메소드를 사용하여 업로드를 일시중지, 재개, 취소할 수 있습니다. pause() 또는 resume()을 호출하면 pause 또는 running 상태 변경이 유발됩니다. cancel() 메소드를 호출하면 업로드가 실패하고 업로드 취소를 알리는 오류가 반환됩니다.

// Upload the file and metadata
var uploadTask = storageRef.child('images/mountains.jpg').put(file);

// Pause the upload
uploadTask.pause();

// Resume the upload
uploadTask.resume();

// Cancel the upload
uploadTask.cancel();

업로드 진행률 모니터링

업로드 중에 업로드 작업의 state_changed 관찰자에서 다음과 같은 진행 이벤트가 발생할 수 있습니다.

이벤트 유형 일반적인 용도
running 이 이벤트는 업로드가 시작되거나 재개될 때 발생하며 일반적으로 pause 이벤트와 함께 사용됩니다.
progress 이 이벤트는 Cloud Storage에 데이터가 업로드될 때 수시로 발생하며 업로드 진행률 표시기에 데이터를 입력하는 데 사용할 수 있습니다.
pause 이 이벤트는 업로드가 일시중지될 때마다 발생하며 일반적으로 running 이벤트와 함께 사용됩니다.

이벤트가 발생하면 TaskSnapshot 개체가 전달됩니다. 이 스냅샷은 이벤트 발생 시점의 작업 상태로서 변경이 불가능합니다. 이 개체는 다음과 같은 속성을 포함합니다.

속성 유형 설명
bytesTransferred Number 이 스냅샷을 생성한 시점까지 전송된 총 바이트 수입니다.
totalBytes Number 업로드가 예정된 총 바이트 수입니다.
state firebase.storage.TaskState 업로드의 현재 상태입니다.
metadata firebaseStorage.Metadata 업로드가 완료되기 전에는 서버에 전송된 메타데이터입니다. 업로드가 완료된 후에는 서버에서 다시 전송한 메타데이터입니다.
task firebaseStorage.UploadTask 스냅샷 대상 작업으로서 작업을 일시중지, 재개 또는 취소하는 데 사용할 수 있습니다.
ref firebaseStorage.Reference 이 작업이 유래된 참조입니다.

이러한 상태 변화와 TaskSnapshot의 속성을 결합하면 업로드 이벤트를 간편하고 유용하게 모니터링할 수 있습니다.

var uploadTask = storageRef.child('images/rivers.jpg').put(file);

// Register three observers:
// 1. 'state_changed' observer, called any time the state changes
// 2. Error observer, called on failure
// 3. Completion observer, called on successful completion
uploadTask.on('state_changed', function(snapshot){
  // Observe state change events such as progress, pause, and resume
  // Get task progress, including the number of bytes uploaded and the total number of bytes to be uploaded
  var progress = (snapshot.bytesTransferred / snapshot.totalBytes) * 100;
  console.log('Upload is ' + progress + '% done');
  switch (snapshot.state) {
    case firebase.storage.TaskState.PAUSED: // or 'paused'
      console.log('Upload is paused');
      break;
    case firebase.storage.TaskState.RUNNING: // or 'running'
      console.log('Upload is running');
      break;
  }
}, function(error) {
  // Handle unsuccessful uploads
}, function() {
  // Handle successful uploads on complete
  // For instance, get the download URL: https://firebasestorage.googleapis.com/...
  uploadTask.snapshot.ref.getDownloadURL().then(function(downloadURL) {
    console.log('File available at', downloadURL);
  });
});

오류 처리

업로드 시 오류가 발생하는 이유는 로컬 파일이 없는 경우, 사용자에게 원하는 파일을 업로드할 권한이 없는 경우 등 다양합니다. 오류의 자세한 내용은 문서의 오류 처리 섹션을 참조하세요.

전체 예

다음은 업로드, 진행률 모니터링 및 오류 처리에 대한 전체 예입니다.

// File or Blob named mountains.jpg
var file = ...

// Create the file metadata
var metadata = {
  contentType: 'image/jpeg'
};

// Upload file and metadata to the object 'images/mountains.jpg'
var uploadTask = storageRef.child('images/' + file.name).put(file, metadata);

// Listen for state changes, errors, and completion of the upload.
uploadTask.on(firebase.storage.TaskEvent.STATE_CHANGED, // or 'state_changed'
  function(snapshot) {
    // Get task progress, including the number of bytes uploaded and the total number of bytes to be uploaded
    var progress = (snapshot.bytesTransferred / snapshot.totalBytes) * 100;
    console.log('Upload is ' + progress + '% done');
    switch (snapshot.state) {
      case firebase.storage.TaskState.PAUSED: // or 'paused'
        console.log('Upload is paused');
        break;
      case firebase.storage.TaskState.RUNNING: // or 'running'
        console.log('Upload is running');
        break;
    }
  }, function(error) {

  // A full list of error codes is available at
  // https://firebase.google.com/docs/storage/web/handle-errors
  switch (error.code) {
    case 'storage/unauthorized':
      // User doesn't have permission to access the object
      break;

    case 'storage/canceled':
      // User canceled the upload
      break;

    ...

    case 'storage/unknown':
      // Unknown error occurred, inspect error.serverResponse
      break;
  }
}, function() {
  // Upload completed successfully, now we can get the download URL
  uploadTask.snapshot.ref.getDownloadURL().then(function(downloadURL) {
    console.log('File available at', downloadURL);
  });
});

이제 파일 업로드가 끝났으므로 Cloud Storage에서 다운로드하는 방법을 알아보세요.

다음에 대한 의견 보내기...

도움이 필요하시나요? 지원 페이지를 방문하세요.