cloudStorage (云存储模块)

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

起始版本: 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个字符,且不能连续输入两个及以上'-'。

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

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

返回值:

类型 说明
StorageBucket 云存储实例。

错误码:

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

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

示例:

import { cloudStorage } from '@kit.CloudFoundationKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

let bucket1: cloudStorage.StorageBucket = cloudStorage.bucket(); // name缺省,将启动异步任务查询云侧默认实例
hilog.info(0x0000, 'testTag', `Succeeded in creating a bucket, result: ${JSON.stringify(bucket1)}`);

/**
 * 指定云存储实例名称为'mybucket-duaf5'
 * 'mybucket'是创建云存储实例时用户输入的存储实例名称,'duaf5'是创建云存储实例时生成的随机字符串,通过符号'-'连接
 */
let bucket2: cloudStorage.StorageBucket = cloudStorage.bucket('mybucket-duaf5');
hilog.info(0x0000, 'testTag', `Succeeded in creating a bucket, result: ${JSON.stringify(bucket2)}`);

StorageBucket

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

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

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

系统能力: SystemCapability.DeviceCloudGateway.CloudFoundation

起始版本: 5.0.0(12)

[h2]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 API错误码。

错误码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';
import { hilog } from '@kit.PerformanceAnalysisKit';

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

// ArkUI上下文
bucket.uploadFile(context, { // context表示应用上下文
  localPath: cacheFile, // 本地文件路径(context.cacheDir目录下的文件路径)
  cloudPath: path // 云侧文件路径,支持传入“文件目录/文件名”,或仅传入文件名
}).then((task: request.agent.Task) => {
  task.on('progress', (progress) => {
    hilog.info(0x0000, 'testTag', `on progress ${JSON.stringify(progress)}`);
  });
  task.on('completed', (progress) => {
    hilog.info(0x0000, 'testTag', `on completed ${JSON.stringify(progress)}`);
  });
  task.on('failed', (progress) => {
    hilog.error(0x0000, 'testTag', `on failed ${JSON.stringify(progress)}`);
  });
  task.on('response', (response) => {
    hilog.info(0x0000, 'testTag', `on response ${JSON.stringify(response)}`);
  });

  // 启动任务
  task.start((err: BusinessError) => {
    if (err) {
      hilog.error(0x0000, 'testTag', `Failed to start a file upload task, code: ${err.code}, message: ${err.message}`);
    } else {
      hilog.info(0x0000, 'testTag', `Succeeded in starting a file upload task.`);
    }
  });
}).catch((err: BusinessError) => {
  hilog.error(0x0000, 'testTag', `Failed to upload file, code: ${err.code}, message: ${err.message}`);
});

[h2]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 API错误码。

错误码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';
import { hilog } from '@kit.PerformanceAnalysisKit';

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

// ArkUI上下文
bucket.uploadFile(context, { // context表示应用上下文
  localPath: cacheFile, // 本地文件路径(context.cacheDir目录下的文件路径)
  cloudPath: path // 云侧文件路径,支持传入“文件目录/文件名”,或仅传入文件名
}, (err: BusinessError, task: request.agent.Task) => {
  if (err) {
    hilog.error(0x0000, 'testTag', `Failed to upload file, code: ${err.code}, message: ${err.message}`);
    return;
  }
  task.on('progress', (progress) => {
    hilog.info(0x0000, 'testTag', `on progress ${JSON.stringify(progress)}`);
  });
  task.on('completed', (progress) => {
    hilog.info(0x0000, 'testTag', `on completed ${JSON.stringify(progress)}`);
  });
  task.on('failed', (progress) => {
    hilog.error(0x0000, 'testTag', `on failed ${JSON.stringify(progress)}`);
  });
  task.on('response', (response) => {
    hilog.info(0x0000, 'testTag', `on response ${JSON.stringify(response)}`);
  });

  // 启动任务
  task.start((err: BusinessError) => {
    if (err) {
      hilog.error(0x0000, 'testTag', `Failed to start a file upload task, code: ${err.code}, message: ${err.message}`);
    } else {
      hilog.info(0x0000, 'testTag', `Succeeded in starting a file upload task.`);
    }
  });
});

