Note: this version of the documentation has been archived and is no longer maintained. Please move to the latest version.

Cloud Storage (AppGallery Connect) Quick Start

Cloud Storage is scalable and maintenance-free. It allows developer to store high volumes of data such as images, audios, and videos generated by your users securely and economically with direct device access.

The service is stable, secure, efficient, and easy-to-use, and can free you from development, deployment, O&M, and capacity expansion of storage servers. You do not need to pay attention to indicators such as availability, reliability, and durability and can focus on service capability building and operations, improving user experience.

Advantages

Cloud Storage provides a client SDK for you to store files generated by users, such as images, videos, and audios. The SDK provides simple, secure, efficient, and robust APIs.

• Transmitted data is encrypted using HTTPS, and files are encrypted and stored on the cloud using secure encryption protocols.
• If an operation is terminated manually or due to a network fault, the app client only needs to pass the position where the operation is terminated to resume the operation.
• EB-level data storage is available for massive data storage.
• You can easily locate the cause of an error according to the result code.

Working Principles

With the client SDK provided by Cloud Storage, an app client can upload files to the cloud storage space. Cloud Storage stores the uploaded files in the default storage instance. You can access these files through AppGallery Connect. You can also use the Cloud Storage SDK to download, delete, and manage files on the app client.

Apply for Test Qualification

Cloud Storage is still in Beta testing. To use Cloud Storage, send an application email to agconnect@huawei.com to apply for the service.

Set your email title format as: [Cloud Storage]-[Company name]-[Developer account ID]-[Project ID]. For details about how to query thedeveloper account ID and project ID, please refer to Querying the Developer Account ID and Project ID. Huawei operation personnel will reply within 1 to 3 working days.

Charge

Cloud Storage is in beta testing and uses a limited free usage policy. That is, you can use the service for free within a specified quota.

Version Update Description

• Latest Version: 0.5.2_1.3.1.100

  • Fix the crash of the updateFileMetadata method.
  • Add some AGCStorageReference interfaces.
  • Add a new part to obtain the Android application storage directory interface.

• v0.5.0_1.3.0.300

  • Integrated Huawei AGC Cloud Storage service.

Enable Cloud Storage Service

• Ensure that the Cloud Storage service test qualification application has been passed.

• Use Cocos Creator to open the project that needs to be connected to Cloud Storage service.

• Cloud Storage service depends on Auth Service, please enable the Auth Service (AGC) before integrating the Cloud Storage service.

• Click on Panel -> Service in the menu bar to open the Service panel, select Cloud Storage service to go to the service detail page, and then click on the Enable button in the top right to enable the service. For details, please refer to the Cocos Service Operation Guide documentation.

  

• Please refer to Enabling Cloud Storage document, set Storage instance and enabling cloud storage. Then fill in the name of the storage instance used by default into the Default Instance parameter at the bottom of the Cloud Storage service panel.

  

Configs HUAWEI Config File

Most of HUAWEI Services need the agconnect-services.json configuration file. If there are operations such as newly opened services, please update the file in time.

• Sign in to AppGallery Connect find your project from the project list and select the app on the project card.

• On the Project Setting page, click the configuration file agconnect-services.json to download it. The agconnect-services.json file must be copied manually to the settings directory of the project directory after downloading or updating.

  

• For Creator v2.4.3 and above, if you want to publish to the HUAWEI AppGallery Connect, you can select the downloaded or updated configuration file directly in the Build panel, no need to copy it manually.

  

Verify whether the service is integrated successfully

• Once the Cloud Storage service is integrated, we can verify the success of the Cloud Storage service integration by adding simple code to the script.

  huawei.agc.storage.storageService.on("list-file", data => this.console.log("Cloud Storage, list-file", JSON.stringify(data)), this);
  var rootReference = storageManagement.getStorageReference();
  rootReference.listAll();

• Please refer to Upload a file document, upload any legal file.

• Publish to the Android platform after the code is added. Please make sure that the Package Name on the Build panel is consistent with the Package Name set in the AppGallery Connect console.

• Run the project on a phone, if you can see the file name of the uploaded file in Logcat, which means the integrate is successful.

Sample Project

Developer can get a quick taste of the Cloud Storage service with the sample project.

• Upload a legal file named output.json.

• Click on the Sample button in the Cloud Storage service panel, clone or download, and open the project in Cocos Creator.

• After enabling the Cloud Storage service and configuring the HUAWEI configuration file as described above, you can open the Build panel to compile the project by clicking Project -> Build in the Creator editor menu bar. Cocos Creator v2.4.1 and above, you could publish to HUAWEI AppGallery Connect. Below Creator v2.4.1 could publish to the Android platform.

