AppGallery Connect Cloud Server SDK for NodeJS

Table of Contents

• Introduction
• Installation
• Prerequisites
• Usage
  • Initializing the SDK
  • Auth Service
  • Cloud Functions
  • Cloud DB
    • Initializing Cloud DB
    • Writing Data
    • Querying Data
  • Cloud Storage
• Constraints and Limitations
• License

Introduction

AppGallery Connect provides in-depth support for application development. The platform offers variety of cloud services which supports mainstream application platforms and helps developers quickly and efficiently build applications.

The AGC Cloud-Server NodeJS SDK allows developers to access the AGC services from their server-side applications developed with NodeJS.

SDK Provides support for multiple AGC cloud services:

• Authentication service: helps applications quickly build a secure and reliable user authentication system.
• Cloud function: provides a serverless code development and running platform.
• Cloud database: Provides collaborative management of device-cloud data.
• Cloud storage: helps applications store images, audios, and videos, and provides high-quality upload, download, and sharing capabilities.

Learn More (ZH)

Learn More (EN)

Installation

npm install @hw-agconnect/cloud-server

Prerequisites

Ensure that:

• You have installed Node.js and npm on your development environment.
• You have registered an account on the HUAWEI Developer website and passed real-name authentication. For details, see HUAWEI ID Registration.
• You have created a project and app on the AppGallery Connect console. For details, see Creating Your Project and App.
• Create an API Client in AGC Console and download your project credentials.

Usage

Initializing the SDK

Follow the steps below to initialize the Cloud-Server SDK in your application.

import { cloud } from '@hw-agconnect/cloud-server';

• Method 1: Set the environment variable.

  • On Linux, perform as follows: For a permanent environment variable, add the following command to the .bashrc or .bash_profile file in the $HOME directory, and run the source .bashrc or source .bash_profile command for the variable to take effect. For a temporary environment variable, run the following command directly and change [PATH] to the actual path of the credential file.

    export AGC_CONFIG="[PATH]/agc-apiclient-xxx-xxx.json"

  • On Windows, perform as follows:

    To set permanent environment variables, go to Advanced system settings > Environment Variables on Windows. You are advised to restart the Windows system, or load the environment variables in another way for them to take effect.

    For a temporary environment variable, run the following command directly and change [PATH] to the actual path of the credential file.

    set AGC_CONFIG=[PATH]\agc-apiclient-xxx-xxx.json

    In this method you do not need anything more. Now on you can use services with directly like in example:

    cloud.auth().sign(...)

• Method 2 : Specify the authentication credential path as follows. Replace [PATH] with the actual credential path:

  If you do not specify environment variable you must follow this method. You can also create multiple instances with credential files

  const cloudInstance=cloud.createInstance('./api-client-project.json',"instancename",Region.REGION_CN);

  [REGION] indicates the data processing location of the client. The value can be CN (China), RU (Russia), SG (Singapore), or DE (Germany).

Auth Service

• Getting Auth Service

  You can reach auth service with following ways:

  const cloudInstance.auth()

   const cloud.auth()

  • Using methods

    You must call functions with wrappers. As you can see in example of sign method usage below

    var token = cloudInstance.auth().sign({uid:"uid",displayName:"",photoUrl:"",privateKey:""})

Cloud Functions

• Getting Function Service

  You can reach function service with following ways:

  const cloudInstance.function()

   const cloud.function()

Calling a Function

export interface FunctionParams {
    name: string;
    version?: string;
    timeout?: number;
    data?: any;
}
const functionResult = cloud.function().call({name: "your-cloud-function", data: {"simple":"example"}});

Note

The default value of the version is the "-$latest" version. The default value of the timeout is the 55000.

Cloud DB

Prerequisites

Before you start using the Cloud DB Server SDK you need to create and export you Database Object Types from AGC Console. For more information, please check the official documentation.

Initializing Cloud DB

• Creates an instance and collection for the cloud database.
• It need to be created the credential for server sdk (api-client-project.json).

During local app development, you can directly add the JS file exported from AppGallery Connect to the local development environment. Then you do not need to create object types for local app development.

Put the obtained authentication credential in your custom directory. Call initialize to initialize the cloud-server instance corresponding to the data processing location.

const instance = cloud.createInstance('./api-client-project.json', 'createinstance', Region.REGION_CN);

Write the zone name that it created from AGC Console. It need to give class type of database object (It can export created object types from AGC Console). BookInfo is database object type that get AGC Console with exporting.

const collection = instance.database({ zoneName: 'testZone' }).collection(BookInfo);

Writing Data

The insertion of a single record into the database.

const tempRecord = {
    id: 1,
    bookName: 'highway',
    author: 'unknown',
    publisher: 'huawei',
    publishTime: new Date('1997-07-26T03:24:00'),
    price: 44,
};
const result = await collection.insert(tempRecord);

The "upsert" operation (update if exists, insert if not) for a record.

const tempRecord = {
    id: 1,
    bookName: 'highway',
    author: 'unknown',
    publisher: 'huawei',
    publishTime: new Date('1997-07-26T03:24:00'),
    price: 44,
};
const result = await collection.upsert(tempRecord);

Querying Data

The query() function must be called to query the database object type. After the filtering functions are run, the get() function must be called to get the result.

const query = collection.query();

The retrieval of records from the database.

const result = await query.get();

Querying records with a limit set to zero.

const result = await query.limit(0).get();

Querying records with a condition of price greater than or equal to 45.

const result = await query.greaterThanOrEqualTo('price', 45).get();

For more information about the Cloud DB Service, please check out the Documentation Guide from the Huawei Developers Website.

Cloud Storage

Constraints and Limitations

Paid services usually offer a certain amount of free quota. Once the free quota is about to be used up in a billing cycle, you can either subscribe to the pay-as-you-go plan to avoid service interruption, or wait until the next billing cycle. Before the next billing cycle arrives, the service will be unavailable.

See more detailed information on Service Pricing and Subscription

Creating Instance

• You can create an instance with the following way.

const storageInstance = await cloud.storage({bucketName: "your-storage-bucket"});

Bucket Upload

• Upload local files to a storage instance.

const result: UploadResponse = await storageInstance.upload({localPath: "localPath"});

File Download

• Downloading a file from the cloud to a local device.

const result: DownloadResponse | void = await storageInstance.download({
                localPath: "path/to/download_file",
                cloudPath: "path/to/cloudFile"
            });

License

AGC Cloud-Server NodeJS SDK is licensed under the: "ISC"