[h2]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 API错误码。

错误码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';
import { hilog } from '@kit.PerformanceAnalysisKit';

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

// ArkUI上下文
bucket.downloadFile(context, { // context表示应用上下文
  cloudPath: path, // 云侧文件路径,支持传入“文件目录/文件名”,或仅传入文件名
  localPath: cacheFile, // 保存至本地文件路径(context.cacheDir目录下的文件路径)
}).then((task: request.agent.Task) => {
  task.on('progress', (progress) => {
    hilog.info(0x0000, 'testTag', `on progress ${JSON.stringify(progress)}`);
  });
  task.on('completed', (progress) => {
    hilog.info(0x0000, 'testTag', `on completed ${JSON.stringify(progress)}`);
  });
  task.on('failed', (progress) => {
    hilog.error(0x0000, 'testTag', `on failed ${JSON.stringify(progress)}`);
  });
  task.on('response', (response) => {
    hilog.info(0x0000, 'testTag', `on response ${JSON.stringify(response)}`);
  });

  // 启动任务
  task.start((err: BusinessError) => {
    if (err) {
      hilog.error(0x0000, 'testTag',
        `Failed to start a file download task, code: ${err.code}, message: ${err.message}`);
    } else {
      hilog.info(0x0000, 'testTag', `Succeeded in starting a file download task.`);
    }
  });
}).catch((err: BusinessError) => {
  hilog.error(0x0000, 'testTag', `Failed to download file, code: ${err.code}, message: ${err.message}`);
});

[h2]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 API错误码。

错误码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';
import { hilog } from '@kit.PerformanceAnalysisKit';

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

// ArkUI上下文
bucket.downloadFile(context, { // context表示应用上下文
  cloudPath: path, // 云侧文件路径,支持传入“文件目录/文件名”,或仅传入文件名
  localPath: cacheFile, // 保存至本地文件路径(context.cacheDir目录下的文件路径)
}, (err: BusinessError, task: request.agent.Task) => {
  if (err) {
    hilog.error(0x0000, 'testTag', `Failed to download file, code: ${err.code}, message: ${err.message}`);
    return;
  }
  task.on('progress', (progress) => {
    hilog.info(0x0000, 'testTag', `on progress ${JSON.stringify(progress)}`);
  });
  task.on('completed', (progress) => {
    hilog.info(0x0000, 'testTag', `on completed ${JSON.stringify(progress)}`);
  });
  task.on('failed', (progress) => {
    hilog.error(0x0000, 'testTag', `on failed ${JSON.stringify(progress)}`);
  });
  task.on('response', (response) => {
    hilog.info(0x0000, 'testTag', `on response ${JSON.stringify(response)}`);
  });

  // 启动任务
  task.start((err: BusinessError) => {
    if (err) {
      hilog.error(0x0000, 'testTag',
        `Failed to start a file download task, code: ${err.code}, message: ${err.message}`);
    } else {
      hilog.info(0x0000, 'testTag', `Succeeded in starting a file download task.`);
    }
  });
});

[h2]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 是 云侧文件路径。支持传入“文件目录/文件名”(如“image/demo.jpg”),或仅传入文件名。

返回值:

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

错误码:

以下错误码的详细介绍请参见通用错误码和ArkTS API错误码。

错误码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';
import { hilog } from '@kit.PerformanceAnalysisKit';

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

// cloudPath是云侧文件路径,支持传入“文件目录/文件名”,或仅传入文件名
bucket.getDownloadURL('cloudPath').then((downloadURL: string) => {
  hilog.info(0x0000, 'testTag', `Succeeded in getting download URL: ${downloadURL}`);
}).catch((err: BusinessError) => {
  hilog.error(0x0000, 'testTag', `Failed to get download URL, code: ${err.code}, message: ${err.message}`);
});

[h2]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 是 云侧文件路径。支持传入“文件目录/文件名”(如“image/demo.jpg”),或仅传入文件名。
callback AsyncCallback<string> 是 回调函数。当获取云侧文件下载地址成功,err为undefined,data为获取到的云侧文件下载地址;否则为错误对象。