• Once the Sample project is running on the phone, click the Auth button first, after completing user authentication, then back to homepage and press Storage button for testing.

  

Developer Guide

Legality of files

When you upload a file or directory, the system strictly checks the name of the file or directory against the following rules:

• When you use UTF-8 for encoding, the total length of the complete address of the cloud file cannot exceed 1024 characters.
• The name cannot contain carriage return characters or line breaks.
• Do not use special characters including the following: # * : ? ' " < > | [ ].
• The maximum size of a file to be uploaded cannot exceed 50GB. The Cloud Storage SDK of AppGallery Connect uploads a maximum of 5 GB data to the server each time until 50GB data is uploaded. If the upload fails, the SDK retries the upload until the configured maximum number of retry times is reached.
• The name of a file or directory can contain up to 255 characters. Otherwise, compatibility problems may occur in some operating systems.

Initializing

Developer need to initialize the cloud storage instance by calling getInstance method before using the Cloud Storage service.

var storageManagement = huawei.agc.storage.storageService.getInstance();

If you need to use a non-default cloud storage instance, you need to pass in the storage instance name.

var customManagement = huawei.agc.storage.storageService.getInstance("custom-bucket-name");

Set listener

Set up types of event listeners, and handle them in the callback if necessary.

Description of callback event types:

Event Type	Description
"error"	Error
"get-file-metadata"	Get file metadata
"update-file-metadata"	Update file metadata
"delete-file"	Delete file
"list-file"	List file
"get-download-url"	Get download url
"task"	Upload or download files task

Example:

huawei.agc.storage.storageService.on("error", data => this.console.log("Cloud Storage, error:", `${data.errCode}:${data.errMsg}`), this);
huawei.agc.storage.storageService.on("get-file-metadata", data => this.console.log("Cloud Storage, get-file-metadata", JSON.stringify(data)), this);
huawei.agc.storage.storageService.on("update-file-metadata", data => this.console.log("Cloud Storage, update-file-metadata", JSON.stringify(data)), this);
huawei.agc.storage.storageService.on("delete-file", data => this.console.log("Cloud Storage, delete-file", JSON.stringify(data)), this);
huawei.agc.storage.storageService.on("list-file", data => this.console.log("Cloud Storage, list-file", JSON.stringify(data)), this);
huawei.agc.storage.storageService.on("get-download-url", data => this.console.log("Cloud Storage, get-download-url", JSON.stringify(data)), this);
huawei.agc.storage.storageService.on("task", data => this.console.log("Cloud Storage, task", JSON.stringify(data)), this);

error event callback

All error messages will be returned to the error event callback.

Parameter	Type	Description
errCode	Number	Error code, please refer to Troubleshooting document.
errMsg	String	Error message description.

Creating a Reference

If developer need to upload, download, and delete a file, or update file metadata, developer need to create a reference to a root directory, a specified file or directory on the cloud by calling getStorageReference method.

Example:

var rootReference = storageManagement.getStorageReference();
var dirReference = storageManagement.getStorageReference("images/");
var fileReference = storageManagement.getStorageReference("images/demo.jpg");

Developer can also call child, getParent and getRoot methods to create the reference.

Example:

var fileReference = rootReference.child("images/demo.jpg");
var dirReference = fileReference.getParent();
var nRootReference = fileReference.getRoot();

Uploading a File

Reference files on the local device to upload the files to the storage instance on the AppGallery Connect cloud by calling putFile method.

putFile(filePath: string, metadata = {}, offset = -1): AGCUploadTask

Parameter	Description
filePath	Binary data of a file to be uploaded. The total size cannot exceed 50GB.
metadata	Metadata of a file or directory.
offset	Position of resumable download. Set this parameter to the number of bytes that have been passed. You can obtain the value of this parameter from bytesTransferred of task callback.

Example:

var fileReference = storageManagement.getStorageReference("images/demo.jpg");
var uploadTask = fileReference.putFile(jsb.fileUtils.getWritablePath() + "/images/demo.jpg");

Call the pause, resume, or cancel method to change the upload task status.

• pause(): boolean: Pauses an upload task that is being executed.
• resume(): boolean: Resumes a paused upload task.
• cancel(): boolean: Cancels a task, will cause the upload task to fail.

Example:

uploadTask.pause();
uploadTask.resume();
uploadTask.cancel();

task event callback

Developer can obtain information from the task event callback.

Parameter	Type	Description
bytesTransferred	Number	Obtains passed bytes.
totalByteCount	Number	Obtains the total number of bytes of an uploaded file.
metadata	Map	Obtain file metadata and return it only on upload.

Listing Files

Call listAll to obtain all files and subdirectories in the current directory.

listAll(): void

Example:

var dirReference = storageManagement.getStorageReference("images/");
dirReference.listAll();

