您当前浏览的HarmonyOS 5.0.0(API 12)文档归档不再维护，推荐您使用最新版本。详细请参考文档维护策略变更。

cloudStorage (云存储模块)

更新时间: 2025-03-17 00:08

本模块提供使用云存储对文件进行上传、下载、查询和删除等操作的能力。

起始版本：5.0.0(12)

导入模块

收起
自动换行
深色代码主题
复制
import { cloudStorage } from '@kit.CloudFoundationKit';

bucket

bucket(name?: string): StorageBucket

初始化云存储实例。

模型约束：此接口仅可在Stage模型下使用。

元服务API：从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力：SystemCapability.DeviceCloudGateway.CloudFoundation

起始版本：5.0.0(12)

参数：

展开

参数名	类型	必填	说明
name	string	否	存储实例名称。格式受云侧约束，只允许输入小写字母、数字、'-'，以字母或数字开头和结尾，长度为9-63个字符，且不能连续输入两个及以上'-'。缺省时，将启动异步任务查询云侧默认实例。非缺省时，请确保当前云侧存在该存储实例，否则后续操作将出现查询存储实例错误。

参数名

类型

必填

说明

name

string

否

存储实例名称。格式受云侧约束，只允许输入小写字母、数字、'-'，以字母或数字开头和结尾，长度为9-63个字符，且不能连续输入两个及以上'-'。

缺省时，将启动异步任务查询云侧默认实例。

非缺省时，请确保当前云侧存在该存储实例，否则后续操作将出现查询存储实例错误。

返回值：

展开

类型	说明
StorageBucket	云存储实例。

错误码：

以下错误码的详细介绍请参见ArkTS错误码。

展开

错误码ID	错误信息
401	Parameter error.

示例：

收起
自动换行
深色代码主题
复制
import { cloudStorage } from '@kit.CloudFoundationKit';

let bucket1: cloudStorage.StorageBucket = cloudStorage.bucket(); // name缺省，将启动异步任务查询云侧默认实例

/**
 * 指定云存储实例名称为'mybucket-duaf5'
 * 'mybucket'是创建云存储实例时用户输入的存储实例名称，'duaf5'是创建云存储实例时生成的随机字符串，通过符号'-'连接
 */
let bucket2: cloudStorage.StorageBucket = cloudStorage.bucket('mybucket-duaf5'); 

StorageBucket

云存储的实例，提供云存储的上传、下载等相关能力，通过bucket初始化。

模型约束：此接口仅可在Stage模型下使用。

元服务API：从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力：SystemCapability.DeviceCloudGateway.CloudFoundation

起始版本：5.0.0(12)

uploadFile

uploadFile(context: common.BaseContext, parameters: UploadParams): Promise<request.agent.Task>

上传指定文件至云侧。使用Promise异步回调。

模型约束：此接口仅可在Stage模型下使用。

元服务API：从版本5.0.0(12)开始，该接口支持在元服务中使用。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.DeviceCloudGateway.CloudFoundation

起始版本：5.0.0(12)

参数：

展开

参数名	类型	必填	说明
context	common.BaseContext	是	应用上下文。
parameters	UploadParams	是	上传相关参数。

返回值：

展开

类型	说明
Promise<request.agent.Task>	Promise对象，返回上传任务。

错误码：

以下错误码的详细介绍请参见ArkTS错误码。

展开

错误码ID	错误信息
201	No Internet permission.
401	Parameter error.
1008220001	Network connection error.
1008220009	Client internal error.
1008221001	Server error.

示例：

收起
自动换行
深色代码主题
复制
import { cloudStorage } from '@kit.CloudFoundationKit';
import { BusinessError, request } from '@kit.BasicServicesKit';

let bucket: cloudStorage.StorageBucket = cloudStorage.bucket();

