Skip to content
体验新版
项目
组织
正在加载...
登录
切换导航
打开侧边栏
joossbown
unidocs-zh
提交
fefc29b9
U
unidocs-zh
项目概览
joossbown
/
unidocs-zh
与 Fork 源项目一致
Fork自
DCloud / unidocs-zh
通知
1
Star
0
Fork
0
代码
文件
提交
分支
Tags
贡献者
分支图
Diff
Issue
0
列表
看板
标记
里程碑
合并请求
0
DevOps
流水线
流水线任务
计划
Wiki
0
Wiki
分析
仓库
DevOps
项目成员
Pages
U
unidocs-zh
项目概览
项目概览
详情
发布
仓库
仓库
文件
提交
分支
标签
贡献者
分支图
比较
Issue
0
Issue
0
列表
看板
标记
里程碑
合并请求
0
合并请求
0
Pages
DevOps
DevOps
流水线
流水线任务
计划
分析
分析
仓库分析
DevOps
Wiki
0
Wiki
成员
成员
收起侧边栏
关闭侧边栏
动态
分支图
创建新Issue
流水线任务
提交
Issue看板
体验新版 GitCode,发现更多精彩内容 >>
提交
fefc29b9
编写于
6月 29, 2022
作者:
W
wanganxp
浏览文件
操作
浏览文件
下载
电子邮件补丁
差异文件
提交普通云函数新版文档
上级
f8ee0e64
变更
1
隐藏空白更改
内联
并排
Showing
1 changed file
with
75 addition
and
65 deletion
+75
-65
docs/uniCloud/cf-callfunction.md
docs/uniCloud/cf-callfunction.md
+75
-65
未找到文件。
docs/uniCloud/cf-callfunction.md
浏览文件 @
fefc29b9
...
...
@@ -26,13 +26,15 @@ callFunction方式避免了服务器提供域名,不暴露固定ip,减少被
|字段 |类型 |说明 |
|:-: |:-: |:-: |
|result |Object |云函数
返回结果
|
|result |Object |云函数
中代码return的返回结果
|
|requestId |String |云函数请求序列号,用于错误排查,可以在uniCloud web控制台的云函数日志中查到 |
|header |Object |服务器header信息 |
|errCode |Number或String |服务器错误码 |
|success |bool |执行是否成功 |
注意:HBuilderX本地运行云函数时只返回result,其他需要在云端运行云函数才会返回
注意:HBuilderX本地运行云函数时只返回
`result`
,其他需要在云端运行云函数才会返回
返回格式,下文有详细解读
[
详见
](
?id=returnformat
)
**前端示例代码**
...
...
@@ -60,7 +62,7 @@ uniCloud.callFunction({
客户端callFunction调用云函数时,云函数通过入参接收客户端数据,通过头信息上下文获取客户端信息,经过业务逻辑处理后给客户端返回结果。
假使客户端代码调用云函数
hellocf,并传递了{a:1,b:2}
的数据,
假使客户端代码调用云函数
`hellocf`
,并传递了
`{a:1,b:2}`
的数据,
```
js
// 客户端调用云函数并传递参数
uniCloud
.
callFunction
({
...
...
@@ -76,78 +78,91 @@ uniCloud.callFunction({
'
use strict
'
;
exports
.
main
=
async
(
event
,
context
)
=>
{
//event为客户端上传的参数
let
c
=
event
.
a
+
event
.
b
return
{
sum
:
event
.
a
+
event
.
b
sum
:
c
}
// 通过return返回结果给客户端
}
```
云函数的传入参数有两个,一个是
`event`
对象,一个是
`context`
对象。
-
`event`
指的是触发云函数的事件。当客户端调用云函数时,
`event`
就是客户端调用云函数时传入的参数。
-
`context`
对象包含了本次请求的上下文,包括客户端的操作系统(
`os`
)、运行平台(
`platform`
)、应用信息(
`appid`
)
-
`context`
对象包含了本次请求的上下文,包括客户端的ip、ua、appId等信息,以及云函数的环境情况、调用来源source等信息。
### event对象
event对象,可以理解为客户端上行参数中的json对象。在使用
`uni-id`
且登录成功后,会自动多添加了一个
`uniIdToken`
属性。
如下是一个示例
:
可以通过
`event.uniIdToken`
获取 uni-id 的 token,如下
:
```
js
'
use strict
'
;
exports
.
main
=
async
(
event
,
context
)
=>
{
//event为客户端上传的参数
//...
//context中可获取客户端调用的上下文
let
clientIP
=
context
.
CLIENTIP
// 客户端ip信息
let
clientUA
=
context
.
CLIENTUA
// 客户端user-agent
let
spaceInfo
=
context
.
SPACEINFO
// 当前环境信息 {spaceId:'xxx',provider:'tencent'}
// 以下四个属性只有使用uni-app以callFunction方式调用才能获取,调用方不是uni-app客户端则没有相应数据
let
os
=
context
.
OS
//客户端操作系统,返回值:android、ios 等
let
platform
=
context
.
PLATFORM
//运行平台,返回值为 mp-weixin、app-plus等。注意:vue3版本uni-app将app-plus修改为了app,此处为保证旧版本兼容性未进行统一,推荐后续在业务中都使用app作为客户端标识
let
appid
=
context
.
APPID
// manifest.json中配置的appid
let
deviceId
=
context
.
DEVICEID
// 客户端标识,新增于HBuilderX 3.1.0,同uni-app客户端getSystemInfo接口获取的deviceId
//... //其它业务代码
let
token
=
event
.
uniIdToken
// 客户端uni-id token
}
```
**注意:下面所有的“客户端”均是相对于云函数而言,如果你使用自己的服务器调用云函数,此时客户端是指你的服务器**
所以开发者需注意,自己上行的参数对象不要包含uniIdToken属性,避免同名冲突。
### 获取用户token@client-token
**入参的体积限制**
如果客户端在storage内存储了uni_id_token,在使用callFunction请求云函数时会自动将此token传递到云端,云端可以通过以下方式获取:
云函数上行的参数内容不能传太大。
```
js
'
use strict
'
;
exports
.
main
=
async
(
event
,
context
)
=>
{
let
token
=
event
.
uniIdToken
// 客户端uni-id token
}
```
-
阿里云event大小不可超过1MB
-
腾讯云event大小不可超过6MB
###
获取客户端IP@clientip
###
context对象
```
js
'
use strict
'
;
exports
.
main
=
async
(
event
,
context
)
=>
{
let
clientIP
=
context
.
CLIENTIP
// 客户端ip信息
}
```
-
`context`
对象包含了本次请求的上下文,包括客户端的ip、ua、appId等信息,以及云函数的环境情况、调用来源source等信息。
### 获取客户端user-agent@client-user-agent
context对象的属性清单如下:
```
js
'
use strict
'
;
exports
.
main
=
async
(
event
,
context
)
=>
{
let
clientUA
=
context
.
CLIENTUA
// 客户端user-agent信息
}
```
|属性名称 |类型 |说明 |
|-- |-- |-- |
|SPACEINFO |object |服务空间信息 |
|
|
- spaceId |string |服务空间id |
|
|
- provider |string |服务空间供应商:aliyun
|
tencent |
|SOURCE |string |云函数调用来源
[
详见
](
?id=context-source
)
|
|FUNCTION_NAME |string |获取云函数名称 |
|CLIENTIP |string |客户端IP。如果调用来源是其他服务器,会返回调用方的ip|
### 获取服务空间信息@context-space-info
除了上述属性,如果是uni-app客户端通过callfunction访问云函数,那么context还会追加一批客户端信息。
-
HBuilderX 3.4.9前,context 添加了一批大写属性,如APPID、OS。
-
HBuilderX 3.4.9起,context 的属性包括前端API
`uni.getSystemInfo`
的所有属性。比如appId、osName,均以驼峰方式命名。这些属性较多,且可能跟随前端API更新而变化,具体详见
[
uni.getSystemInfo
](
/api/system/info.html#getsysteminfo
)
为了保持向下兼容,新版并没有去掉老版那些大写属性的客户端信息,但文档标注为以废弃。对于新版HBuilderX用户而言,请使用
`uni.getSystemInfo`
返回的驼峰属性。
示例:
```
js
'
use strict
'
;
exports
.
main
=
async
(
event
,
context
)
=>
{
//event为客户端上传的参数
//...
//context中可获取客户端调用的上下文
let
clientIP
=
context
.
CLIENTIP
// 客户端ip信息
let
spaceInfo
=
context
.
SPACEINFO
// 当前环境信息 {spaceId:'xxx',provider:'tencent'}
let
source
=
context
.
SOURCE
// 云函数调用来源
// 以下属性只有使用uni-app以callFunction方式调用才能获取,即context.SOURCE=="client",调用方不是uni-app客户端则没有相应数据
let
appid
=
context
.
appId
// manifest.json中配置的appid
let
deviceId
=
context
.
deviceId
// 客户端标识,新增于HBuilderX 3.1.0,同uni-app客户端getSystemInfo接口获取的deviceId
//... //其它业务代码
}
```
### 获取云函数调用来源@context-source
context.SOURCE,返回云函数调用来源,它的值域为:
|取值 |解释 |
|-- |-- |
|client |客户端callFunction方式调用 |
|http |云函数url化方式调用 |
|timing |定时触发器调用 |
|function |由其他云函数callFunction调用 |
|server |由uniCloud管理端调用,HBuilderX里上传并运行|
```
js
'
use strict
'
;
exports
.
main
=
async
(
event
,
context
)
=>
{
...
...
@@ -160,30 +175,14 @@ exports.main = async (event, context) => {
}
```
### 其他客户端信息@client-info
> HBuilderX 3.4.9起,可以获取所有客户端`getSystemInfo`返回的客户端信息,详细字段列表参考:[getSystemInfo](https://uniapp.dcloud.net.cn/api/system/info.html#getsysteminfo)
```
js
'
use strict
'
;
exports
.
main
=
async
(
event
,
context
)
=>
{
let
os
=
context
.
OS
//客户端操作系统,返回值:android、ios 等
let
platform
=
context
.
PLATFORM
//运行平台,返回值为 mp-weixin、app等。注意老版曾使用app-plus,具体见下
let
appid
=
context
.
APPID
// manifest.json中配置的appid
let
deviceId
=
context
.
DEVICEID
// 客户端标识,新增于HBuilderX 3.1.0,同uni-app客户端getSystemInfo接口获取的deviceId
}
```
**注意事项**
-
客户端上报的信息在理论上存在被篡改可能,实际业务中应验证前端传来的数据的合法性
-
`context.PLATFORM`
的取值,有
`app`
和
`app-plus`
两种情况。
*
uni-app的vue3版本取值为
`app`
*
vue2版本,在uni-app 3.4.9之前,取值为
`app-plus`
,uni-app 3.4.9起,该值修改为了
`app`
-
阿里云event大小不可超过1MB,腾讯云event大小不可超过6MB
客户端信息只有使用uni-app客户端以callFunction方式调用才能获取,由客户端传递到云函数。如果云函数url化后被uni-app通过request调用,也没有客户端信息。
除了CLIENTIP外,其他客户端信息只有使用uni-app客户端以callFunction方式调用才能获取。如果云函数url化后被uni-app通过request调用,也没有客户端信息。
在云函数URL化的场景无法获取客户端平台信息,可以在调用依赖客户端平台的接口接口之前(推荐在云函数入口)通过修改context.PLATFORM手动传入客户端平台信息供其他插件(如:uni-id)使用
...
...
@@ -195,11 +194,11 @@ exports.main = async (event, context) => {
}
```
## 云函数的返回格式
## 云函数的返回格式
@returnformat
普通云函数返回给客户端的是json格式数据。返回结果包裹在result下。
前端发起callFunction到云端接收参数并响应,然后反馈前端,
然后前端接收参数的
完整流程代码如下:
前端发起callFunction到云端接收参数并响应,然后反馈前端,
前端接收,
完整流程代码如下:
```
js
// 客户端发起调用云函数hellocf,并传入data数据
...
...
@@ -228,7 +227,8 @@ exports.main = async (event, context) => {
那么客户端得到的res结构如下
```
json
{
"errCode"
:
0
"errCode"
:
0
,
"errMsg"
:
""
,
"header"
:
{
"access-control-expose-headers"
:
"Date,x-fc-request-id,x-fc-error-type,x-fc-code-checksum,x-fc-invocation-duration,x-fc-max-memory-usage,x-fc-log-result,x-fc-invocation-code-version"
"content-disposition"
:
"attachment"
...
...
@@ -252,13 +252,23 @@ exports.main = async (event, context) => {
其中
`result`
是开发者云函数代码返回的数据,其余是云平台返回的。
注意:HBuilderX本地运行云函数时只返回
`result`
,其他需要在云端运行云函数才会返回。
注意:HBuilderX本地运行云函数时,如果没有系统错误,则只返回
`result`
,其他需要在云端运行云函数才会返回。
-
errCode为0时,success也是true。
*
表示云函数在系统层面没有运行错误。可以正常返回result。前端callFunction会进入success回调
*
如果开发者的业务有报错,可以在 result 里返回 errCode 和 errMsg。
-
errCode不为0时,success为false。
*
表示云函数在系统层面报错了,比如联网失败、云函数超时、内存超限等错误。前端callFunction会进入fail回调
*
发生系统错误时 result 里无法正常返回业务错误。errCode不为0时,还会返回errMsg。
-
requestId是云函数的请求id,线上运行时,可以在uniCloud web控制台的云函数日志中查看运行日志。
-
header是云厂商的一些信息,阿里云和腾讯云不同,上面示例代码是阿里云的header。
**uniCloud响应体规范**
为了方便统一拦截错误,推荐开发者使用
`uniCloud响应体规范`
,
[
详见
](
uniCloud/cf-functions.md?id=resformat
)
为了方便统一拦截错误,推荐开发者使用
[
uniCloud响应体规范
](
cf-functions.md?id=resformat
)
业务报错时,在 result 里返回 errCode 和 errMsg。如下:
如果按照uniCloud响应体规范,那么云函数代码应该修正为return信息补充errCode和errMsg。如下:
```
js
'
use strict
'
;
exports
.
main
=
async
(
event
,
context
)
=>
{
...
...
编辑
预览
Markdown
is supported
0%
请重试
或
添加新附件
.
添加附件
取消
You are about to add
0
people
to the discussion. Proceed with caution.
先完成此消息的编辑!
取消
想要评论请
注册
或
登录