# 文件存储

# CloudBaseStorage

# CloudBaseStorage.uploadFile

# 1. 接口描述

接口功能:上传文件到文件管理服务

接口声明:Future<void> uploadFile({String cloudPath, String filePath}) async {}

# 2. 输入参数

字段 类型 必填 说明
cloudPath String 云端文件的路径
filePath String 本地文件的路径,需要为能直接访问的路径
onProcess (int count, int total) => void 上传文件进度

# 3. 输出参数

上传文件成功时,uploadFile 接口会返回空,失败时则会抛出错误。

# 4. 示例代码

import 'package:cloudbase_core/cloudbase_core.dart';
import 'package:cloudbase_auth/cloudbase_auth.dart';
import 'package:cloudbase_storage/cloudbase_storage.dart';
import 'package:path_provider/path_provider.dart';

// 获取 flutter Document 路径
// 参考文档:https://flutter.cn/docs/cookbook/persistence/reading-writing-files
_getDocumentsPath() async {
  final directory = await getApplicationDocumentsDirectory();
  String path = directory.path;
  return path;
}

void main() async {
  CloudBaseCore core = CloudBaseCore.init({
    'env': 'your-env-id',
    'appAccess': {
      'key': 'your-app-access-key',
      'version': 'your-app-access-version'
    }
  });
  CloudBaseStorage storage = CloudBaseStorage(core);
  // 匿名登录
  CloudBaseAuth auth = CloudBaseAuth(core);
  CloudBaseAuthState authState = await auth.getAuthState();

  if (authState == null) {
      await auth.signInAnonymously();
  }

  String path = await _getDocumentsPath();

  await storage.uploadFile(
    cloudPath: 'flutter/data.txt', 
    filePath: '$path/data.txt',
    onProcess: (int count, int total) {
      // 当前进度
      print(count);
      // 总进度
      pring(total);
    }
  );
}

# CloudBaseStorage.downloadFile

# 1. 接口描述

接口功能:从云端下载文件

接口声明:Future<void> downloadFile({String fileId, String savePath}) async {}

# 2. 输入参数

字段 类型 必填 说明
fileId String 需要下载的文件 id
savePath String 保存文件的本地路径
onProcess (int count, int total) => void 下载文件进度

# 3. 输出参数

下载文件成功时,downloadFile 接口会返回空,失败时则会抛出错误。

# 4. 示例代码

import 'package:cloudbase_core/cloudbase_core.dart';
import 'package:cloudbase_auth/cloudbase_auth.dart';
import 'package:cloudbase_storage/cloudbase_storage.dart';
import 'package:path_provider/path_provider.dart';

void main async {
  // _getDocumentsPath() 同上
  String docPath = await _getDocumentsPath();

  // 本地存储文件的路径
  String savePath = '$docPath/favicon.png';

  // 初始化实例
  CloudBaseCore core = CloudBaseCore.init({
    'env': 'your-env-id',
    'appAccess': {
      'key': 'your-app-access-key',
      'version': 'your-app-access-version'
    }
  });
  CloudBaseStorage storage = CloudBaseStorage(core);
  // 匿名登录
  CloudBaseAuth auth = CloudBaseAuth(core);
  CloudBaseAuthState authState = await auth.getAuthState();

  if (authState == null) {
      await auth.signInAnonymously();
  }

  // 下载文件
  String fileId = 'cloud://xxxx';
  await storage.downloadFile(
    fileId: fileId, 
    savePath: savePath
    onProcess: (int count, int total) {
      // 当前进度
      print(count);
      // 总进度
      pring(total);
    }
  );
}

# CloudBaseStorage.deleteFiles

# 1. 接口描述

接口功能:删除云端文件

接口声明:Future<CloudBaseStorageRes<List<DeleteMetadata>>> deleteFiles(List<String> fileIdList) async {}

# 2. 输入参数

字段 类型 必填 说明
fileIdList List<String> 要删除的文件 Id 组成的数组

# 3. 输出参数

字段 类型 必填 说明
code string 状态码,操作成功则不返回
message string 错误描述
data List<dynamic> 删除结果组成的数组
requestId string 请求序列号,用于错误排查

# data

字段 类型 必填 说明
code string 删除结果,成功为 SUCCESS
fileID string 文件 ID

# 4. 示例代码

