Как загружать файлы в Cloud Storage с помощью Flutter

Cloud Storage for Firebase позволяет быстро и легко загружать файлы в сегмент Cloud Storage, предоставляемый и управляемый Firebase.

Загрузка файлов

Чтобы загрузить файл в 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) {
  // ...
}

Загрузка из строки

Вы можете загружать данные в виде необработанной строки или строки в кодировке base64, base64url или data_url с помощью метода putString(). Например, чтобы загрузить текстовую строку, закодированную как 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 для скачивания

После загрузки файла вы можете получить URL для его скачивания, вызвав метод getDownloadUrl() для Reference:

await mountainsRef.getDownloadURL();

Добавить метаданные файла

При загрузке файлов вы также можете добавить метаданные. Эти метаданные содержат типичные свойства метаданных файла, такие как contentType (обычно называемый MIME-типом). Метод putFile() автоматически определяет MIME-тип по расширению File, но вы можете переопределить его, указав contentType в метаданных. Если вы не укажете contentType и 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.