目录

cloudCommon (Common Module)

This module provides the capability of initializing Cloud Foundation Kit.

Since: 5.0.0(12)

Modules to Import

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

init

init(options?: CloudOptions): void

Initializes Cloud Foundation Kit. This API is usually called during app startup to initialize the cloud service connection for subsequent access to features such as Cloud Functions, Cloud Storage, and Cloud DB.

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
options CloudOptions No Initialization parameters.

Error codes:

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

Error Code Error Message
401 Parameter error.

Example:

The Cloud Functions service does not require authentication. Therefore, you do not need to obtain user credentials when using this service for development. However, you need to obtain user credentials for development using Cloud Storage or Cloud DB. You can obtain user credentials using two methods. The following code provides an example of obtaining credentials through the Auth Service SDK of AppGallery Connect. For details about the complete code, please refer to method 1 in AuthProvider.getAccessToken.

import { cloudCommon } from '@kit.CloudFoundationKit';
import auth from '@hw-agconnect/auth';
import { request } from '@kit.BasicServicesKit';

let authProvider = auth.getAuthProvider(); // Call this method to obtain an authProvider when a user successfully signs in.
cloudCommon.init({
  region: cloudCommon.CloudRegion.CHINA,
  authProvider: authProvider,
  functionOptions: { timeout: 10 * 1000 },
  storageOptions: { mode: request.agent.Mode.BACKGROUND, network: request.agent.Network.ANY },
  databaseOptions: { schema: 'schema.json', traceId: 'traceId' }
});

CloudOptions

Initialization options.

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
region CloudRegion No Yes Storage location. The default value is CHINA.
authProvider AuthProvider No Yes Authentication provider.
functionOptions FunctionOptions No Yes Cloud Functions initialization settings.
storageOptions StorageOptions No Yes Cloud Storage initialization settings.
databaseOptions DatabaseOptions No Yes Cloud DB initialization settings.

CloudRegion

Enumerated storage locations.

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 Value Description
CHINA 0 Data is stored in the Chinese mainland.
GERMANY 1 Data is stored in Germany.
RUSSIA 2 Data is stored in Russia.
SINGAPORE 3 Data is stored in Singapore.

AuthProvider

Authentication provider. You can use Account Kit's API for obtaining a user-level credential to customize an AuthProvider.

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]getAccessToken

getAccessToken(isForceRefresh: boolean): Promise<string>

Obtains user credentials. 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).

System capability: SystemCapability.DeviceCloudGateway.CloudFoundation

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
isForceRefresh boolean Yes Indicates whether to forcibly refresh user credentials. true: yes; false: no.

Returns:

Type Description
Promise<string> User credentials returned through a promise. The user credentials can be generated through the API of Account Kit for obtaining a user-level credential.

Example:

  1. Use Account Kit's API for obtaining a user-level credential to obtain the refresh token, and then obtain the access token based on the refresh token to customize an AuthProvider. The sample code is as follows:
    import { cloudCommon } from '@kit.CloudFoundationKit';
import { http } from '@kit.NetworkKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

let accessToken = '';

export class MyAuthProvider implements cloudCommon.AuthProvider {
  async getAccessToken(isForceRefresh: boolean): Promise<string> {
    let data =
      'grant_type=refresh_token&client_id=xxxx&client_secret=xxxx&refresh_token=';
    let refreshToken =
      encodeURIComponent('xxxx'); // xxxx is the refresh token obtained through Account Kit's API for obtaining a user-level credential.
    // Forcibly refresh the access token that has expired.
    if (isForceRefresh) {
      data = data + refreshToken;
      try {
        let httpRequest = http.createHttp();
        let ohosOptions: http.HttpRequestOptions = {
          method: http.RequestMethod.POST,
          header: {
            'Content-Type': 'application/x-www-form-urlencoded'
          },
          extraData: data
        };
        let url = 'https://oauth-login.cloud.huawei.com/oauth2/v3/token';
        let resp = await httpRequest.request(url, ohosOptions);
        accessToken = JSON.parse(resp.result.toString()).access_token;
      } catch (err) {
        hilog.error(0x0000, 'testTag', `Failed to get accessToken, code: ${err.code}, message: ${err.message}`);
      }
    }
    return Promise.resolve(accessToken);
  }
}
  2. Complete initialization using the custom AuthProvider.
    import { cloudCommon } from '@kit.CloudFoundationKit';
import { request } from '@kit.BasicServicesKit';
import { MyAuthProvider } from 'xxx'; // xxx indicates the file path of the custom AuthProvider.

let authProvider = new MyAuthProvider();
cloudCommon.init({
  region: cloudCommon.CloudRegion.CHINA, // Enter the actual data processing location.
  authProvider: authProvider,
  functionOptions: { timeout: 10 * 1000 },
  storageOptions: { mode: request.agent.Mode.BACKGROUND, network: request.agent.Network.ANY },
  databaseOptions: { schema: 'schema.json', traceId: 'traceId' }
});

FunctionOptions

Cloud Functions initialization settings.

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
timeout number No Yes

Timeout interval for requesting a function, in milliseconds. The default interval is 70 x 1000 milliseconds.

The value range is unrestricted, and the value will be converted to the unsigned long type.

StorageOptions

Cloud Storage initialization settings.

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
mode request.agent.Mode No Yes

Task mode. 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 type. 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

DatabaseOptions

Cloud DB initialization settings.

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
schema string No Yes Complete data table structures and permissions. The schema.json configuration file is downloaded from the cloud and, by default, is obtained from the fixed rawfile directory in the project.
traceId string No Yes

Custom trace ID, used to trace requests.

The custom trace ID must contain 1 to 32 characters and can only consist of the following two types of characters:

- Letters (a to f)

- Digits (0 to 9)

If no custom trace ID is provided or the provided trace ID does not meet the requirements, the system will automatically generate one.

By default, the value is empty.