// ArkUI上下文
bucket.uploadFile(getContext(this), {
  localPath: cacheFile,  // 本地文件路径
  cloudPath: path        // 云侧文件路径
}).then((task: request.agent.Task) => {
  task.on('progress', (progress) => {
    console.info(`on progress ${JSON.stringify(progress)}`);
  });
  task.on('completed', (progress) => {
    console.info(`on completed ${JSON.stringify(progress)}`);
  });
  task.on('failed', (progress) => {
    console.error(`on failed ${JSON.stringify(progress)}`);
  });
  task.on('response', (response) => {
    console.info(`on response ${JSON.stringify(response)}`);
  });

  // start task
  task.start((err: BusinessError) => {
    if (err) {
      console.error(`Failed to start the uploadFile task, Code: ${err.code}, message: ${err.message}`);
    } else {
      console.info(`Succeeded in starting a uploadFile task.`);
    }
  });
}).catch((err: BusinessError) => {
  console.error(`Upload file failed, Code: ${err.code}, message: ${err.message}`);
});

uploadFile

uploadFile(context: common.BaseContext, parameters: UploadParams, callback: AsyncCallback<request.agent.Task>): void

上传指定文件至云侧。使用callback异步回调。

模型约束：此接口仅可在Stage模型下使用。

元服务API：从版本5.0.0(12)开始，该接口支持在元服务中使用。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.DeviceCloudGateway.CloudFoundation

起始版本：5.0.0(12)

参数：

展开

参数名	类型	必填	说明
context	common.BaseContext	是	应用上下文。
parameters	UploadParams	是	上传相关参数。
callback	AsyncCallback<request.agent.Task>	是	回调函数。当上传文件成功，err为undefined，data为获取到的request.agent.Task；否则为错误对象。

错误码：

以下错误码的详细介绍请参见ArkTS错误码。

展开

错误码ID	错误信息
201	No Internet permission.
401	Parameter error.
1008220001	Network connection error.
1008220009	Client internal error.
1008221001	Server error.

示例：

收起
自动换行
深色代码主题
复制
import { cloudStorage } from '@kit.CloudFoundationKit';
import { BusinessError, request } from '@kit.BasicServicesKit';

let bucket: cloudStorage.StorageBucket = cloudStorage.bucket();

// ArkUI上下文
bucket.uploadFile(getContext(this), {
  localPath: cacheFile,  // 本地文件路径
  cloudPath: path        // 云侧文件路径
}, (err: BusinessError, task: request.agent.Task) => {
  if (err) {
    console.error(`Upload file failed! Code: ${err.code}, message: ${err.message}`);
    return;
  }
  task.on('progress', (progress) => {
    console.info(`on progress ${JSON.stringify(progress)}`);
  });
  task.on('completed', (progress) => {
    console.info(`on completed ${JSON.stringify(progress)}`);
  });
  task.on('failed', (progress) => {
    console.error(`on failed ${JSON.stringify(progress)}`);
  });
  task.on('response', (response) => {
    console.info(`on response ${JSON.stringify(response)}`);
  });

  // start task
  task.start((err: BusinessError) => {
    if (err) {
      console.error(`Failed to start the uploadFile task, Code: ${err.code}, message: ${err.message}`);
    } else {
      console.info(`Succeeded in starting a uploadFile task.`);
    }
  });
});

downloadFile

downloadFile(context: common.BaseContext, parameters: DownloadParams): Promise<request.agent.Task>

下载云侧文件至本地。使用Promise异步回调。

模型约束：此接口仅可在Stage模型下使用。

元服务API：从版本5.0.0(12)开始，该接口支持在元服务中使用。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.DeviceCloudGateway.CloudFoundation

起始版本：5.0.0(12)

参数：

展开

参数名	类型	必填	说明
context	common.BaseContext	是	应用上下文。
parameters	DownloadParams	是	下载相关参数。

返回值：

展开

类型	说明
Promise<request.agent.Task>	Promise对象，返回下载任务。

错误码：

以下错误码的详细介绍请参见ArkTS错误码。

展开

错误码ID	错误信息
201	No Internet permission.
401	Parameter error.
1008220001	Network connection error.
1008220009	Client internal error.
1008221001	Server error.

