目录

cloudStorage (Cloud Storage Module)

This module provides the capabilities of uploading, downloading, querying, and deleting files through the Cloud Storage service.

Since: 5.0.0(12)

Modules to Import

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

bucket

bucket(name?: string): StorageBucket

Initializes a Cloud Storage instance.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
name string No

Name of a storage instance. The format is restricted by the cloud. Only lowercase letters, digits, and hyphens (-) are allowed. The value must start and end with a letter or digit and contain 9 to 63 characters. Two or more consecutive hyphens (-) are not allowed.

If this parameter is not specified, an asynchronous task will be initiated to query the default instance on the cloud.

If this parameter is specified, ensure that the storage instance exists on the cloud; otherwise, subsequent operations will fail due to a storage instance query error.

Returns:

Type Description
StorageBucket Cloud Storage instance.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

Error Code Error Message
401 Parameter error.

Example:

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

let bucket1: cloudStorage.StorageBucket = cloudStorage.bucket(); // When name is not specified, an asynchronous task will be initiated to query the default instance on the cloud.
hilog.info(0x0000, 'testTag', `Succeeded in creating a bucket, result: ${JSON.stringify(bucket1)}`);

/**
  * Set the Cloud Storage instance name to 'mybucket-duaf5'.
  * In this example, 'mybucket' is the storage instance name set during Cloud Storage instance creation, and 'duaf5' is a random character string generated during Cloud Storage instance creation. They are connected by a hyphen (-).
 */
let bucket2: cloudStorage.StorageBucket = cloudStorage.bucket('mybucket-duaf5');
hilog.info(0x0000, 'testTag', `Succeeded in creating a bucket, result: ${JSON.stringify(bucket2)}`);

StorageBucket

Cloud Storage instance, which provides capabilities through the Cloud Storage service, including uploading and downloading files. The instance is initialized through bucket.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

[h2]uploadFile

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

Uploads a specified file to the cloud. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
context common.BaseContext Yes App context.
parameters UploadParams Yes Upload-related parameters.

Returns:

Type Description
Promise<request.agent.Task> Promise used to return the upload task.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Error Code Error Message
201 No Internet permission.
401 Parameter error.
1008220001 Network connection error.
1008220009 Client internal error.
1008221001 Server error.

Example:

import { cloudStorage } from '@kit.CloudFoundationKit';
import { BusinessError, request } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

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

// ArkUI context.
bucket.uploadFile(context, { // context indicates the app context.
  localPath: cacheFile, // Local file path, located in the context.cacheDir directory.
  cloudPath: path // Cloud file path. The value can be in the format of File directory/File name, or simply File name.
}).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)}`);
  });

  // Start the task.
  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

Uploads a specified file to the cloud. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
context common.BaseContext Yes App context.
parameters UploadParams Yes Upload-related parameters.
callback AsyncCallback<request.agent.Task> Yes Callback. If the file is uploaded successfully, err is undefined and data is the request.agent.Task obtained; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Error Code Error Message
201 No Internet permission.
401 Parameter error.
1008220001 Network connection error.
1008220009 Client internal error.
1008221001 Server error.

Example:

import { cloudStorage } from '@kit.CloudFoundationKit';
import { BusinessError, request } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

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

// ArkUI context.
bucket.uploadFile(context, { // context indicates the app context.
  localPath: cacheFile, // Local file path, located in the context.cacheDir directory.
  cloudPath: path // Cloud file path. The value can be in the format of File directory/File name, or simply File name.
}, (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)}`);
  });

  // Start the task.
  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>

Downloads a file from the cloud to a local path. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
context common.BaseContext Yes App context.
parameters DownloadParams Yes Download-related parameters.

Returns:

Type Description
Promise<request.agent.Task> Promise used to return the download task.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Error Code Error Message
201 No Internet permission.
401 Parameter error.
1008220001 Network connection error.
1008220009 Client internal error.
1008221001 Server error.

Example:

import { cloudStorage } from '@kit.CloudFoundationKit';
import { BusinessError, request } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

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

// ArkUI context.
bucket.downloadFile(context, { // context indicates the app context.
  cloudPath: path, // Cloud file path. The value can be in the format of File directory/File name, or simply File name.
  localPath: cacheFile, // Local file path, located in the **context.cacheDir** directory.
}).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)}`);
  });

  // Start the task.
  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

Downloads a file from the cloud to a local path. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
context common.BaseContext Yes App context.
parameters DownloadParams Yes Download-related parameters.
callback AsyncCallback<request.agent.Task> Yes Callback. If the file is downloaded successfully, err is undefined and data is the request.agent.Task obtained; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Error Code Error Message
201 No Internet permission.
401 Parameter error.
1008220001 Network connection error.
1008220009 Client internal error.
1008221001 Server error.

Example:

import { cloudStorage } from '@kit.CloudFoundationKit';
import { BusinessError, request } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

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

// ArkUI context.
bucket.downloadFile(context, { // context indicates the app context.
  cloudPath: path, // Cloud file path. The value can be in the format of File directory/File name, or simply File name.
  localPath: cacheFile, // Local file path, located in the **context.cacheDir** directory.
}, (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)}`);
  });

  // Start the task.
  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>

