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

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

Дополнительную информацию можно найти в разделе часто задаваемых вопросов.

Загрузить файлы

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

// Create a storage reference from your 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) {
  // ...
}

Загрузить первичные данные

Вы можете загружать типизированные данные более низкого уровня в виде Uint8List в тех случаях, когда загрузка строки или File нецелесообразна. В этом случае вызовите метод 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 Cloud 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.