示例：

收起
自动换行
深色代码主题
复制
import { cloudStorage } from '@kit.CloudFoundationKit';
import { BusinessError, request } from '@kit.BasicServicesKit';

let bucket: cloudStorage.StorageBucket = cloudStorage.bucket();

// ArkUI上下文
bucket.downloadFile(getContext(this), {
  cloudPath: path,        // 云侧文件路径
  localPath: cacheFile,   // 保存至本地文件路径
}).then((task: request.agent.Task) => {
  task.on('progress', (progress) => {
    console.info(`on progress ${JSON.stringify(progress)}`);
  });
  task.on('completed', (progress) => {
    console.info(`on completed ${JSON.stringify(progress)}`);
  });
  task.on('failed', (progress) => {
    console.error(`on failed ${JSON.stringify(progress)}`);
  });
  task.on('response', (response) => {
    console.info(`on response ${JSON.stringify(response)}`);
  });

  // start task
  task.start((err: BusinessError) => {
    if (err) {
      console.error(`Failed to start the downloadFile task, Code: ${err.code}, message: ${err.message}`);
    } else {
      console.info(`Succeeded in starting a downloadFile task.`);
    }
  });
}).catch((err: BusinessError) => {
  console.error(`Download file failed! Code: ${err.code}, message: ${err.message}`);
});

downloadFile

downloadFile(context: common.BaseContext, parameters: DownloadParams, callback: AsyncCallback<request.agent.Task>): void

下载云侧文件至本地。使用callback异步回调。

模型约束：此接口仅可在Stage模型下使用。

元服务API：从版本5.0.0(12)开始，该接口支持在元服务中使用。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.DeviceCloudGateway.CloudFoundation

起始版本：5.0.0(12)

参数：

展开

参数名	类型	必填	说明
context	common.BaseContext	是	应用上下文。
parameters	DownloadParams	是	下载相关参数。
callback	AsyncCallback<request.agent.Task>	是	回调函数。当下载文件成功，err为undefined，data为获取到的request.agent.Task；否则为错误对象。

错误码：

以下错误码的详细介绍请参见ArkTS错误码。

展开

错误码ID	错误信息
201	No Internet permission.
401	Parameter error.
1008220001	Network connection error.
1008220009	Client internal error.
1008221001	Server error.

示例：

收起
自动换行
深色代码主题
复制
import { cloudStorage } from '@kit.CloudFoundationKit';
import { BusinessError, request } from '@kit.BasicServicesKit';

let bucket: cloudStorage.StorageBucket = cloudStorage.bucket();

// ArkUI上下文
bucket.downloadFile(getContext(this), {
  cloudPath: path,      // 云侧文件路径
  localPath: cacheFile, // 保存至本地文件路径
}, (err: BusinessError, task: request.agent.Task) => {
  if (err) {
    console.error(`Download file failed! Code: ${err.code}, message: ${err.message}`);
    return;
  }
  task.on('progress', (progress) => {
    console.info(`on progress ${JSON.stringify(progress)}`);
  });
  task.on('completed', (progress) => {
    console.info(`on completed ${JSON.stringify(progress)}`);
  });
  task.on('failed', (progress) => {
    console.error(`on failed ${JSON.stringify(progress)}`);
  });
  task.on('response', (response) => {
    console.info(`on response ${JSON.stringify(response)}`);
  });

  // start task
  task.start((err: BusinessError) => {
    if (err) {
      console.error(`Failed to start the downloadFile task, Code: ${err.code}, message: ${err.message}`);
    } else {
      console.info(`Succeeded in starting a downloadFile task.`);
    }
  });
});

getDownloadURL

getDownloadURL(cloudPath: string): Promise<string>

获取云侧文件下载地址。使用Promise异步回调。

模型约束：此接口仅可在Stage模型下使用。

元服务API：从版本5.0.0(12)开始，该接口支持在元服务中使用。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.DeviceCloudGateway.CloudFoundation