Obtains the download URL of a cloud file. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
cloudPath string Yes Cloud file path. The value can be in the format of File directory/File name (for example, image/demo.jpg), or simply File name.

Returns:

Type Description
Promise<string> Promise used to return the cloud file download URL.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Error Code Error Message
201 No Internet permission.
401 Parameter error.
1008220001 Network connection error.
1008220009 Client internal error.
1008221001 Server error.

Example:

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

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

// cloudPath indicates the cloud file path. The value can be in the format of File directory/File name, or simply File name.
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

Obtains the download URL of a cloud file. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
cloudPath string Yes Cloud file path. The value can be in the format of File directory/File name (for example, image/demo.jpg), or simply File name.
callback AsyncCallback<string> Yes Callback. If the cloud file download URL is successfully obtained, err is undefined and data is the obtained URL; otherwise, data is an error object.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Error Code Error Message
201 No Internet permission.
401 Parameter error.
1008220001 Network connection error.
1008220009 Client internal error.
1008221001 Server error.

Example:

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

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

// cloudPath indicates the cloud file path.
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>

Deletes a cloud file. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
cloudPath string Yes Cloud file path. The value can be in the format of File directory/File name (for example, image/demo.jpg), or simply File name.

Returns:

Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Error Code Error Message
201 No Internet permission.
401 Parameter error.
1008220001 Network connection error.
1008220009 Client internal error.
1008221001 Server error.

Example:

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

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

// cloudPath indicates the cloud file path. The value can be in the format of File directory/File name, or simply File name.
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

Deletes a cloud file. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
cloudPath string Yes Cloud file path. The value can be in the format of File directory/File name (for example, image/demo.jpg), or simply File name.
callback AsyncCallback<void> Yes Callback. If the cloud file is deleted successfully, err is undefined; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Error Code Error Message
201 No Internet permission.
401 Parameter error.
1008220001 Network connection error.
1008220009 Client internal error.
1008221001 Server error.

Example:

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

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

// cloudPath indicates the cloud file path. The value can be in the format of File directory/File name, or simply File name.
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>

Obtains the cloud file list. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
cloudPath string Yes

Cloud file path.

If an empty character string ('') is passed, the list of files in the root path on the cloud will be obtained. If some_directory/ is passed, the list of files in the specified folder some_directory will be obtained.
options ListOptions No Parameters for obtaining the file list.

Returns:

Type Description
Promise<ListResults> Promise used to return the file list.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Error Code Error Message
201 No Internet permission.
401 Parameter error.
1008220001 Network connection error.
1008220009 Client internal error.
1008221001 Server error.

Example:

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

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

// Obtain the list of files in the root path on the cloud.
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}`);
});

// Obtain the list of files in the specified folder 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

Obtains the cloud file list. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
cloudPath string Yes

Cloud file path.

If an empty character string ('') is passed, the list of files in the root path on the cloud will be obtained. If some_directory/ is passed, the list of files in the specified folder some_directory will be obtained.
options ListOptions Yes Parameters for obtaining the file list.
callback AsyncCallback<ListResults> Yes Callback. If the cloud file list is obtained successfully, err is undefined and data is the ListResults obtained; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Error Code Error Message
201 No Internet permission.
401 Parameter error.
1008220001 Network connection error.
1008220009 Client internal error.
1008221001 Server error.

Example:

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

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

// Obtain the list of files in the root path on the cloud.
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)}`);
  }
});

// Obtain the list of files in the specified folder 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>

Obtains metadata of a cloud file. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
cloudPath string Yes Cloud file path. The value can be in the format of File directory/File name (for example, image/demo.jpg), or simply File name.

Returns:

Type Description
Promise<Metadata> Promise used to return metadata of the cloud file.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Error Code Error Message
201 No Internet permission.
401 Parameter error.
1008220001 Network connection error.
1008220009 Client internal error.
1008221001 Server error.

Example:

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

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

// cloudPath indicates the cloud file path. The value can be in the format of File directory/File name, or simply File name.
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

Obtains metadata of a cloud file. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
cloudPath string Yes Cloud file path. The value can be in the format of File directory/File name (for example, image/demo.jpg), or simply File name.
callback AsyncCallback<Metadata> Yes Callback. If the cloud file metadata is obtained successfully, err is undefined and data is the Metadata obtained; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Error Code Error Message
201 No Internet permission.
401 Parameter error.
1008220001 Network connection error.
1008220009 Client internal error.
1008221001 Server error.

Example:

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

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

// cloudPath indicates the cloud file path. The value can be in the format of File directory/File name, or simply File name.
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>