You can also call list method to get a list of files in the current directory, including files and subdirectories.

list(max: number, marker = ""): void

Parameter	Description
max	Total number of files and subdirectories to be obtained in pagination mode. The value of max ranges from 1 to 1000.
marker	Pagination identifier. Obtain the pagination identifier of the next page from pageMaker of list-file callback, and then call this method to obtain the data of the next page.

Example:

var dirReference = storageManagement.getStorageReference("images/");
dirReference.list(100, "file100.json");

list-file event callback

Developer can obtain information from the list-file event callback.

Parameter	Type	Description
pageMarker	String	Start pagination identifier. This parameter will be returned when calling the list(max: number, marker = "") method.
fileList	JSONArray	References of all files in the list.
dirList	JSONArray	References of all directories in the list.

Downloading a File

After files are uploaded to the cloud, call getFile method to download files on the cloud to the local device.

The getFile method supports resumable download. If the download fails due to an exception, call getFile again to continue the download, improving user experience.

getFile(filePath: string): AGCDownloadTask

Parameter	Description
filePath	Path of the file which data needs to be written in, the file must be created in advance.

Example:

var fileReference = storageManagement.getStorageReference("images/demo.jpg");
var downloadTask = fileReference.getFile(jsb.fileUtils.getWritablePath() + "/images/demo.jpg");

Developer can obtain information from the task event callback.

Deleting a File

Call delete method to delete a file on the cloud. The deletion operation is irreversible, once the operation is performed, the file will be physically deleted and cannot be retrieved.

delete(): void

Example:

var fileReference = defaultInstance.getStorageReference("images/demo.jpg");
fileReference.delete();

delete-file event callback

If the file is successfully deleted, the message will be received in the delete-file event callback, and no parameters need to be processed. If the file deletion fails, it will be will be received in the error event callback.

Obtaining Metadata

After a file is saved to the cloud, you can obtain the metadata of the file to determine whether to download the file.

getFileMetadata(): void

Example:

var fileReference = storageManagement.getStorageReference("images/demo.jpg");
fileReference.getFileMetadata();

get-file-metadata event callback

Developer can obtain information from the get-file-metadata event callback.

Parameter	Type	Description
bucket	String	Name of a storage instance.
cTime	String	Creation time, in the following format: "Thu, 12 Mar 2020 12:10:03 GMT".
dirList	String	Last update time, in the following format: "Thu, 12 Mar 2020 12:10:03 GMT".
name	String	Name of a file on the cloud server.
path	String	Path of a file on the cloud server. Example: images/demo.jpg.
size	String	Size of a file on the cloud server, in bytes.
sha256	String	SHA-256 value set during file upload.
contentType	String	Type of a file on the cloud server.
cacheControl	String	CacheControl setting of a user.
contentDisposition	String	ContentDisposition setting of a user.
contentEncoding	String	ContentEncoding setting of a user.
contentLanguage	String	ContentLanguage setting of a user.
customMetadata	Map	Custom file attributes.

Setting Metadata

Set file metadata before uploading a file or after a file is uploaded to the cloud. Configurable file metadata includes custom file attributes.

updateFileMetadata(metedata: any): void

Modifiable parameters: sha256, contentType, cacheControl, contentDisposition, contentEncoding, contentLanguage, customMetadata.

Example:

var metadata = {"contentType": "jpg", "customMetadata": {"key1": "values1", "key2": "value2"}};
fileReference.updateFileMetadata(metadata);

update-file-metadata event callback

Developer can obtain information from the update-file-metadata event callback.

Parameter	Type	Description
bucket	String	Name of a storage instance.
cTime	String	Creation time, in the following format: "Thu, 12 Mar 2020 12:10:03 GMT".
dirList	String	Last update time, in the following format: "Thu, 12 Mar 2020 12:10:03 GMT".
name	String	Name of a file on the cloud server.
path	String	Path of a file on the cloud server. Example: images/demo.jpg.
size	String	Size of a file on the cloud server, in bytes.
sha256	String	SHA-256 value set during file upload.
contentType	String	Type of a file on the cloud server.
cacheControl	String	CacheControl setting of a user.
contentDisposition	String	ContentDisposition setting of a user.
contentEncoding	String	ContentEncoding setting of a user.
contentLanguage	String	ContentLanguage setting of a user.
customMetadata	Map	Custom file attributes.

Get Download Url

Obtains the download URL of a cloud file.

getDownloadUrl(): void

Example:

var fileReference = storageManagement.getStorageReference("images/demo.jpg");
fileReference.getDownloadUrl();

get-download-url event callback

Developer can obtain information from the get-download-url event callback.

Parameter	Type	Description
url	String	Download url address

API Reference

Please refer to the Cloud Storage - API Reference.