起始版本：5.0.0(12)

参数：

展开

参数名	类型	必填	说明
cloudPath	string	是	云侧文件路径。

返回值：

展开

类型	说明
Promise<string>	Promise对象，返回云侧文件下载地址。

错误码：

以下错误码的详细介绍请参见ArkTS错误码。

展开

错误码ID	错误信息
201	No Internet permission.
401	Parameter error.
1008220001	Network connection error.
1008220009	Client internal error.
1008221001	Server error.

示例：

收起
自动换行
深色代码主题
复制
import { cloudStorage } from '@kit.CloudFoundationKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bucket: cloudStorage.StorageBucket = cloudStorage.bucket();

// cloudPath是云侧文件路径
bucket.getDownloadURL('cloudPath').then((downloadURL: string) => {
  console.info(`downloadURL: ${downloadURL}`);
}).catch((err: BusinessError) => {
  console.error(`getDownloadURL failed! Code: ${err.code}, message: ${err.message}`);
});

getDownloadURL

getDownloadURL(cloudPath: string, callback: AsyncCallback<string>): void

获取云侧文件下载地址。使用callback异步回调。

模型约束：此接口仅可在Stage模型下使用。

元服务API：从版本5.0.0(12)开始，该接口支持在元服务中使用。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.DeviceCloudGateway.CloudFoundation

起始版本：5.0.0(12)

参数：

展开

参数名	类型	必填	说明
cloudPath	string	是	云侧文件路径。
callback	AsyncCallback<string>	是	回调函数，返回云侧文件下载地址。

错误码：

以下错误码的详细介绍请参见ArkTS错误码。

展开

错误码ID	错误信息
201	No Internet permission.
401	Parameter error.
1008220001	Network connection error.
1008220009	Client internal error.
1008221001	Server error.

示例：

收起
自动换行
深色代码主题
复制
import { cloudStorage } from '@kit.CloudFoundationKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bucket: cloudStorage.StorageBucket = cloudStorage.bucket();

// cloudPath是云侧文件路径
bucket.getDownloadURL('cloudPath', (err: BusinessError, downloadURL: string) => {
  if (err) {
    console.error(`getDownloadURL failed! Code: ${err.code}, message: ${err.message}`);
  } else {
    console.info(`downloadURL: ${downloadURL}`);
  }
});

deleteFile

deleteFile(cloudPath: string): Promise<void>

删除云侧文件。使用Promise异步回调。

模型约束：此接口仅可在Stage模型下使用。

元服务API：从版本5.0.0(12)开始，该接口支持在元服务中使用。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.DeviceCloudGateway.CloudFoundation

起始版本：5.0.0(12)

参数：

展开

参数名	类型	必填	说明
cloudPath	string	是	云侧文件路径。

返回值：

展开

类型	说明
Promise<void>	Promise对象。无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见ArkTS错误码。

展开

错误码ID	错误信息
201	No Internet permission.
401	Parameter error.
1008220001	Network connection error.
1008220009	Client internal error.
1008221001	Server error.

示例：

收起
自动换行
深色代码主题
复制
import { cloudStorage } from '@kit.CloudFoundationKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bucket: cloudStorage.StorageBucket = cloudStorage.bucket();

// cloudPath云侧文件路径
bucket.deleteFile('cloudPath').then(() => {
  console.info('delete file success.');
}).catch((err: BusinessError) => {
  console.error(`delete file failed! Code: ${err.code}, message: ${err.message}`);
});

deleteFile

deleteFile(cloudPath: string, callback: AsyncCallback<void>): void

删除云侧文件。使用callback异步回调。

模型约束：此接口仅可在Stage模型下使用。

元服务API：从版本5.0.0(12)开始，该接口支持在元服务中使用。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.DeviceCloudGateway.CloudFoundation

起始版本：5.0.0(12)

参数：

展开

参数名	类型	必填	说明
cloudPath	string	是	云侧文件路径。
callback	AsyncCallback<void>	是	回调函数。当删除云侧文件成功，err为undefined，否则为错误对象。