Sets metadata of a cloud file. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
cloudPath string Yes Cloud file path. The value can be in the format of File directory/File name (for example, image/demo.jpg), or simply File name.
metadata MetadataUpdatable Yes Updatable metadata.

Returns:

Type Description
Promise<Metadata> Promise used to return the complete metadata of the cloud file after the metadata is updated.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Error Code Error Message
201 No Internet permission.
401 Parameter error.
1008220001 Network connection error.
1008220009 Client internal error.
1008221001 Server error.

Example:

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

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

// cloudPath indicates the cloud file path. The value can be in the format of File directory/File name, or simply File name.
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

Sets metadata of a cloud file. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Required permission: ohos.permission.INTERNET

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
cloudPath string Yes Cloud file path. The value can be in the format of File directory/File name (for example, image/demo.jpg), or simply File name.
metadata MetadataUpdatable Yes Updatable metadata.
callback AsyncCallback<Metadata> Yes Callback. If the cloud file metadata is set successfully, err is undefined and data is the Metadata set; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

Error Code Error Message
201 No Internet permission.
401 Parameter error.
1008220001 Network connection error.
1008220009 Client internal error.
1008221001 Server error.

Example:

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

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

// cloudPath indicates the cloud file path. The value can be in the format of File directory/File name, or simply File name.
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

Upload-related parameters.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Name Type Read-Only Optional Description
localPath string No No Local file path. The root path is the cache directory.
cloudPath string No No Cloud file path. After a file is uploaded successfully, you can use this path to perform other operations.
metadata MetadataUpdatable No Yes File metadata.
mode request.agent.Mode No Yes

Type of the upload task. After an app is switched to the background for a period of time, background tasks are not affected but foreground tasks will fail or pause. The default value is request.agent.Mode.BACKGROUND.

- request.agent.Mode.BACKGROUND: background task

- request.agent.Mode.FOREGROUND: foreground task
network request.agent.Network No Yes

Network required by the upload task. If the network does not meet the preset condition, tasks that have not been executed will await execution, and tasks that are being executed will fail or pause. The default value is request.agent.Network.ANY.

- request.agent.Network.ANY: network of any type

- request.agent.Network.WIFI: wireless network

- request.agent.Network.CELLULAR: cellular data network

DownloadParams

Download-related parameters.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Name Type Read-Only Optional Description
localPath string No No Local file path. The root path is the cache directory.
cloudPath string No No Cloud file path. The value can be in the format of File directory/File name (for example, image/demo.jpg), or simply File name.
mode request.agent.Mode No Yes

Type of the download task. After an app is switched to the background for a period of time, background tasks are not affected but foreground tasks will fail or pause. The default value is request.agent.Mode.BACKGROUND.

- request.agent.Mode.BACKGROUND: background task

- request.agent.Mode.FOREGROUND: foreground task
overwrite boolean No Yes

Indicates whether to overwrite the local file when the file to be downloaded already exists. The default value is false.

- true: Overwrite the local file.

- false: Do not overwrite the existing file. If a file with the same name exists, the download will fail.
network request.agent.Network No Yes

Network required by the download task. If the network does not meet the preset condition, tasks that have not been executed will await execution, and tasks that are being executed will fail or pause. The default value is request.agent.Network.ANY.

- request.agent.Network.ANY: network of any type

- request.agent.Network.WIFI: wireless network

- request.agent.Network.CELLULAR: cellular data network

ListOptions

Parameters for obtaining the file list.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Name Type Read-Only Optional Description
maxResults number No Yes Maximum number of files in a list. The value ranges from 1 to 1000. By default, all files are listed. If the value is out of the range, the API will report an error.
pageMarker string No Yes Pagination marker. By default, the value is empty.

ListResults

File listing result.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Name Type Read-Only Optional Description
directories string[] No No List of cloud directories returned.
files string[] No No List of cloud files returned.
pageMarker string No Yes Pagination marker. By default, the value is empty.

MetadataUpdatable

Updatable metadata.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Name Type Read-Only Optional Description
contentType string No Yes Content-Type in the standard HTTP headers.
cacheControl string No Yes Cache-Control in the standard HTTP headers.
contentDisposition string No Yes Content-Disposition in the standard HTTP headers.
contentEncoding string No Yes Content-Encoding in the standard HTTP headers.
contentLanguage string No Yes Content-Language in the standard HTTP headers.
customMetadata Record<string, string> No Yes Custom cloud file attributes, which are case insensitive and must comply with the standard HTTP header specifications.

Metadata

Complete metadata, extended from MetadataUpdatable.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Name Type Read-Only Optional Description
name string No No Cloud file name.
size number No No Size of a cloud file, in bytes.
createTime Date No No Time when a cloud file was created, in the format yyyy-MM-ddTHH:mm:ssZ.
modifyTime Date No No Time when a cloud file was modified, in the format yyyy-MM-ddTHH:mm:ssZ.
sha256Hash string No Yes SHA-256 hash value of a cloud file.