提交 03e7f41a 编写于 作者: 雪洛's avatar 雪洛

docs: uniCloud

上级 2514e559
......@@ -48,7 +48,6 @@
* [uni-sec-check 内容安全](https://ext.dcloud.net.cn/plugin?id=5460)
* [统一发行页面](https://uniapp.dcloud.io/m3w)
* [uni-cloud-router](uniCloud/uni-cloud-router.md)
* [同时连多服务空间](uniCloud/init.md)
* [案例](uniCloud/resource.md)
* [开发者使用反馈](uniCloud/feedback.md)
* [DCloud行业认证服务商](https://ask.dcloud.net.cn/article/39388)
......
......@@ -14,12 +14,76 @@
## 名词解释
- Ticket(票据):由云函数调用`createTicket`返回的票据,用于客户端使用票据进行登录操作
- Ticket(票据):由云函数调用`auth.createTicket`返回的票据,用于客户端使用票据进行登录操作
- 匿名登录:用户未进行登录操作的状态
- 短期访问令牌:用户身份的凭证(access token),调用`signInWithTicket`或者`linkAndRetrieveDataWithTicket`之后会自动进行存储
## uniCloud.customAuth()
## 云函数接口
### uniCloud.customAuth@cloud-custom-auth
**重要:自HBuilderX 2.9.12起,此接口由uniCloud.auth调整为uniCloud.customAuth,短时间内仍会兼容uniCloud.auth**
获取登录对象
**示例代码**
```js
const auth = uniCloud.customAuth()
```
### auth.createTicket@cloud-create-ticket
云端根据用户id创建票据用于客户端登录到对应的云厂商
**接口形式**
```js
auth.createTicket(String uid, Object options)
```
**参数说明**
|字段 |类型 |是否必填 |说明 |
|:-: |:-: |:-: |:-: |
|uid |string |是 |应用内的用户唯一id |
|options.refresh|number |否 |access_token的刷新时间,默认一小时 |
|options.expire |number |否 |access_token的过期时间 |
**示例代码**
```js
let uid = '123456';
const ticket = uniCloud.customAuth().createTicket(uid, {
refresh: 10 * 60 * 1000 // 每十分钟刷新一次登录态, 默认为一小时
});
```
### auth.getUserInfo@cloud-get-user-info
任何方式登录成功后,可以调用 `getUserInfo` 获得用户的身份信息。
**响应参数**
|字段 |类型 |是否必备 |说明 |
|:-: |:-: |:-: |:-: |
|uid |string |是 |用户在云厂商的唯一ID |
|customUserId |string |否 |用户使用自定义登录传入的用户Id |
**示例代码**
```js
const {
uid,
customUserId
} = await auth.getUserInfo()
```
## 客户端接口
### uniCloud.customAuth@custom-auth
**重要:自HBuilderX 2.9.12起,此接口由uniCloud.auth调整为uniCloud.customAuth,短时间内仍会兼容uniCloud.auth**
......@@ -42,9 +106,9 @@ const auth = uniCloud.customAuth()
auth.signInAnonymously()
``` -->
## auth.signInWithTicket()@signinwithticket
### auth.signInWithTicket@signinwithticket
使用,详细描述参考[登录流程](#cloudtoken)
使用云函数接口createTicket返回的票据进行登录,详细描述参考[登录流程](#cloudtoken)
**示例代码**
......@@ -58,7 +122,7 @@ auth.signInWithTicket('YourTicket').then(() => {
})
```
## auth.getLoginState()
### auth.getLoginState@get-login-state
开发者可以通过 `getLoginState()` 来获取当前的登录状态,调用 `getLoginState()` 后,SDK 会识别本地是否有登录状态,如果有,则会尝试刷新登录状态,若刷新登录状态成功,则会返回新的登录状态,否则返回 `undefined`
......@@ -74,16 +138,16 @@ auth.getLoginState().then(loginState => {
})
```
## auth.getUserInfo()
### auth.getUserInfo@get-user-info
任何方式登录成功后,可以调用 `getUserInfo` 获得用户的身份信息。
**响应参数**
|字段 |类型 |是否必备 |说明 |
|:-: |:-: |:-: |:-: |
|uid |string |是 |用户在云开发的唯一ID |
|customUserId |string |否 |用户使用自定义登录传入的用户Id |
|字段 |类型 |是否必备 |说明 |
|:-: |:-: |:-: |:-: |
|uid |string |是 |用户在云厂商的唯一ID |
|customUserId |string |否 |用户使用自定义登录传入的用户Id |
**示例代码**
......
......@@ -164,7 +164,7 @@ exports.main = async (event, context) => {
**注意事项**
- event大小不可超过100kb
- 云函数url化的场景下无法获取`context.OS``context.PLATFORM``context.APPID``context.CLIENTUUID`
- 云函数url化的场景下无法获取`context.OS``context.PLATFORM``context.APPID``context.DEVICEID`
>在云函数URL化的场景无法获取客户端平台信息,可以在调用依赖客户端平台的接口接口之前(推荐在云函数入口)通过修改context.PLATFORM手动传入客户端平台信息供其他插件(如:uni-id)使用
......@@ -225,26 +225,12 @@ errCode在成功时应返回数字`0`,失败时应返回一个以插件id开头
errMsg用于存放具体错误信息,包括展示给开发者、终端用户的错误信息
<!-- 占位变量格式说明:
支持情况
1. 从xx版本开始,clientDB遵循该格式
2. 推荐开发者的云函数在返回json数据给客户端时也遵循这种格式。
3. uniCloud客户端sdk后续会提供callFunction及数据库操作的拦截器,开发者可以在拦截器内对特定的错误码进行处理。例如:在收到token过期的错误码时进行提示并跳转到登录页面
4. uniCloud admin和uni-starter等插件内置的网络拦截器也均将支持该格式。
历史兼容说明: -->
云函数中如果要使用其他服务(比如mysql数据库、redis等),可以按照nodejs的写法即可。但注意这些非uniCloud数据库和云函数运行环境不在一起,访问速度受影响。
云函数启动后环境会保留一段时间(如15分钟),超过保留期后若该云函数一直没有被再调用,那这个环境会被释放。
所以云函数有冷启动的概念,由于js环境的启动要比php和java更快,所以js适合serverless方式。
## uniCloud API列表
云函数支持js和nodejs的标准API,但除了标准API外,uniCloud扩展了一批新API,实际开发中更常用的是uniCloud的扩展API。见下:
......
......@@ -7,15 +7,15 @@ uniCloud分为客户端和云端两部分,有些接口名称相同,参数也
客户端API列表
|API |描述 |
|-- |-- |
|uniCloud.callFunction() |客户端调用云函数 [详情](https://uniapp.dcloud.net.cn/uniCloud/cf-functions?id=clientcallfunction) |
|uniCloud.database() |客户端访问云数据库,获取云数据库对象引用 [详情](https://uniapp.dcloud.net.cn/uniCloud/clientdb) |
|uniCloud.uploadFile() |客户端直接上传文件到云存储 [详情](https://uniapp.dcloud.net.cn/uniCloud/storage?id=uploadfile) |
|uniCloud.getTempFileURL() |客户端获取云存储文件的临时路径 [详情](https://uniapp.dcloud.net.cn/uniCloud/storage?id=gettempfileurl) |
|uniCloud.chooseAndUploadFile() |客户端选择文件并上传 [详情](https://uniapp.dcloud.net.cn/uniCloud/storage?id=chooseanduploadfile) |
|uniCloud.getCurrentUserInfo() |获取当前用户信息 [详情](https://uniapp.dcloud.io/uniCloud/client-sdk?id=client-getcurrentuserinfo) |
|uniCloud.init() |同时使用多个服务空间时初始化额外服务空间 [详情](https://uniapp.dcloud.net.cn/uniCloud/init) |
|API |描述 |
|-- |-- |
|uniCloud.callFunction() |客户端调用云函数 [详情](https://uniapp.dcloud.net.cn/uniCloud/cf-functions?id=clientcallfunction) |
|uniCloud.database() |客户端访问云数据库,获取云数据库对象引用 [详情](https://uniapp.dcloud.net.cn/uniCloud/clientdb) |
|uniCloud.uploadFile() |客户端直接上传文件到云存储 [详情](https://uniapp.dcloud.net.cn/uniCloud/storage?id=uploadfile) |
|uniCloud.getTempFileURL() |客户端获取云存储文件的临时路径 [详情](https://uniapp.dcloud.net.cn/uniCloud/storage?id=gettempfileurl) |
|uniCloud.chooseAndUploadFile() |客户端选择文件并上传 [详情](https://uniapp.dcloud.net.cn/uniCloud/storage?id=chooseanduploadfile) |
|uniCloud.getCurrentUserInfo() |获取当前用户信息 [详情](#client-getcurrentuserinfo) |
|uniCloud.init() |同时使用多个服务空间时初始化额外服务空间 [详情](https://uniapp.dcloud.net.cn/uniCloud/init) |
### 获取当前用户信息getCurrentUserInfo@client-getcurrentuserinfo
......
`uniCloud`提供了一个 JSON 格式的文档型数据库,数据库中的每条记录都是一个 JSON 格式的对象。一个数据库可以有多个集合(相当于关系型数据中的表),集合可看做一个 JSON 数组,数组中的每个对象就是一条记录,记录的格式是 JSON 对象。
更多云数据库介绍参考[规范](uniCloud/cf-database)
更多云数据库介绍参考[规范](uniCloud/hellodb.md)
......@@ -22,10 +22,10 @@ web控制台可以新建、删除服务空间,管理线上的服务空间资
**新建服务空间注意**
- 第一次创建腾讯云服务空间时会为用户创建腾讯云账号并跳转到腾讯云实名界面,等待实名认证审核之后可以开通服务空间。若腾讯云实名认证提示身份证下已创建过多账户,则需要在腾讯云官网注销不用的账户。[详见](/uniCloud/faq?id=%e8%85%be%e8%ae%af%e4%ba%91%e6%8f%90%e7%a4%ba%e5%bd%93%e5%89%8d%e5%ae%9e%e5%90%8d%e4%b8%bb%e4%bd%93%e5%b7%b2%e7%bb%8f%e6%9c%89%e4%b8%89%e4%b8%aa%e8%b4%a6%e5%8f%b7%e6%80%8e%e4%b9%88%e5%8a%9e)
- 第一次创建腾讯云服务空间时会为用户创建腾讯云账号并跳转到腾讯云实名界面,等待实名认证审核之后可以开通服务空间。若腾讯云实名认证提示身份证下已创建过多账户,则需要在腾讯云官网注销不用的账户。[详见](/uniCloud/faq?id=tencent-exceed-account-limit)
- 创建服务空间可能需要几十秒的时间,可以在web控制台查看是否创建完成。
## 多人协作
## 多人协作@collaboration
一个服务空间只有一个创建者,但可以设置协作者。
......@@ -58,13 +58,13 @@ web控制台可以新建、删除服务空间,管理线上的服务空间资
服务空间和手机端项目是多对多绑定关系。同DCloud账号下,一个应用可以关联到多个服务空间。一个服务空间也可以被多个项目访问。
### 多应用共用服务空间
### 多应用共用服务空间@multi-app
比如一个项目的用户端和管理端,在HBuilderX里可以创建成2个项目,但2个项目的服务空间可以指向一个,或者干脆把其中一个项目的服务空间绑定到另一个项目上。
[详见](https://ask.dcloud.net.cn/article/37949)
### 一个应用访问多个服务空间
### 一个应用访问多个服务空间@multi-space
若应用仅连接一个服务空间,在HBuilderX中做好服务空间关联即可。开发者无需手动做初始化工作(可理解为类调用)。
......@@ -117,4 +117,4 @@ myCloud.uploadFile()
- 云函数会自动识别自己所属的服务空间,无需初始化。
- 腾讯云支持在云函数内初始化本账号下的其他服务空间
uniCloud还支持跨服务空间的数据库访问,另见[文档](https://uniapp.dcloud.net.cn/uniCloud/init?id=init-db)
\ No newline at end of file
uniCloud还支持跨服务空间的数据库访问,另见[文档](https://uniapp.dcloud.net.cn/uniCloud/hellodb?id=init-db)
\ No newline at end of file
......@@ -219,7 +219,7 @@ uniCloud的每个云函数是一个独立进程,不存在云函数级别的多
2. 将上述域名CNAME到`api.bspapp.com`
3. [自行初始化uniCloud](uniCloud/init.md)传入endpoint参数,其值为开通全球加速的自有域名
### 腾讯云提示当前实名主体已经有三个账号怎么办
### 腾讯云提示当前实名主体已经有三个账号怎么办@tencent-exceed-account-limit
开通腾讯云服务空间时实名认证提示实名主体已有三个账号,这往往是开发者在微信小程序开发工具里不小心开通了多个免费的小程序云,此时可以参考以下流程注销不用的账号:
......@@ -287,7 +287,7 @@ exports.main = async function(event){
### 授权其他用户访问服务空间@collaborator
详见文档:[服务空间的多人协作](/uniCloud/concepts/space?id=%e5%a4%9a%e4%ba%ba%e5%8d%8f%e4%bd%9c)
详见文档:[服务空间的多人协作](/uniCloud/concepts/space?id=collaboration)
### 如何使用promise/async/await@promise
......@@ -354,7 +354,7 @@ uniCloud客户端callFunction及数据库相关接口会返回Promise类型结
- bspapp.com,属于阿里云。如果该域名访问报错,说明阿里云serverless出故障了。
- tencentcloudapi.com,属于腾讯云。如果该域名访问报错,说明腾讯云serverless出故障了。
当然还有一种情况报错,其实是客户端的问题,包括浏览器的跨域问题,或者小程序的域名白名单问题,导致客户端无法连接uniCloud。这需要通过配置来解决,参考文档:[小程序和浏览器的域名访问配置](https://uniapp.dcloud.io/uniCloud/quickstart?id=%e5%b0%8f%e7%a8%8b%e5%ba%8f%e4%b8%ad%e4%bd%bf%e7%94%a8unicloud%e7%9a%84%e7%99%bd%e5%90%8d%e5%8d%95%e9%85%8d%e7%bd%ae)
当然还有一种情况报错,其实是客户端的问题,包括浏览器的跨域问题,或者小程序的域名白名单问题,导致客户端无法连接uniCloud。这需要通过配置来解决,参考文档:[小程序和浏览器的域名访问配置](https://uniapp.dcloud.io/uniCloud/quickstart?id=useinmp)
2. 通过测试系统判断故障点
- [hello uniCloud 阿里云版](https://hellounicloud.dcloud.net.cn/#/)
......
......@@ -104,25 +104,39 @@ exports.main = async (event, context) => {
};
```
**获取其他服务空间的数据库实例**
## 获取其他服务空间数据库实例@init-db
> 仅腾讯云在云函数内可用
如果当前应用仅使用一个服务空间,在HBuilderX中做好服务空间关联即可。获取当前空间的数据库实例时无需传递配置,直接调用database方法即可
接口形式:`uniCloud.database(Object DBOptions)`
```js
const db = uniCloud.database()
```
如果应用有连接其他服务空间数据库的需求,可以在获取database实例时传递对应服务空间的配置
> HBuilderX 3.2.11及更高版本支持客户端初始化其他服务空间database实例,此前仅腾讯云云函数环境支持。阿里云云函数环境不支持此用法。
**DBOptions参数说明**
调用`uniCloud.database()`时可以传入对应的服务空间信息(参数同uniCloud.init,参考:[uniCloud.init](uniCloud/init.md?id=init-unicloud))来获取指定服务空间的database实例。
|字段 |类型 |必填 |描述 |平台差异说明 |
|:-: |:-: |:-: |:-: |:-: |
|spaceId|String |否 |同一账号下的服务空间ID |仅腾讯云支持 |
**示例**
```js
// 如果ID为tcb-space-demo的服务空间也在你的账号下,可以通过这种方式访问tcb-space-demo的数据库。调用此接口的服务空间和tcb-space-demo对应的服务空间均为腾讯云才可以正常使用
const db = uniCloud.database({
spaceId: 'tcb-space-demo'
});
provider: 'tencent',
spaceId: 'xxx'
})
db.collection('uni-id-users').get()
```
**参数说明**
|参数名 |类型 |必填 |默认值 |说明 |
|:-: |:-: |:-: |:-: |:-: |
|provider |String |是 |- |aliyun、tencent |
|spaceId |String |是 |- |服务空间ID,**注意是服务空间ID,不是服务空间名称** |
|clientSecret |String |是 |- |仅阿里云支持,可以在[uniCloud控制台](https://unicloud.dcloud.net.cn)服务空间列表中查看 |
|endpoint |String |否 |`https://api.bspapp.com` |服务空间地址,仅阿里云侧支持 |
## 创建一个集合/数据表@createCollection
......
## 初始化uniCloud实例@init-unicloud
文档已迁移至:[一个应用访问多个服务空间](https://uniapp.dcloud.net.cn/uniCloud/concepts/space?id=%e4%b8%80%e4%b8%aa%e5%ba%94%e7%94%a8%e8%ae%bf%e9%97%ae%e5%a4%9a%e4%b8%aa%e6%9c%8d%e5%8a%a1%e7%a9%ba%e9%97%b4)
文档已迁移至:[一个应用访问多个服务空间](uniCloud/concepts/space.md?id=multi-space)
## 获取其他服务空间的database@init-db
> HBuilderX 3.2.11及更高版本支持客户端初始化其他服务空间database实例,此前仅腾讯云云函数环境支持。阿里云云函数环境不支持此用法。
调用`uniCloud.database()`时可以传入对应的服务空间信息(参数同uniCloud.init,参考:[uniCloud.init](uniCloud/init.md?id=init-unicloud))来获取指定服务空间的database实例。
**示例**
```js
const db = uniCloud.database({
provider: 'tencent',
spaceId: 'xxx'
})
db.collection('uni-id-users').get()
```
**参数说明**
|参数名 |类型 |必填 |默认值 |说明 |
|:-: |:-: |:-: |:-: |:-: |
|provider |String |是 |- |aliyun、tencent |
|spaceId |String |是 |- |服务空间ID,**注意是服务空间ID,不是服务空间名称** |
|clientSecret |String |是 |- |仅阿里云支持,可以在[uniCloud控制台](https://unicloud.dcloud.net.cn)服务空间列表中查看 |
|endpoint |String |否 |`https://api.bspapp.com` |服务空间地址,仅阿里云侧支持 |
文档已迁移至:[一个应用访问多个服务空间](uniCloud/hellodb.md?id=init-db)
......@@ -285,7 +285,7 @@ db.collection('user').where({
|DUPLICATE_KEY |索引冲突 |
|SYSTEM_ERROR |系统错误 |
如需自定义返回的err对象,可以在clientDB中挂一个[action云函数](uniCloud/database?id=action),在action云函数的`after`内用js修改返回结果,传入`after`内的result不带code和message。
如需自定义返回的err对象,可以在clientDB中挂一个[action云函数](#action),在action云函数的`after`内用js修改返回结果,传入`after`内的result不带code和message。
## 查询数据@query
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册