错误码：

以下错误码的详细介绍请参见ArkTS错误码。

展开

错误码ID	错误信息
201	No Internet permission.
401	Parameter error.
1008220001	Network connection error.
1008220009	Client internal error.
1008221001	Server error.

示例：

收起
自动换行
深色代码主题
复制
import { cloudStorage } from '@kit.CloudFoundationKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bucket: cloudStorage.StorageBucket = cloudStorage.bucket();

// cloudPath是云侧文件路径
bucket.deleteFile('cloudPath', (err: BusinessError) => {
  if (err) {
    console.error(`delete file failed! Code: ${err.code}, message: ${err.message}`);
  } else {
    console.info('delete file success.');
  }
});

list

list(cloudPath: string, options?: ListOptions): Promise<ListResults>

获取云侧文件列表。使用Promise异步回调。

模型约束：此接口仅可在Stage模型下使用。

元服务API：从版本5.0.0(12)开始，该接口支持在元服务中使用。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.DeviceCloudGateway.CloudFoundation

起始版本：5.0.0(12)

参数：

展开

参数名	类型	必填	说明
cloudPath	string	是	云侧文件路径。传入''（空字符串）表示获取云侧根路径下的文件列表；传入'some_directory/'表示获取指定文件夹some_directory下的文件列表。
options	ListOptions	否	列举操作的相关参数。

参数名

类型

必填

说明

cloudPath

string

是

云侧文件路径。

传入''（空字符串）表示获取云侧根路径下的文件列表；传入'some_directory/'表示获取指定文件夹some_directory下的文件列表。

options

ListOptions

否

列举操作的相关参数。

返回值：

展开

类型	说明
Promise<ListResults>	Promise对象，返回列举操作的结果。

错误码：

以下错误码的详细介绍请参见ArkTS错误码。

展开

错误码ID	错误信息
201	No Internet permission.
401	Parameter error.
1008220001	Network connection error.
1008220009	Client internal error.
1008221001	Server error.

示例：

收起
自动换行
深色代码主题
复制
import { cloudStorage } from '@kit.CloudFoundationKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bucket: cloudStorage.StorageBucket = cloudStorage.bucket();

// 获取云侧根路径下的文件列表
bucket.list('').then((result: cloudStorage.ListResults) => {
  console.info(`list result: ${JSON.stringify(result)}`);
}).catch((err: BusinessError) => {
  console.error(`list file failed! Code: ${err.code}, message: ${err.message}`);
});

// 获取指定文件夹some_directory下的文件列表
bucket.list('some_directory/').then((result: cloudStorage.ListResults) => {
  console.info(`list result: ${JSON.stringify(result)}`);
}).catch((err: BusinessError) => {
  console.error(`list file failed! Code: ${err.code}, message: ${err.message}`);
});

list

list(cloudPath: string, options: ListOptions, callback: AsyncCallback<ListResults>): void

获取云侧文件列表。使用callback异步回调。

模型约束：此接口仅可在Stage模型下使用。

元服务API：从版本5.0.0(12)开始，该接口支持在元服务中使用。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.DeviceCloudGateway.CloudFoundation

起始版本：5.0.0(12)

参数：

展开

参数名	类型	必填	说明
cloudPath	string	是	云侧文件路径。传入''（空字符串）表示获取云侧根路径下的文件列表；传入'some_directory/'表示获取指定文件夹some_directory下的文件列表。
options	ListOptions	是	列举操作的相关参数。
callback	AsyncCallback<ListResults>	是	回调函数。当获取云侧文件列表成功，err为undefined，data为获取到的ListResults；否则为错误对象。

参数名

类型

必填

说明

cloudPath

string

是

云侧文件路径。

传入''（空字符串）表示获取云侧根路径下的文件列表；传入'some_directory/'表示获取指定文件夹some_directory下的文件列表。

options

ListOptions

是

列举操作的相关参数。

callback

