快应用接入云存储服务指导
1. 云存储服务介绍
云存储是一种可伸缩、免维护的云端存储服务，您可以用于存储图片、音频、视频或其他由用户生成的内容。借助云存储服务，您可以无需关心存储服务器的开发、部署、运维、扩容等事务，大大降低了应用使用存储的门槛，让您可以专注于应用的业务能力构建，助力您的商业成功。
工作原理：
您的应用客户端使用云存储服务提供的 SDK，可以向云存储服务器上传文件，云存储将您上传的文件存储在默认的存储实例中。您可以通过 AGC 访问这些文件。当然，您还可以使用云存储 SDK 的 API 执行下载、删除、管理文件等操作。云存储还可以配合云函数，在云存储的文件上传完成或删除成功后触发云函数执行您想要实现的功能。
典型应用场景：
存储海量文件信息，提供跨平台高效上传下载服务
云存储服务提供简单易用、功能强大的端/云SDK，实现用户生成内容的存储，让您无需关注云端能力的构建而聚焦业务逻辑开发。
2. 快应用接入云存储开发流程
开发流程概览
申请和开通云存储服务
- 申请云存储服务
云存储服务当前仍处于 Beta 开放状态，在使用此服务前，您需要向 agconnect@huawei.com 发送申请邮件，申请开通云存储服务。
邮件标题请使用如下格式：“[云存储]-[公司名称]-[开发者帐号ID]-[项目ID]”
- 开通云存储服务
登录 AppGallery Connect 网站，点击“我的项目”。
在项目列表中点击需要开通云存储的项目。
选择“构建 > 云存储”，点击“立即开通”。
在引导界面输入存储实例名称和选择“默认数据处理位置”，选择“默认安全策略”。
单击“完成”，开通云存储成功。
新建Serverless项目
1. 打开快应用 IDE，在欢迎页点击登录，在跳转的网页中登录注册的帐号。
2. 登录成功后，IDE 的导航选择“新建工程 > 快应用·云开发”，选择关联应用、模板，设置项目路径后，点击“确定”。
将应用配置信息添加到项目
1. 登录 AppGallery Connect 网站，选择“我的项目”。
2. 在项目列表中找到您的项目，并点击需要集成云存储服务的快应用。
3. 在“项目设置”页面中选择“常规”页签，下载配置文件“agconnect-services.json”。
4. 检查 agconnect-services.json 文件中 "service > cloudstorage" 标签中是否已默认配置 default_storage。
"cloudstorage" : {
"default_storage" : "您准备默认使用的存储实例名称",
"storage_url" : "https://agc-storage-drcn.platform.dbankcloud.cn"
}5. 将修改后 agconnect-services.json 拷贝到您快应用项目的 src 目录下。
集成SDK
1. 执行如下命令安装云存储 JS SDK 到您的项目中。
npm install --save @agconnect/cloudstorage@1.1.02. 在您的项目中导入 agc 组件。
import agconnect from '@agconnect/api';
import '@agconnect/cloudstorage';
import "@agconnect/instance";3. 初始化 AGC SDK。
let agConnectConfig = require('./agconnect-services.json');
agconnect.instance().configInstance(agConnectConfig);4. 初始化存储实例
const storageManagement = agconnect.cloudStorage();创建引用
1. 文件存储在云端的存储实例中，存储方式与本地硬盘中的文件系统类似，您可以通过文件的引用进行上传文件、获取文件的下载地址、删除文件、更新文件元数据等操作，您也可以通过创建目录的引用来获取该目录下的文件列表。
如果您需要上传、删除文件，更新文件的元数据及获取文件的下载地址，均需要创建对应文件的引用。
2. 初始化成功后，您可通过调用 StorageManagement.storageReference 创建 StorageReference 对象的引用。
// storageManagement为已经初始化的cloudStorage实例
const reference = storageManagement.storageReference();3. 您也可以通过调用 StorageManagement.storageReference 并传入一个完整的云端文件的地址来创建一个 StorageReference 对象的引用。
let agconnect = this.$app.$def.agc;
//创建存储示例对象的引用，通过引用调用相关的文件/目录接口
let ref = agconnect.cloudStorage().storageReference();
let parentPath = this.getParentPath();
const child = ref.child(parentPath);
child.list({ maxResults: 10 }).then((res) => {
this.currentPath = parentPath;
this.selected = '';
this.setList(res);
})上传文件
1. 用户可以通过引用操作本地设备上的文件，将文件上传到云端的存储实例中。
2. 调用 StorageManagement.storageReference 创建需上传文件的引用，传入文件在云端预先规划的文件地址。
var storageReference = storage.storageReference();
var reference = storageReference.child('images/demo.jpg');3. 调用 StorageReference.put4QuickApp 方法将文件上传到存储实例中。
// uri为本地文件资源uri标识
var fileMetadata = reference.put4QuickApp(uri);4. 如果您需要在上传文件时为文件指定自定义属性，可以使用 StorageReference.put4QuickApp(uri : String, , attribute ?: UploadMetadata) 方法中的 UploadMetadata 属性。
putFile() {
let that = this;
media.pickFile ({
success: function (data) {
console.log("handling success: " + data.uri);
let agconnect = that.$app.$def.agc;
let ref = agconnect.cloudStorage().storageReference();
let path = that.currentPath + that.getName(data.uri);
const child = ref.child(path);
child.put4QuickApp(data.uri, {
cacheControl: 'no-cache',
//contentDisposition: 'attachment;filename="demo.png"',
contentEncoding: 'identity',
contentLanguage: 'en-US',
//contentType: 'image/png; charset=utf-8',
customMetadata: {
hello: 'kitty'
}
}).then((res) => {
that.result = JSON.stringify(res, null, "\t");
prompt.showToast ({
message: `putFile success`,
duration: 3500,
gravity: 'center'
});
})
},
fail: function (data, code) {
console.log("handling fail, code=" + code);
}
})
},列举文件
1. 云存储 SDK 支持通过 API 列举云端某个目录下的所有文件或子目录。
2. 在列举某个目录下的文件或目录前，先调用 StorageManagement.storageReference 创建目录的引用。例如创建根目录的引用：
var storageReference = storage.storageReference();3. 调用 StorageReference.listAll 可获取当前目录下所有文件与目录。
reference.listAll()
.then((res) => {})
.catch((err) => {});4. 如果需要分页获取，可以调用 StorageReference.list(options?: ListOptions) 方法。
// pageMarker是获取分页列表信息时下一页的起始位置
reference.list ({
maxResults: 100,
pageMarker: pageMarker
}).then((res) = >{}).catch((err) = >{});
getList() {
let agconnect = this.$app.$def.agc;
let ref = agconnect.cloudStorage().storageReference();
let path = this.selected === '' ? this.currentPath : this.selected;
const child = ref.child(path);
child.list ({
maxResults: 10
}).then((res) = > {
this.currentPath = path;
this.selected = '';
this.setList(res);
})
},
getListAll() {
let agconnect = this.$app.$def.agc;
let ref = agconnect.cloudStorage().storageReference();
let path = this.selected === '' ? this.currentPath : this.selected;
const child = ref.child(path);
child.listAll().then((res) = > {
this.currentPath = path;
this.selected = '';
this.setList(res);
})
},获取文件的下载地址
1. 文件已经上传到云端后，您可以通过调用云存储 SDK 的 API 获取云端文件的下载地址。
2. 调用 StorageManagement.storageReference 创建需要下载文件的引用。
var storageReference = storage.storageReference();
var reference = storageReference.child('images/demo.jpg');3. 调用 StorageReference.getDownloadURL 获取下载地址。
reference.getDownloadURL()
.then(function(downloadURL){})
.catch((err) => {});4. 您可以通过将上一步获取的下载地址拷贝到浏览器的地址栏下载文件，或者调用快应用下载接口获取文件。
getDownloadURL() {
if (this.selected === '' || this.selected.endsWith('/')) {
prompt.showToast ({
message: `only file can getDownloadURL`,
duration: 3500,
gravity: 'center'
});
return;
}
let agconnect = this.$app.$def.agc;
let ref = agconnect.cloudStorage()
.storageReference();
const child = ref.child(this.selected);
child.getDownloadURL().then((res) => {
this.result = res;
prompt.showToast ({
message: `getDownloadURL success`,
duration: 3500,
gravity: 'center'
});
}).catch((err) => {
console.error("getDownloadURL fail");
prompt.showToast ({
message: `getDownloadURL fail`,
duration: 3500,
gravity: 'center'
});
});
var that = this
prompt.showDialog ({
title: '',
message: 'Do you want to download the file and view the content?',
buttons: [{
text: 'yes',
color: '#33dd44'
},
{
text: 'cancel',
color: '#33dd44'
}],
success: function(data) {
console.log("handling callback", data);
if (data.index === 0) {
router.push ({
uri: '/DownloadShow',
params: {
url: that.result
}
})
}
},
cancel: function() {
console.log("cancel");
}
})
}删除文件
1. 当云端的文件不需要时，您可以通过调用云存储 SDK 的 API 在应用客户端删除云端的文件。
2. 调用 StorageManagement.storageReference 创建需要删除文件的引用。
var storageReference = storage.storageReference();
var reference = storageReference.child('images/demo.jpg');3. 调用 StorageReference.delete 删除云端文件。
reference.delete()
.then((res) => {})
.catch((err) => {});注意：删除操作不可逆，一旦执行，文件会被物理删除，不可找回。
delete() {
if (this.selected === '' || this.selected.endsWith('/')) {
prompt.showToast ({
message: `only file can be delete`,
duration: 3500,
gravity: 'center'
});
return;
}
let agconnect = this.$app.$def.agc;
let ref = agconnect.cloudStorage().storageReference();
const child = ref.child(this.selected);
child.delete().then((res) => {
prompt.showToast ({
message: `delete success`,
duration: 3500,
gravity: 'center'
});
let result = [];
for (var i in this.list) {
if (this.list[i].path !== this.selected) {
result.push(this.list[i]);
}
}
this.list = result;
this.selected = '';
})
},元数据管理
1. 在上传文件前或者文件已经上传到云端，您都可以设置文件元数据。可设置的文件元数据包括文件的自定义属性。
2. 调用 StorageManagement.storageReference 创建文件的引用，并初始化文件的 UploadMetadata 实例。
var storageReference = storage.storageReference();
var reference = storageReference.child('images/demo.jpg');
var metadata = { contentType:'image/jpeg' };
// uri为本地文件资源uri标识
var fileMetadata = reference.put4QuickApp(uri, metadata);3.文件的自定义属性可以通过 UploadMetadata.customMetadata 设置。
调用 StorageReference.updateFileMetadata 采用覆盖的方式将设置的文件元数据覆盖到云端。
reference.updateFileMetadata(metadata)
.then(function(res){})
.catch((err) => {});4. 当设置元数据成功后，您可以通过调用 StorageReference.getFileMetadata 方法来获取设置在云端的元数据。
reference.getFileMetadata()
.then((res) => {})
.catch((err) => {});
uploadMetaData() {
if (this.selected === '' || this.selected.endsWith('/')) {
prompt.showToast ({
message: `only file can uploadMetaData`,
duration: 3500,
gravity: 'center'
});
return;
}
let agconnect = this.$app.$def.agc;
let ref = agconnect.cloudStorage().storageReference();
const child = ref.child(this.selected);
child.updateFileMetadata ({
cacheControl: 'no-cache',
contentEncoding: 'identity',
contentLanguage: 'en-US',
customMetadata: {
hello: 'kitty'
}
}).then((res) => {
this.result = JSON.stringify(res, null, '\t');
prompt.showToast ({
message: `uploadMetaData success`,
duration: 3500,
gravity: 'center'
});
})
},3. AGC 控制台管理文件
AGC 的云存储服务提供可视化的文件管理和数据分析功能。
文件管理：除了在应用客户端通过云存储SDK的API来管理文件，您还可以直接在AGC以可视化的方式来进行文件管理，包括上传文件、查看文件详情、下载文件、创建文件夹、删除文件或文件夹、创建令牌。
数据分析：您可以在AGC中查看云存储数据分析情况。
AGC 控制台目前支持以下功能：
- 上传文件
- 创建文件夹
- 查看文件详情
- 下载文件
- 删除文件或文件夹
- 创建令牌
- 云存储数据分析
4. FAQ
配额限制
当您使用的云存储资源超过免费配额后，则需要付费使用超额的部分，具体请参见服务定价与订购。
资源限制
Q：是否支持流式文件上传？
采用流式上传文件没办法对文件进行一致性校验，容易造成文件损坏，可采用先接收数据并写入文件，然后再通过本地文件上传到云端的方式上传文件。
Q：云端文件的命名是否有限制？
满足命名规范即可，无其他限制，但服务器会按照文件名的 UTF-8 编码范围进行分区管理，对系统进行水平扩展与动态负载均衡。如果文件命名规则使用了顺序前缀（如时间戳或字母顺序），可能导致大量文件的请求访问集中于某个特定分区，造成访问热点，热点分区上的请求速率受限，访问时延上升。