错误码:

以下错误码的详细介绍请参见通用错误码和ArkTS API错误码。

错误码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';
import { hilog } from '@kit.PerformanceAnalysisKit';

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

// cloudPath是云侧文件路径
bucket.getDownloadURL('cloudPath', (err: BusinessError, downloadURL: string) => {
  if (err) {
    hilog.error(0x0000, 'testTag', `Failed to get download URL, code: ${err.code}, message: ${err.message}`);
  } else {
    hilog.info(0x0000, 'testTag', `Succeeded in getting download URL: ${downloadURL}`);
  }
});

[h2]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 是 云侧文件路径。支持传入“文件目录/文件名”(如“image/demo.jpg”),或仅传入文件名。

返回值:

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

错误码:

以下错误码的详细介绍请参见通用错误码和ArkTS API错误码。

错误码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';
import { hilog } from '@kit.PerformanceAnalysisKit';

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

// cloudPath云侧文件路径,支持传入“文件目录/文件名”,或仅传入文件名。
bucket.deleteFile('cloudPath').then(() => {
  hilog.info(0x0000, 'testTag', `Succeeded in deleting file.`);
}).catch((err: BusinessError) => {
  hilog.error(0x0000, 'testTag', `Failed to delete file, code: ${err.code}, message: ${err.message}`);
});

[h2]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 是 云侧文件路径。支持传入“文件目录/文件名”(如“image/demo.jpg”),或仅传入文件名。
callback AsyncCallback<void> 是 回调函数。当删除云侧文件成功,err为undefined,否则为错误对象。

错误码:

以下错误码的详细介绍请参见通用错误码和ArkTS API错误码。

错误码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';
import { hilog } from '@kit.PerformanceAnalysisKit';

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

// cloudPath是云侧文件路径,支持传入“文件目录/文件名”,或仅传入文件名。
bucket.deleteFile('cloudPath', (err: BusinessError) => {
  if (err) {
    hilog.error(0x0000, 'testTag', `Failed to delete file, Code: ${err.code}, message: ${err.message}`);
  } else {
    hilog.info(0x0000, 'testTag', `Succeeded in deleting file.`);
  }
});

[h2]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 否 列举操作的相关参数。

返回值:

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

错误码:

以下错误码的详细介绍请参见通用错误码和ArkTS API错误码。

错误码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';
import { hilog } from '@kit.PerformanceAnalysisKit';

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

// 获取云侧根路径下的文件列表
bucket.list('').then((result: cloudStorage.ListResults) => {
  hilog.info(0x0000, 'testTag', `Succeeded in listing files, result: ${JSON.stringify(result)}`);
}).catch((err: BusinessError) => {
  hilog.error(0x0000, 'testTag', `Failed to list files, code: ${err.code}, message: ${err.message}`);
});

// 获取指定文件夹some_directory下的文件列表
bucket.list('some_directory/').then((result: cloudStorage.ListResults) => {
  hilog.info(0x0000, 'testTag', `Succeeded in listing files, result: ${JSON.stringify(result)}`);
}).catch((err: BusinessError) => {
  hilog.error(0x0000, 'testTag', `Failed to list files, code: ${err.code}, message: ${err.message}`);
});

[h2]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;否则为错误对象。

错误码:

以下错误码的详细介绍请参见通用错误码和ArkTS API错误码。

错误码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';
import { hilog } from '@kit.PerformanceAnalysisKit';

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

// 获取云侧根路径下的文件列表
bucket.list('', { maxResults: 10, pageMarker: 'test' }, (err: BusinessError, result: cloudStorage.ListResults) => {
  if (err) {
    hilog.error(0x0000, 'testTag', `Failed to list files, code: ${err.code}, message: ${err.message}`);
  } else {
    hilog.info(0x0000, 'testTag', `Succeeded in listing files, result: ${JSON.stringify(result)}`);
  }
});

// 获取指定文件夹some_directory下的文件列表
bucket.list('some_directory/', {}, (err: BusinessError, result: cloudStorage.ListResults) => {
  if (err) {
    hilog.error(0x0000, 'testTag', `Failed to list files, code: ${err.code}, message: ${err.message}`);
  } else {
    hilog.info(0x0000, 'testTag', `Succeeded in listing files, result: ${JSON.stringify(result)}`);
  }
});