AsyncCallback<ListResults>

是

回调函数。当获取云侧文件列表成功，err为undefined，data为获取到的ListResults；否则为错误对象。

错误码：

以下错误码的详细介绍请参见ArkTS错误码。

展开

错误码ID	错误信息
201	No Internet permission.
401	Parameter error.
1008220001	Network connection error.
1008220009	Client internal error.
1008221001	Server error.

示例：

收起
自动换行
深色代码主题
复制
import { cloudStorage } from '@kit.CloudFoundationKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bucket: cloudStorage.StorageBucket = cloudStorage.bucket();

// 获取云侧根路径下的文件列表
bucket.list('', {}, (err: BusinessError, result: cloudStorage.ListResults) => {
  if (err) {
    console.error(`list file failed! Code: ${err.code}, message: ${err.message}`);
  } else {
    console.info(`list result: ${JSON.stringify(result)}`);
  }
});

// 获取指定文件夹some_directory下的文件列表
bucket.list('some_directory/', {}, (err: BusinessError, result: cloudStorage.ListResults) => {
  if (err) {
    console.error(`list file failed! Code: ${err.code}, message: ${err.message}`);
  } else {
    console.info(`list result: ${JSON.stringify(result)}`);
  }
});

getMetadata

getMetadata(cloudPath: string): Promise<Metadata>

获取云侧文件的元数据。使用Promise异步回调。

模型约束：此接口仅可在Stage模型下使用。

元服务API：从版本5.0.0(12)开始，该接口支持在元服务中使用。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.DeviceCloudGateway.CloudFoundation

起始版本：5.0.0(12)

参数：

展开

参数名	类型	必填	说明
cloudPath	string	是	云侧文件路径。

返回值：

展开

类型	说明
Promise<Metadata>	Promise对象，返回云侧文件的元数据信息。

错误码：

以下错误码的详细介绍请参见ArkTS错误码。

展开

错误码ID	错误信息
201	No Internet permission.
401	Parameter error.
1008220001	Network connection error.
1008220009	Client internal error.
1008221001	Server error.

示例：

收起
自动换行
深色代码主题
复制
import { cloudStorage } from '@kit.CloudFoundationKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bucket: cloudStorage.StorageBucket = cloudStorage.bucket();

// cloudPath是云侧文件路径
bucket.getMetadata('cloudPath').then((data: cloudStorage.Metadata) => {
  console.info(`Metadata : ${JSON.stringify(data)}`);
}).catch((err: BusinessError) => {
  console.error(`getMetadata failed! Code: ${err.code}, message: ${err.message}`);
});

getMetadata

getMetadata(cloudPath: string, callback: AsyncCallback<Metadata>): void

获取云侧文件的元数据。使用callback异步回调。

模型约束：此接口仅可在Stage模型下使用。

元服务API：从版本5.0.0(12)开始，该接口支持在元服务中使用。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.DeviceCloudGateway.CloudFoundation

起始版本：5.0.0(12)

参数：

展开

参数名	类型	必填	说明
cloudPath	string	是	云侧文件路径。
callback	AsyncCallback<Metadata>	是	回调函数。当获取云侧文件的元数据成功，err为undefined，data为获取到的Metadata；否则为错误对象。

错误码：

以下错误码的详细介绍请参见ArkTS错误码。

展开

错误码ID	错误信息
201	No Internet permission.
401	Parameter error.
1008220001	Network connection error.
1008220009	Client internal error.
1008221001	Server error.

示例：

收起
自动换行
深色代码主题
复制
import { cloudStorage } from '@kit.CloudFoundationKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bucket: cloudStorage.StorageBucket = cloudStorage.bucket();

// cloudPath是云侧文件路径
bucket.getMetadata('cloudPath', (err: BusinessError, data: cloudStorage.Metadata) => {
  if (err) {
    console.error(`getMetadata failed! Code: ${err.code}, message: ${err.message}`);
  } else {
    console.info(`Metadata: ${JSON.stringify(data)}`);
  }
});

