From 4c981962dd30498310b5ea4c2f92ba6b459f7ca8 Mon Sep 17 00:00:00 2001
From: wangyaqi <wangyaqi988@163.com>
Date: Thu, 11 Aug 2022 16:36:47 +0800
Subject: [PATCH] docs: update uniCloud http trigger

---
 docs/uniCloud/cf-callfunction.md |  41 +-----
 docs/uniCloud/cloud-obj.md       |   3 +
 docs/uniCloud/http.md            | 245 +++++++++++++++++++------------
 3 files changed, 158 insertions(+), 131 deletions(-)

diff --git a/docs/uniCloud/cf-callfunction.md b/docs/uniCloud/cf-callfunction.md
index 29ed2f458..ba8ab02d5 100644
--- a/docs/uniCloud/cf-callfunction.md
+++ b/docs/uniCloud/cf-callfunction.md
@@ -296,44 +296,5 @@ exports.main = async (event, context) => {
 
 ## 在云函数中使用cookie
 
-在某些场景下，cookie依然占有重要地位，例如在云函数URL化的情况下，获取客户端的状态
-
-在云函数中使用cookie需要依赖cookie库[npm页面地址](http://https://www.npmjs.com/package/cookie)，可以通过`npm inistall cookie` 安装
-
-```js
-'use strict';
-
-//引入cookie
-const cookie = require('cookie')
-exports.main = async (event, context) => {
-	//event为客户端上传的参数
-	//如果客户端有cookie，则cookie回随请求携带至服务端，放置在event.headers.cookie中,假设 cookie为“[jwt=自加密base64; app=uniCloud]”
-	console.log('event : ', event)
-    
-        //解析cookie
-        const cookieData = cookie.parse( event.headers.cookie||'' )
-        console.log(cookieData)//输出结果为：{jwt:"自加密base64", app:"uniCloud" }
-
-        //设置cookie到客户端
-
-        const cookieOptions = {
-            //具体参数请查阅 https://www.npmjs.com/package/cookie
-            maxAge: 60 * 60 * 24 * 7,//一周
-            path:"/"
-        }
-        const setCookieData = cookie.serialize('app', 'appName', cookieOptions)
-        return {
-            statusCode: 200,
-            headers: {
-                'content-type': '返回数据类型',
-                'set-cookie': setCookieData
-            },
-            body: '返回数据'
-        }
-	
-};
-
-```
-
-
+详见：[url化场景下使用cookie](http.md#cookie)
 
diff --git a/docs/uniCloud/cloud-obj.md b/docs/uniCloud/cloud-obj.md
index 55545b953..745127a33 100644
--- a/docs/uniCloud/cloud-obj.md
+++ b/docs/uniCloud/cloud-obj.md
@@ -745,6 +745,9 @@ method1(param1) {
 调用该方法时可以看到代码提示：
 ![](https://vkceyugu.cdn.bspapp.com/VKCEYUGU-f184e7c3-1912-41b2-b81f-435d1b37c7b4/a94aa7c2-daa6-4bcb-a74c-d0e5c5c58b12.jpg)
 
+## 在云对象中使用cookie
+
+详见：[url化场景下使用cookie](http.md#cookie)
 
 ## 注意事项
 
diff --git a/docs/uniCloud/http.md b/docs/uniCloud/http.md
index aa111e1aa..e5454bd3c 100644
--- a/docs/uniCloud/http.md
+++ b/docs/uniCloud/http.md
@@ -18,7 +18,7 @@ url化后需要注意以下几点
 
 - 腾讯云免费服务空间最多只支持配置10个云函数URL化地址
 
-## 操作步骤
+## 操作步骤@steps
 
 ### 设置云函数 HTTP 访问地址@set-path
 
@@ -67,15 +67,17 @@ url化后需要注意以下几点
 
 在阿里云申请的ssl证书包含一个pem文件和一个key文件，pem的文本内容为证书内容，key文件的内容为私钥
 
+## 普通云函数@cf-url
+
 ### 通过 HTTP URL 方式访问云函数@request-url
 
-通过`https://${云函数Url化域名}/${path}`直接访问函数，其中`${path}`是配置的函数触发路径。
+通过`https://${云函数Url化域名}/${path}`直接访问函数，其中`${path}`是配置的函数触发路径或其子路径。
 
 ### 云函数的入参@input
 
 使用 HTTP 访问云函数时，HTTP 请求会被转化为特殊的结构体，称之为**集成请求**，结构如下：
 
-```shell
+```js
 {
     path: 'HTTP请求路径，如 /hello',
     httpMethod: 'HTTP请求方法，如 GET',
@@ -87,12 +89,12 @@ url化后需要注意以下几点
 ```
 
 下面是一个示例：
-```shell
+```js
 {
     path: '/',
     httpMethod: 'GET',
     headers: {
-        'host': 'xxx.service.tcloudbase.com',
+        'host': 'xxx.example.com',
         'connection': 'close',
         'user-agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.88 Safari/537.36',
         'accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9',
@@ -109,7 +111,7 @@ url化后需要注意以下几点
 
 使用GET请求`https://${云函数Url化域名}/${functionPath}?a=1&b=2`，云函数接收到的`event`为
 
-```
+```js
 {
     path: '/',
     httpMethod: 'GET',
@@ -120,7 +122,7 @@ url化后需要注意以下几点
 ```
 
 
-使用POST请求`https://${spaceId}.service.tcloudbase.com/${functionPath}`，云函数接收到的`event.body`为请求发送的数据，**uni.request默认content-type为application/json**
+使用POST请求`https://${云函数Url化域名}/${functionPath}`，云函数接收到的`event.body`为请求发送的数据，**uni.request默认content-type为application/json**
 
 ```js
 // 以uni.request为例
@@ -149,51 +151,52 @@ uni.request({
 }
 ```
 
-**注意**
+### 云函数url化返回值
 
-- 阿里云目前请求与响应有如下限制
-  + 请求Body大小限制，不能超过1MB。
-  + 响应Body大小限制，不能超过1MB。
+参考：[url化返回值](#output)
 
-- 腾讯云目前请求与响应有如下限制
-  + 请求Body大小限制，文本不能超过100KB，二进制不能超过20MB。
-  + 响应Body大小限制，不能超过6MB。
 
->在云函数URL化的场景无法获取客户端平台信息，可以在调用依赖客户端平台的接口接口之前（推荐在云函数入口）通过修改context.PLATFORM手动传入客户端平台信息
+## 云对象使用url化@cloudobject
 
-例：
+云对象使用url化配置仍需按照上文的操作步骤来，参考：[url化操作步骤](#steps)
 
-```js
-exports.main = async (event, context) => {
-	context.PLATFORM = 'app'
-}
-```
+### 通过 HTTP URL 方式访问云对象@request-co-url
 
-云函数接收到的post请求的请求体可能是被转成base64的，如果是这样需要进行一次转化。
+调用url化的云对象时，以`url化路径/云对象方法名`形式的链接访问云对象的方法。例如：云对象配置的触发路径是`/todo`，调用`/todo/addTodo`即会触发云对象的addTodo方法。方法区分大小写且不可含`/`。
 
-以接收application/json格式的post请求为例
+### 云对象入参@input
+
+url内query部分会被转换成云对象方法的入参。以下面的todo云对象为例
 
 ```js
-exports.main = function(event) {
-    let body = event.body
-    if(event.isBase64Encoded){
-      body = Buffer.from(body)
-    }
-    const param = JSON.parse(body) // param为客户端上传的数据
-    // ...
+module.exports = {
+	addTodo: function(params) { 
+		console.log(params)
+        return {
+            errCode: 0
+        }
+	}
 }
 ```
 
-**关于path的说明**
+如果通过`https://xxx.com/todo/addTodo?title=todo-title&content=todo-content`调用云对象，todo方法内的console.log会输出以下内容`{title: 'todo-title', content: 'todo-content'}`
+
+需要注意的是自url内解析出的参数均为字符串类型。
+
+**注意**
+
+- url化方式调用云对象时，`_before`和`_after`均正常执行
+- 如果需要获取其他方式传入云对象的参数（如：post一个json内容到云对象），请使用[this.getHttpInfo](cloud-obj.md#get-http-info)获取
 
-url化场景下，event.path表示以配置的url化路径为根路径的访问路径。以配置`/test`为云函数url化路径，访问`/test/a/b/c`时event.path为`/a/b/c`
+### 云对象url化返回值
 
+参考：[url化返回值](#output)
 
-### 云函数的返回值@output
+## url化返回值@output
 
-云函数可以返回`string`、`object`、`number`等类型的数据，或者返回 [集成响应](#Integrationresponse)，随后云接入会将返回值转化为正常的 HTTP 响应。
+云函数、云对象可以返回`string`、`object`、`number`等类型的数据，或者返回 [集成响应](#Integrationresponse)，uniCloud会将返回值转化为正常的 HTTP 响应。
 
-#### 返回字符串或数字
+### 返回字符串或数字
 
 云函数返回字符串，那么：
 ```js
@@ -212,7 +215,7 @@ content-length: 13
 hello gateway
 ```
 
-#### 返回 Object
+### 返回 Object
 
 返回的`Object`会被转换为 JSON，同时 HTTP 响应的`content-type`会被设置为 `application/json`：
 
@@ -234,7 +237,7 @@ content-length: 13
 {"foo":"bar"}
 ```
 
-#### 返回集成响应@Integrationresponse
+### 返回集成响应@Integrationresponse
 
 云函数可以返回如下这样特殊结构的**集成响应**，来自由地控制响应体：
 
@@ -250,22 +253,20 @@ content-length: 13
 
 **headers内可以返回传统服务器的所有响应头，包括Set-Cookie、Content-Type等**
 
-##### 使用集成响应返回 HTML
+#### 使用集成响应返回HTML
 
 将`content-type`设置为`text/html`，即可在`body`中返回 HTML，会被浏览器自动解析：
 
 **阿里云默认域名无法返回html并在浏览器中展示，只可以触发下载（无法修改Content-Disposition）。绑定自定义域名无此限制**
 
 ```js
-exports.main = function() {
-    return {
-        mpserverlessComposedResponse: true, // 使用阿里云返回集成响应是需要此字段为true
-        statusCode: 200,
-        headers: {
-            'content-type': 'text/html'
-        },
-        body: '<h1>Hello</h1>'
-    }
+{
+    mpserverlessComposedResponse: true, // 使用阿里云返回集成响应是需要此字段为true
+    statusCode: 200,
+    headers: {
+        'content-type': 'text/html'
+    },
+    body: '<h1>Hello</h1>'
 }
 ```
 
@@ -279,20 +280,18 @@ content-length: 14
 <h1>Hello</h1>
 ```
 
-##### 使用集成响应返回 JS 文件
+#### 使用集成响应返回 JS 文件
 
 将`content-type`设置为`application/javascript`，即可在`body`中返回 JavaScript 文件：
 
 ```js
-exports.main = function() {
-    return {
-        mpserverlessComposedResponse: true, // 使用阿里云返回集成响应是需要此字段为true
-        statusCode: 200,
-        headers: {
-            'content-type': 'application/javascript'
-        },
-        body: 'console.log("Hello!")'
-    }
+{
+    mpserverlessComposedResponse: true, // 使用阿里云返回集成响应是需要此字段为true
+    statusCode: 200,
+    headers: {
+        'content-type': 'application/javascript'
+    },
+    body: 'console.log("Hello!")'
 }
 ```
 
@@ -306,21 +305,19 @@ content-length: 21
 console.log("Hello!")
 ```
 
-##### 使用集成响应返回二进制文件
+#### 使用集成响应返回二进制文件
 
 如果返回体是诸如图片、音视频这样的二进制文件，那么可以将`isBase64Encoded`设置为`true`，并且将二进制文件内容转为 Base64 编码的字符串，例如：
 
 ```js
-exports.main = function() {
-    return {
-        mpserverlessComposedResponse: true, // 使用阿里云返回集成响应是需要此字段为true
-        isBase64Encoded: true,
-        statusCode: 200,
-        headers: {
-            'content-type': 'image/png'
-        },
-        body: 'iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAY...'
-    }
+{
+    mpserverlessComposedResponse: true, // 使用阿里云返回集成响应是需要此字段为true
+    isBase64Encoded: true,
+    statusCode: 200,
+    headers: {
+        'content-type': 'image/png'
+    },
+    body: 'iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAY...'
 }
 ```
 
@@ -335,46 +332,112 @@ content-length: 9897
 <binary payload...>
 ```
 
-##### 返回不同的状态码
+#### 返回不同的状态码
 
 如需重定向或返回4xx，5xx等自定义状态码等，可以使用如下方式
 
 **注意：阿里云默认域名不支持在返回的header里面使用location，绑定自定义域名能正常使用**
 
 ```js
-exports.main = function() {
-    return {
-        mpserverlessComposedResponse: false, // 使用阿里云返回集成响应是需要此字段为true
-        isBase64Encoded: false,
-        statusCode: 301,
-        headers: {
-            'location': 'http://www.baidu.com'
-        }
+{
+    mpserverlessComposedResponse: false, // 使用阿里云返回集成响应是需要此字段为true
+    isBase64Encoded: false,
+    statusCode: 301,
+    headers: {
+        'location': 'http://www.baidu.com'
     }
 }
 ```
 
-### 云对象使用url化@cloudobject
-
-云对象使用url化配置方式和云函数一致，需要先在[uniCloud web控制台](https://unicloud.dcloud.net.cn/home)的云对象详情里面设置URL的PATH部分。生产环境建议绑定自定义域名，参考：[云函数绑定自定义域名](#custom-domain)
+## 处理cookie@cookie
 
-调用url化的云对象时，以`url化路径/云对象方法名`形式的链接访问云对象的方法。例如：云对象配置的触发路径是`/todo`，调用`/todo/addTodo`即会触发云对象的addTodo方法。方法区分大小写且不可含`/`。
+在某些场景下，cookie依然占有重要地位，例如在云函数URL化的情况下，获取客户端的状态
 
-url内query部分会被转换成云对象方法的入参。以下面的todo云对象为例
+在云函数中使用cookie需要依赖cookie库[npm页面地址](http://https://www.npmjs.com/package/cookie)，可以通过`npm inistall cookie` 安装
 
 ```js
-module.exports = {
-	addTodo: function(params) { 
-		console.log(params)
+// 普通云函数
+'use strict';
+//引入cookie
+const cookie = require('cookie')
+exports.main = async (event, context) => {
+	const cookieData = cookie.parse(event.headers.cookie || '')
+	//设置cookie到客户端
+	const cookieOptions = {
+		//具体参数请查阅 https://www.npmjs.com/package/cookie
+		maxAge: 60 * 60 * 24 * 7,//一周
+		path:"/"
 	}
-}
+	const setCookieData = cookie.serialize('app', 'appName', cookieOptions)
+	return {
+		statusCode: 200,
+		headers: {
+				'content-type': '返回数据类型',
+				'set-cookie': setCookieData // 在headers内返回set-cookie用于设置客户端cookie
+		},
+		body: '返回数据'
+	}
+};
+
+// 云对象
+'use strict';
+//引入cookie
+const cookie = require('cookie')
+module.exports = {
+  addTodo: function () {
+    const httpInfo = this.getHttpInfo()
+    const cookieData = cookie.parse(httpInfo.headers.cookie || '')
+    //设置cookie到客户端
+    const cookieOptions = {
+    	//具体参数请查阅 https://www.npmjs.com/package/cookie
+    	maxAge: 60 * 60 * 24 * 7,//一周
+    	path:"/"
+    }
+    const setCookieData = cookie.serialize('app', 'appName', cookieOptions)
+    return {
+    	statusCode: 200,
+    	headers: {
+    			'content-type': '返回数据类型',
+    			'set-cookie': setCookieData // 在headers内返回set-cookie用于设置客户端cookie
+    	},
+    	body: '返回数据'
+    }
+  }
+};
+
 ```
 
-如果通过`https://xxx.com/todo/addTodo?title=todo-title&content=todo-content`调用云对象，todo方法内的console.log会输出以下内容`{title: 'todo-title', content: 'todo-content'}`
 
-需要注意的是自url内解析出的参数均为字符串类型。
 
-**注意**
+## 注意事项@tips
 
-- url化方式调用云对象时，`_before`和`_after`均正常执行
-- 如果需要获取其他方式传入云对象的参数（如：post一个json内容到云对象），请使用[this.getHttpInfo](cloud-obj.md#get-http-info)获取
\ No newline at end of file
+- 阿里云目前请求与响应有如下限制
+  + 请求Body大小限制，不能超过1MB。
+  + 响应Body大小限制，不能超过1MB。
+- 腾讯云目前请求与响应有如下限制
+  + 请求Body大小限制，文本不能超过100KB，二进制不能超过20MB。
+  + 响应Body大小限制，不能超过6MB。
+- url化场景下，path（云函数event.path、云对象httpInfo.path）表示以配置的url化路径为根路径的访问路径。以配置`/test`为云函数url化路径，访问`/test/a/b/c`时path为`/a/b/c`
+- 在URL化的场景无法获取客户端平台等信息，但是可以获取客户端IP、客户端userAgent
+- 接收到的post请求的请求体可能是被转成base64的，如果是这样需要进行一次转化。
+    以接收text/xml格式的post请求为例
+    ```js
+    // 云函数
+    exports.main = function(event) {
+        let body = event.body
+        if(event.isBase64Encoded){
+            body = Buffer.from(body, 'base64').toString('utf8') // 将base64格式的xml内容转为xml字符串
+        }
+    }
+
+    // 云对象
+    module.exports = {
+        addTodo: function() {
+            let httpInfo = this.getHttpInfo()
+            let body = httpInfo.body
+            if(httpInfo.isBase64Encoded){
+                body = Buffer.from(body, 'base64').toString('utf8') // 将base64格式的xml内容转为xml字符串
+            }
+        }
+    }
+    ```
\ No newline at end of file
-- 
GitLab