uniCloud内置API总结
uniCloud提供了丰富的内置API，这些API可以在云函数和云对象中使用。本文将对这些API进行分类总结，帮助开发者更好地理解和使用uniCloud的功能。
1. 数据库API
1.1 获取数据库实例
// 获取数据库实例
const db = uniCloud.database();
// 获取指定服务空间的数据库实例
const db = uniCloud.database({
provider: 'aliyun', // 服务商，可选值：aliyun、tencent
spaceId: 'your-space-id' // 服务空间ID
});
1.2 集合操作
// 获取集合引用
const collection = db.collection('collection-name');
// 获取集合的聚合操作对象
const aggregate = db.collection('collection-name').aggregate();
// 获取集合的查询对象
const query = db.collection('collection-name').where({
field: 'value'
});
// 获取集合的更新对象
const update = db.collection('collection-name').doc('document-id').update({
field: 'new-value'
});
// 获取集合的删除对象
const remove = db.collection('collection-name').doc('document-id').remove();
1.3 查询操作
// 查询示例
const result = await db.collection('users')
.where({
age: db.command.gt(18), // 年龄大于18
city: '北京' // 城市为北京
})
.field({
name: true, // 只返回name字段
age: true // 只返回age字段
})
.orderBy('age', 'desc') // 按年龄降序排序
.skip(0) // 跳过0条记录
.limit(10) // 最多返回10条记录
.get();
console.log(result.data); // 查询结果
1.4 添加操作
// 添加单条记录
const result = await db.collection('users').add({
name: '张三',
age: 25,
city: '北京',
createTime: Date.now()
});
console.log(result.id); // 新增记录的ID
// 添加多条记录
const result = await db.collection('users').add([
{
name: '张三',
age: 25,
city: '北京',
createTime: Date.now()
},
{
name: '李四',
age: 30,
city: '上海',
createTime: Date.now()
}
]);
console.log(result.ids); // 新增记录的ID数组
1.5 更新操作
// 更新单条记录
const result = await db.collection('users').doc('document-id').update({
age: 26,
updateTime: Date.now()
});
console.log(result.updated); // 更新的记录数
// 更新多条记录
const result = await db.collection('users').where({
city: '北京'
}).update({
city: '广州',
updateTime: Date.now()
});
console.log(result.updated); // 更新的记录数
1.6 删除操作
// 删除单条记录
const result = await db.collection('users').doc('document-id').remove();
console.log(result.deleted); // 删除的记录数
// 删除多条记录
const result = await db.collection('users').where({
age: db.command.lt(18)
}).remove();
console.log(result.deleted); // 删除的记录数
1.7 聚合操作
// 聚合示例
const result = await db.collection('orders')
.aggregate()
.match({
status: 'completed'
})
.group({
_id: '$userId',
totalAmount: db.command.aggregate.sum('$amount'),
orderCount: db.command.aggregate.count()
})
.sort({
totalAmount: -1
})
.limit(10)
.end();
console.log(result.data); // 聚合结果
2. 存储API
2.1 上传文件
// 上传文件
const result = await uniCloud.uploadFile({
filePath: 'file-path', // 文件路径
cloudPath: 'cloud-path/file-name.jpg', // 云端路径
onUploadProgress: function(progressEvent) {
console.log(progressEvent);
}
});
console.log(result.fileID); // 文件ID
2.2 下载文件
// 下载文件
const result = await uniCloud.downloadFile({
fileID: 'file-id', // 文件ID
onDownloadProgress: function(progressEvent) {
console.log(progressEvent);
}
});
console.log(result.tempFilePath); // 临时文件路径
2.3 删除文件
// 删除文件
const result = await uniCloud.deleteFile({
fileList: ['file-id-1', 'file-id-2'] // 文件ID列表
});
console.log(result.fileList); // 删除结果
2.4 获取文件信息
// 获取文件信息
const result = await uniCloud.getFileInfo({
fileList: ['file-id-1', 'file-id-2'] // 文件ID列表
});
console.log(result.fileList); // 文件信息列表
2.5 获取临时访问链接
// 获取临时访问链接
const result = await uniCloud.getTempFileURL({
fileList: ['file-id-1', 'file-id-2'] // 文件ID列表
});
console.log(result.fileList); // 临时访问链接列表
3. 云函数API
3.1 调用云函数
// 调用云函数
const result = await uniCloud.callFunction({
name: 'function-name', // 云函数名称
data: {
// 传递给云函数的参数
param1: 'value1',
param2: 'value2'
}
});
console.log(result.result); // 云函数返回结果
3.2 导入云对象
// 导入云对象
const todo = uniCloud.importObject('todo');
// 调用云对象方法
const result = await todo.add('标题', '内容');
console.log(result); // 云对象方法返回结果
3.3 导入云对象参数说明
interface ImportObjectOptions {
/**
* 是否移除自动展示的ui
*/
customUI?: boolean;
/**
* loading界面配置
*/
loadingOptions?: ImportObjectLoadingOptions;
/**
* 错误提示配置
*/
errorOptions?: ImportObjectErrorOptions;
/**
* 使用安全网络的方法及安全网络类型
*/
secretMethods?: Record<string, 'none' | 'request' | 'response' | 'both'>;
/**
* 转化云对象内未捕获的错误或客户端网络错误
*/
parseSystemError?: (params: ParseSystemErrorParams) => Promise<ParsedSystemError> | ParsedSystemError;
}
4. HTTP请求API
4.1 发送HTTP请求
// 发送HTTP请求
const result = await uniCloud.httpclient.request(
'https://example.com/api',
{
method: 'POST',
data: {
key: 'value'
},
dataType: 'json',
headers: {
'Content-Type': 'application/json'
}
}
);
console.log(result.data); // 响应数据
4.2 发送formdata类型数据
// 发送formdata类型数据
const result = await uniCloud.httpclient.request(
'https://example.com/api',
{
method: 'POST',
data: {
key: 'value'
},
dataType: 'json',
headers: {
'Content-Type': 'multipart/form-data'
},
files: {
file: {
filename: 'file.jpg',
contentType: 'image/jpeg',
value: fs.createReadStream('file.jpg')
}
}
}
);
console.log(result.data); // 响应数据
5. WebSocket API
5.1 创建WebSocket连接
// 创建WebSocket连接
const socketTask = uniCloud.httpclient.createSocketTask({
url: 'wss://example.com/websocket',
success: function() {
console.log('WebSocket连接成功');
},
fail: function(err) {
console.error('WebSocket连接失败', err);
}
});
5.2 WebSocket事件监听
// 监听WebSocket连接打开事件
socketTask.onOpen(function() {
console.log('WebSocket连接已打开');
});
// 监听WebSocket接收到服务器的消息事件
socketTask.onMessage(function(res) {
console.log('收到服务器消息', res.data);
});
// 监听WebSocket错误事件
socketTask.onError(function(err) {
console.error('WebSocket错误', err);
});
// 监听WebSocket关闭事件
socketTask.onClose(function() {
console.log('WebSocket连接已关闭');
});
5.3 WebSocket发送消息
// 发送消息
socketTask.send({
data: 'Hello Server',
success: function() {
console.log('消息发送成功');
},
fail: function(err) {
console.error('消息发送失败', err);
}
});
5.4 关闭WebSocket连接
// 关闭WebSocket连接
socketTask.close({
success: function() {
console.log('WebSocket连接已关闭');
},
fail: function(err) {
console.error('关闭WebSocket连接失败', err);
}
});
6. 请求和环境API
6.1 获取请求ID
// 获取请求ID
const requestId = uniCloud.getRequestId();
console.log(requestId); // 请求ID
6.2 获取客户端信息
// 获取客户端信息
const clientInfo = uniCloud.getClientInfo();
console.log(clientInfo);
// 输出示例：
// {
// clientIP: '127.0.0.1',
// userAgent: 'Mozilla/5.0 ...',
// platform: 'web',
// os: 'windows',
// device: 'desktop'
// }
6.3 获取云端信息
// 获取云端信息
const cloudInfo = uniCloud.getCloudInfo();
console.log(cloudInfo);
// 输出示例：
// {
// provider: 'aliyun',
// spaceId: 'your-space-id',
// functionName: 'function-name',
// functionType: 'cloudFunction'
// }
7. 配置中心API
7.1 获取配置
// 获取配置
const config = uniCloud.getConfig({
configKey: 'config-key' // 配置键名
});
console.log(config); // 配置值
7.2 设置配置
// 设置配置
const result = await uniCloud.setConfig({
configKey: 'config-key', // 配置键名
configValue: 'config-value' // 配置值
});
console.log(result); // 设置结果
8. 云对象API
云对象提供了多种内置API，用于获取上下文信息：
- getClientInfo()：获取客户端信息
- getCloudInfo()：获取云端信息
- getClientToken()：获取客户端Token
- getMethodName()：获取当前调用的方法名
- getParams()：获取当前参数列表
- getRequestId()：获取当前请求ID
- getHttpInfo()：获取URL化时的HTTP信息
- setCookie()：设置Cookie
- getCookie()：获取Cookie
- deleteCookie()：删除Cookie
9. uniCloud扩展API
uniCloud除了提供内置API外，还提供了一些扩展API，这些API需要单独引入才能使用。以下是常用的扩展API：
9.1 Redis扩展库
Redis扩展库提供了对Redis数据库的操作能力，可以用于缓存、会话存储、消息队列等场景。
9.1.1 引入Redis扩展库
// 引入Redis扩展库
const redis = uniCloud.importObject('redis');
9.1.2 Redis基本操作
// 设置键值对
await redis.set('key', 'value');
// 获取键值
const value = await redis.get('key');
// 删除键
await redis.del('key');
// 设置键值对并设置过期时间（单位：秒）
await redis.setex('key', 3600, 'value');
// 判断键是否存在
const exists = await redis.exists('key');
// 设置键的过期时间（单位：秒）
await redis.expire('key', 3600);
// 获取键的剩余过期时间（单位：秒）
const ttl = await redis.ttl('key');
9.1.3 Redis列表操作
// 从列表左侧添加元素
await redis.lpush('list', 'value1', 'value2');
// 从列表右侧添加元素
await redis.rpush('list', 'value3', 'value4');
// 从列表左侧弹出元素
const value = await redis.lpop('list');
// 从列表右侧弹出元素
const value = await redis.rpop('list');
// 获取列表长度
const length = await redis.llen('list');
// 获取列表指定范围的元素
const values = await redis.lrange('list', 0, -1);
9.1.4 Redis哈希表操作
// 设置哈希表字段
await redis.hset('hash', 'field1', 'value1');
// 获取哈希表字段值
const value = await redis.hget('hash', 'field1');
// 获取哈希表所有字段和值
const hash = await redis.hgetall('hash');
// 删除哈希表字段
await redis.hdel('hash', 'field1');
// 判断哈希表字段是否存在
const exists = await redis.hexists('hash', 'field1');
// 获取哈希表字段数量
const length = await redis.hlen('hash');
9.1.5 Redis集合操作
// 添加集合元素
await redis.sadd('set', 'value1', 'value2');
// 获取集合所有元素
const members = await redis.smembers('set');
// 判断元素是否在集合中
const isMember = await redis.sismember('set', 'value1');
// 获取集合元素数量
const size = await redis.scard('set');
// 从集合中删除元素
await redis.srem('set', 'value1');
9.2 Push扩展库
Push扩展库提供了消息推送的能力，可以用于向客户端推送通知、消息等。
9.2.1 引入Push扩展库
// 引入Push扩展库
const push = uniCloud.importObject('push');
9.2.2 推送消息
// 推送消息到指定客户端
await push.sendMessage({
push_clientid: 'client-id', // 客户端ID
title: '消息标题', // 消息标题
content: '消息内容', // 消息内容
force: true, // 是否强制推送
data: { // 自定义数据
key: 'value'
}
});
// 推送消息到多个客户端
await push.sendMessage({
push_clientid: ['client-id-1', 'client-id-2'], // 客户端ID数组
title: '消息标题', // 消息标题
content: '消息内容', // 消息内容
force: true, // 是否强制推送
data: { // 自定义数据
key: 'value'
}
});
// 推送消息到所有客户端
await push.sendMessage({
title: '消息标题', // 消息标题
content: '消息内容', // 消息内容
force: true, // 是否强制推送
data: { // 自定义数据
key: 'value'
}
});
9.2.3 获取客户端列表
// 获取客户端列表
const clients = await push.getClientList({
page: 1, // 页码
pageSize: 10 // 每页数量
});
console.log(clients.data); // 客户端列表
console.log(clients.total); // 客户端总数
9.3 uni-id扩展库
uni-id扩展库提供了用户身份认证的能力，可以用于实现用户注册、登录、权限控制等功能。
9.3.1 引入uni-id扩展库
// 引入uni-id扩展库
const uniId = uniCloud.importObject('uni-id');
9.3.2 用户注册
// 用户注册
const result = await uniId.register({
username: 'username', // 用户名
password: 'password', // 密码
nickname: '昵称', // 昵称
gender: 0, // 性别，0：未知，1：男，2：女
avatar: 'avatar-url', // 头像URL
mobile: '13800138000', // 手机号
email: 'example@example.com' // 邮箱
});
console.log(result.uid); // 用户ID
9.3.3 用户登录
// 用户名密码登录
const result = await uniId.login({
username: 'username', // 用户名
password: 'password', // 密码
queryField: ['username', 'email', 'mobile'] // 查询字段
});
console.log(result.token); // 登录令牌
console.log(result.uid); // 用户ID
// 手机号验证码登录
const result = await uniId.loginBySms({
mobile: '13800138000', // 手机号
code: '123456' // 验证码
});
console.log(result.token); // 登录令牌
console.log(result.uid); // 用户ID
9.3.4 用户信息
// 获取用户信息
const result = await uniId.getUserInfo({
uid: 'user-id' // 用户ID
});
console.log(result.userInfo); // 用户信息
// 更新用户信息
const result = await uniId.updateUserInfo({
uid: 'user-id', // 用户ID
nickname: '新昵称', // 昵称
gender: 1, // 性别
avatar: 'new-avatar-url' // 头像URL
});
console.log(result.updated); // 更新结果
9.3.5 权限控制
// 设置用户角色
const result = await uniId.setRole({
uid: 'user-id', // 用户ID
roleID: 'role-id' // 角色ID
});
console.log(result.updated); // 更新结果
// 检查用户权限
const result = await uniId.checkPermission({
uid: 'user-id', // 用户ID
permissionID: 'permission-id' // 权限ID
});
console.log(result.hasPermission); // 是否有权限
9.4 uni-pay扩展库
uni-pay扩展库提供了支付能力，可以用于实现各种支付场景。
9.4.1 引入uni-pay扩展库
// 引入uni-pay扩展库
const uniPay = uniCloud.importObject('uni-pay');
9.4.2 创建支付订单
// 创建支付订单
const result = await uniPay.createOrder({
provider: 'alipay', // 支付提供商，可选值：alipay、wxpay
trade_no: 'trade-no', // 商户订单号
total_fee: 100, // 订单金额，单位：分
subject: '商品名称', // 商品名称
body: '商品描述', // 商品描述
notify_url: 'https://example.com/notify', // 支付结果通知地址
return_url: 'https://example.com/return' // 支付结果返回地址
});
console.log(result.payment); // 支付参数
9.4.3 查询支付订单
// 查询支付订单
const result = await uniPay.queryOrder({
provider: 'alipay', // 支付提供商
trade_no: 'trade-no' // 商户订单号
});
console.log(result.orderInfo); // 订单信息
9.4.4 关闭支付订单
// 关闭支付订单
const result = await uniPay.closeOrder({
provider: 'alipay', // 支付提供商
trade_no: 'trade-no' // 商户订单号
});
console.log(result.closed); // 关闭结果
9.4.5 申请退款
// 申请退款
const result = await uniPay.refund({
provider: 'alipay', // 支付提供商
trade_no: 'trade-no', // 商户订单号
refund_fee: 100, // 退款金额，单位：分
refund_reason: '退款原因' // 退款原因
});
console.log(result.refundInfo); // 退款信息
10. 总结
uniCloud提供了丰富的内置API和扩展API，包括：
- 数据库API：用于操作数据库，包括查询、添加、更新、删除和聚合操作。
- 存储API：用于操作云存储，包括上传、下载、删除、获取文件信息和获取临时访问链接。
- 云函数API：用于调用云函数和导入云对象。
- HTTP请求API：用于发送HTTP请求和接收响应。
- WebSocket API：用于创建WebSocket连接、发送消息和接收消息。
- 请求和环境API：用于获取请求ID、客户端信息和云端信息。
- 配置中心API：用于获取和设置配置。
- 云对象API：用于获取上下文信息和操作Cookie。
- 扩展API：包括Redis扩展库、Push扩展库、uni-id扩展库和uni-pay扩展库等。
通过使用这些API，开发者可以更加高效地开发云函数和云对象，实现各种业务逻辑。