setMetadata

setMetadata(cloudPath: string, metadata: MetadataUpdatable): Promise<Metadata>

设置云侧文件的元数据。使用Promise异步回调。

模型约束：此接口仅可在Stage模型下使用。

元服务API：从版本5.0.0(12)开始，该接口支持在元服务中使用。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.DeviceCloudGateway.CloudFoundation

起始版本：5.0.0(12)

参数：

展开

参数名	类型	必填	说明
cloudPath	string	是	云侧文件路径。
metadata	MetadataUpdatable	是	可更新参数的元数据信息。

返回值：

展开

类型	说明
Promise<Metadata>	Promise对象，返回云侧文件更新后的完整元数据信息。

错误码：

以下错误码的详细介绍请参见ArkTS错误码。

展开

错误码ID	错误信息
201	No Internet permission.
401	Parameter error.
1008220001	Network connection error.
1008220009	Client internal error.
1008221001	Server error.

示例：

收起
自动换行
深色代码主题
复制
import { cloudStorage } from '@kit.CloudFoundationKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bucket: cloudStorage.StorageBucket = cloudStorage.bucket();

// cloudPath是云侧文件路径
bucket.setMetadata('cloudPath', {
  customMetadata: {
    key1: "value1",
    key2: "value2"
  }
}).then((data: cloudStorage.Metadata) => {
  console.info(`Metadata : ${JSON.stringify(data)}`);
}).catch((err: BusinessError) => {
  console.error(`setMetadata failed! Code: ${err.code}, message: ${err.message}`);
});

setMetadata

setMetadata(cloudPath: string, metadata: MetadataUpdatable, callback: AsyncCallback<Metadata>): void

设置云侧文件的元数据。使用callback异步回调。

模型约束：此接口仅可在Stage模型下使用。

元服务API：从版本5.0.0(12)开始，该接口支持在元服务中使用。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.DeviceCloudGateway.CloudFoundation

起始版本：5.0.0(12)

参数：

展开

参数名	类型	必填	说明
cloudPath	string	是	云侧文件路径。
metadata	MetadataUpdatable	是	可更新参数的元数据信息。
callback	AsyncCallback<Metadata>	是	回调函数。当设置云侧文件的元数据成功，err为undefined，data为设置的Metadata；否则为错误对象。

错误码：

以下错误码的详细介绍请参见ArkTS错误码。

展开

错误码ID	错误信息
201	No Internet permission.
401	Parameter error.
1008220001	Network connection error.
1008220009	Client internal error.
1008221001	Server error.

示例：

收起
自动换行
深色代码主题
复制
import { cloudStorage } from '@kit.CloudFoundationKit';
import { BusinessError } from '@kit.BasicServicesKit';

let bucket: cloudStorage.StorageBucket = cloudStorage.bucket();

// cloudPath是云侧文件路径
bucket.setMetadata('cloudPath', {
  customMetadata: {
    key1: "value1",
    key2: "value2"
  }
}, (err: BusinessError, data: cloudStorage.Metadata) => {
  if (err) {
    console.error(`setMetadata failed! Code: ${err.code}, message: ${err.message}`);
  } else {
    console.info(`Metadata: ${JSON.stringify(data)}`);
  }
});

UploadParams

上传相关参数。

模型约束：此接口仅可在Stage模型下使用。

元服务API：从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.DeviceCloudGateway.CloudFoundation

起始版本：5.0.0(12)

展开

名称	类型	只读	可选	说明
localPath	string	否	否	本地文件路径，根路径为cache目录。
cloudPath	string	否	否	云侧文件路径，上传成功后，可以使用该路径进行其他操作。
metadata	MetadataUpdatable	否	是	文件元数据信息。
mode	request.agent.Mode	否	是	上传任务类型，前端任务在应用切换到后台一段时间后失败/暂停；后台任务不受影响。默认为request.agent.Mode.BACKGROUND。 request.agent.Mode.BACKGROUND：后台任务。 request.agent.Mode.FOREGROUND：前端任务。
network	request.agent.Network	否	是	上传任务的网络配置，网络不满足设置条件时，未执行的任务等待执行，执行中的任务失败/暂停。默认为request.agent.Network.ANY。 request.agent.Network.ANY：不限网络类型。 request.agent.Network.WIFI：无线网络。 request.agent.Network.CELLULAR：蜂窝数据网络。