[h2]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 是 云侧文件路径。支持传入“文件目录/文件名”(如“image/demo.jpg”),或仅传入文件名。

返回值:

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

错误码:

以下错误码的详细介绍请参见通用错误码和ArkTS API错误码。

错误码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';
import { hilog } from '@kit.PerformanceAnalysisKit';

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

// cloudPath是云侧文件路径,支持传入“文件目录/文件名”,或仅传入文件名。
bucket.getMetadata('cloudPath').then((data: cloudStorage.Metadata) => {
  hilog.info(0x0000, 'testTag', `Succeeded in getting metadata: ${JSON.stringify(data)}`);
}).catch((err: BusinessError) => {
  hilog.error(0x0000, 'testTag', `Failed to get metadata, code: ${err.code}, message: ${err.message}`);
});

[h2]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 是 云侧文件路径。支持传入“文件目录/文件名”(如“image/demo.jpg”),或仅传入文件名。
callback AsyncCallback<Metadata> 是 回调函数。当获取云侧文件的元数据成功,err为undefined,data为获取到的Metadata;否则为错误对象。

错误码:

以下错误码的详细介绍请参见通用错误码和ArkTS API错误码。

错误码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';
import { hilog } from '@kit.PerformanceAnalysisKit';

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

// cloudPath是云侧文件路径,支持传入“文件目录/文件名”,或仅传入文件名。
bucket.getMetadata('cloudPath', (err: BusinessError, data: cloudStorage.Metadata) => {
  if (err) {
    hilog.error(0x0000, 'testTag', `Failed to get metadata, code: ${err.code}, message: ${err.message}`);
  } else {
    hilog.info(0x0000, 'testTag', `Succeeded in getting metadata: ${JSON.stringify(data)}`);
  }
});

[h2]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 是 云侧文件路径。支持传入“文件目录/文件名”(如“image/demo.jpg”),或仅传入文件名。
metadata MetadataUpdatable 是 可更新参数的元数据信息。

返回值:

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

错误码:

以下错误码的详细介绍请参见通用错误码和ArkTS API错误码。

错误码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';
import { hilog } from '@kit.PerformanceAnalysisKit';

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

// cloudPath是云侧文件路径,支持传入“文件目录/文件名”,或仅传入文件名。
bucket.setMetadata('cloudPath', {
  customMetadata: {
    key1: 'value1',
    key2: 'value2'
  }
}).then((data: cloudStorage.Metadata) => {
  hilog.info(0x0000, 'testTag', `Succeeded in setting metadata: ${JSON.stringify(data)}`);
}).catch((err: BusinessError) => {
  hilog.error(0x0000, 'testTag', `Failed to set metadata, code: ${err.code}, message: ${err.message}`);
});

[h2]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 是 云侧文件路径。支持传入“文件目录/文件名”(如“image/demo.jpg”),或仅传入文件名。
metadata MetadataUpdatable 是 可更新参数的元数据信息。
callback AsyncCallback<Metadata> 是 回调函数。当设置云侧文件的元数据成功,err为undefined,data为设置的Metadata;否则为错误对象。

错误码:

以下错误码的详细介绍请参见通用错误码和ArkTS API错误码。

错误码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';
import { hilog } from '@kit.PerformanceAnalysisKit';

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

// cloudPath是云侧文件路径,支持传入“文件目录/文件名”,或仅传入文件名。
bucket.setMetadata('cloudPath', {
  customMetadata: {
    key1: 'value1',
    key2: 'value2'
  }
}, (err: BusinessError, data: cloudStorage.Metadata) => {
  if (err) {
    hilog.error(0x0000, 'testTag', `Failed to set metadata, code: ${err.code}, message: ${err.message}`);
  } else {
    hilog.info(0x0000, 'testTag', `Succeeded in setting 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 否 否 云侧文件路径。支持传入“文件目录/文件名”(如“image/demo.jpg”),或仅传入文件名。
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信息。