import 'package:cloudbase_core/cloudbase_core.dart';
import 'package:cloudbase_auth/cloudbase_auth.dart';
import 'package:cloudbase_storage/cloudbase_storage.dart';

void main async {
  CloudBaseCore core = CloudBaseCore.init({
    'env': 'your-env-id',
    'appAccess': {
      'key': 'your-app-access-key',
      'version': 'your-app-access-version'
    }
  });
  CloudBaseStorage storage = CloudBaseStorage(core);
  // 匿名登录
  CloudBaseAuth auth = CloudBaseAuth(core);
  CloudBaseAuthState authState = await auth.getAuthState();

  if (authState == null) {
      await auth.signInAnonymously();
  }

  String fileId = 'cloud://xxx';
  CloudBaseStorageRes<List<DeleteMetadata>> res = await storage.deleteFiles([fileId]);
  print(res.data[0]); // {'fileId': 'xxx', 'code': 'SUCCESS'}
}

# CloudBaseStorage.getFileDownloadURL

# 1. 接口描述

接口功能:获取文件下载链接,可以自定义实现下载文件的方法。

接口声明:Future<CloudBaseStorageRes<List<DownloadMetadata>>> getFileDownloadURL(List<String> fileIdList) async {}

# 2. 输入参数

字段 类型 必填 说明
fileList List<String> 要下载的文件 ID 组成的数组

# 3. 输出参数

字段 类型 必填 说明
code String 状态码,操作成功则为 SUCCESS
message String 错误描述
data List<dynamic> 存储下载链接的数组
requestId String 请求序列号,用于错误排查
# data
字段 类型 必填 说明
code string 删除结果,成功为 SUCCESS
message string 错误描述
fileId string 文件 ID
downloadUrl string 文件访问链接

# 4. 示例代码

import 'package:cloudbase_core/cloudbase_core.dart';
import 'package:cloudbase_auth/cloudbase_auth.dart';
import 'package:cloudbase_storage/cloudbase_storage.dart';

void main() async{
  CloudBaseCore core = CloudBaseCore.init({
    'env': 'your-env-id',
    'appAccess': {
      'key': 'your-app-access-key',
      'version': 'your-app-access-version'
    }
  });
  CloudBaseStorage storage = CloudBaseStorage(core);

  // 匿名登录
  CloudBaseAuth auth = CloudBaseAuth(core);
  CloudBaseAuthState authState = await auth.getAuthState();

  if (authState == null) {
      await auth.signInAnonymously();
  }

  List<String> fileIds = [
    'cloud://xxxx'
  ];
  CloudBaseStorageRes<List<DeleteMetadata>> res res = await storage.getFileDownloadURL(fileIds);
  print(res.data[0]); // {'fileId': 'xxx', 'downloadUrl': 'https://xxx'}
}

# CloudBaseStorage.getUploadMetadata

# 1. 接口描述

接口功能:获取上传文件需要的属性,可用于实现自定义上传文件的逻辑。

接口声明:Future<CloudBaseStorageRes<UploadMetadata>> getUploadMetadata(String cloudPath) async{}

# 2. 输入参数

字段 类型 必填 说明
cloudPath List<String> 云端文件路径

# 3. 输出参数

字段 类型 必填 说明
code String 状态码,操作成功则为 SUCCESS
message String 错误描述
data List<dynamic> 存储上传文件属性的数组
requestId String 请求序列号,用于错误排查
# data
字段 类型 必填 说明
code string 删除结果,成功为 SUCCESS
message string 错误描述
url string 上传文件的 url
token string 访问 token
authorization string 访问授权信息
cosFileId string 文件 id

# 4. 示例代码

import 'package:cloudbase_core/cloudbase_core.dart';
import 'package:cloudbase_auth/cloudbase_auth.dart';
import 'package:cloudbase_storage/cloudbase_storage.dart';

void main() async {
  CloudBaseCore core = CloudBaseCore.init({
    'env': 'your-env-id',
    'appAccess': {
      'key': 'your-app-access-key',
      'version': 'your-app-access-version'
    }
  });
  CloudBaseStorage storage = CloudBaseStorage(core);
  // 匿名登录
  CloudBaseAuth auth = CloudBaseAuth(core);
  CloudBaseAuthState authState = await auth.getAuthState();

  if (authState == null) {
      await auth.signInAnonymously();
  }

  CloudBaseStorageRes<UploadMetadata>> res = await storage.getUploadMetadata('test/index.txt');
  print(res.data);
}