DownloadParams

下载相关参数。

模型约束：此接口仅可在Stage模型下使用。

元服务API：从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.DeviceCloudGateway.CloudFoundation

起始版本：5.0.0(12)

展开

名称	类型	只读	可选	说明
localPath	string	否	否	本地文件路径，根路径为cache目录。
cloudPath	string	否	否	云侧文件路径。
mode	request.agent.Mode	否	是	下载任务类型，前端任务在应用切换到后台一段时间后失败/暂停；后台任务不受影响。默认为request.agent.Mode.BACKGROUND。 request.agent.Mode.BACKGROUND：后台任务。 request.agent.Mode.FOREGROUND：前端任务。
overwrite	boolean	否	是	当本地文件已存在时，是否覆盖本地文件，默认false。 true：覆盖本地文件。 false：不覆盖，若存在同名文件则下载失败。
network	request.agent.Network	否	是	下载任务的网络配置，网络不满足设置条件时，未执行的任务等待执行，执行中的任务失败/暂停。默认为request.agent.Network.ANY。 request.agent.Network.ANY：不限网络类型。 request.agent.Network.WIFI：无线网络。 request.agent.Network.CELLULAR：蜂窝数据网络。

ListOptions

列举操作的相关参数。

模型约束：此接口仅可在Stage模型下使用。

元服务API：从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.DeviceCloudGateway.CloudFoundation

起始版本：5.0.0(12)

展开

名称	类型	只读	可选	说明
maxResults	number	否	是	列举文件的最大数量，取值范围1-1000，默认则列举所有文件。
pageMarker	string	否	是	分页标识。

ListResults

列举操作的结果。

模型约束：此接口仅可在Stage模型下使用。

元服务API：从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.DeviceCloudGateway.CloudFoundation

起始版本：5.0.0(12)

展开

名称	类型	只读	可选	说明
directories	string[]	否	否	列举操作返回的云侧目录列表。
files	string[]	否	否	列举操作返回的云侧文件列表。
pageMarker	string	否	是	分页标识。

MetadataUpdatable

可更新参数的元数据信息。

模型约束：此接口仅可在Stage模型下使用。

元服务API：从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.DeviceCloudGateway.CloudFoundation

起始版本：5.0.0(12)

展开

名称	类型	只读	可选	说明
contentType	string	否	是	标准HTTP头部的Content-Type。
cacheControl	string	否	是	标准HTTP头部的Cache-Control。
contentDisposition	string	否	是	标准HTTP头部的Content-Disposition。
contentEncoding	string	否	是	标准HTTP头部的Content-Encoding。
contentLanguage	string	否	是	标准HTTP头部的Content-Language。
customMetadata	Record<string, string>	否	是	自定义的云侧文件属性，不区分大小写，并且需要符合标准HTTP头部的规范。

Metadata

完整的元数据信息，继承自MetadataUpdatable。

模型约束：此接口仅可在Stage模型下使用。

元服务API：从版本5.0.0(12)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.DeviceCloudGateway.CloudFoundation

起始版本：5.0.0(12)

展开

名称	类型	只读	可选	说明
name	string	否	否	云侧文件名称。
size	number	否	否	云侧文件大小，单位为字节。
createTime	Date	否	否	云侧文件创建时间，格式：yyyy-MM-ddTHH:mm:ssZ。
modifyTime	Date	否	否	云侧文件修改时间，格式：yyyy-MM-ddTHH:mm:ssZ。
sha256Hash	string	否	是	云侧文件的SHA256信息。

cloudFunction (云函数模块)

cloudDatabase (云数据库模块)