新增 API 网关使用指南 (#233)

Co-authored-by: chenhuanlin <[email protected]>

README.md

@@ -313,6 +313,11 @@
           <li><a href="/support/practice/cloud-function.md">云函数实战教程</a></li>
           <li><a href="/support/practice/trigger.md">触发器实战教程</a></li>
         </ul>
+        <em class="directory-item-section-title">使用指南</em>
+        <ul class="directory-item-section-list">
+          <li><a href="/support/practice/trigger-v2-guideline.md">触发器 V2 使用指南</a></li>
+          <li><a href="/support/practice/api-gateway.md">API 网关使用指南</a></li>
+        </ul>
       </div>
       <div class="directory-item-section">
         <em class="directory-item-section-title">其他</em>

SUMMARY.md

@@ -363,6 +363,7 @@
     * [订阅消息实战教程](support/practice/subscribe-message-course.md)
 * [使用指南](support/practice/README.md)
     * [触发器 V2 使用指南](support/practice/trigger-v2-guideline.md)
+    * [API 网关使用指南](support/practice/api-gateway.md)
 * [管理与支持](support/README.md)
     * [插件](support/plugin.md)
     * [常见问题](support/qA.md)

cloud-function/node-sdk/start/code-format.md

@@ -25,7 +25,7 @@ exports.main = function helloWorld(event, callback) {
 | 包含字段         | 类型            | 说明 |
 | :-------------- | :------------- | :-- |
 | data            | 任何 js 合法类型 | 在用户调用云函数时传入的参数 |
-| eventType       | String         | 提供给用户的触发来源的信息，包括 sdk/open_api/user_dash/cloud_function 等 |
+| eventType       | String         | 提供给用户的触发来源的信息，包括 sdk/open_api/user_dash/cloud_function/[api_gateway](/support/practice/api-gateway.md) 等 |
 | jobId           | Number         | 当前函数执行的 id |
 | memoryLimitInMB | Number         | 当前函数的内存资源限制 |
 | miniappId       | Number         | 云函数所属小程序 id |
@@ -34,13 +34,13 @@ exports.main = function helloWorld(event, callback) {
 
 request 结构说明
 
-| 参数             | 类型   | 描述 |
-| :-------------- | :----- | :--- |
-| meta.ip_address | Object | 发起云函数请求的 IP   |
-| meta.user_agent | String | 发起云函数请求设备的 userAgent |
-| user.avatar_url | String | 发起云函数请求的用户头像  |
-| user.nickname   | Object | 发起云函数请求的用户昵称 |
-| user.id         | Object | 发起云函数请求的用户 ID |
+| 参数             | 类型    | 描述 |
+| :-------------- | :------ | :--- |
+| meta.ip_address | String  | 发起云函数请求的 IP   |
+| meta.user_agent | String  | 发起云函数请求设备的 userAgent |
+| user.avatar_url | String  | 发起云函数请求的用户头像  |
+| user.nickname   | String  | 发起云函数请求的用户昵称 |
+| user.id         | Integer | 发起云函数请求的用户 ID |
 
 request 示例如下
 

cloud-function/node-sdk/user.md

@@ -16,7 +16,7 @@
 
 7. `language`
 
-8. `avata`
+8. `avatar`
 {% endmacro %}
 
 # 获取用户信息

dashboard/basic-services/README.md

@@ -9,3 +9,4 @@
 * [云函数](/dashboard/basic-services/cloud-function.md)
 * [设置](/dashboard/basic-services/set-up.md)
 * [ACL 简介](/dashboard/basic-services/acl.md)
+* [API 网关](/dashboard/basic-services/api-gateway.md)

dashboard/basic-services/api-gateway.md

@@ -0,0 +1,48 @@
+# API 网关
+
+知晓云 API 网关（API Gateway），是 API 发布、管理、运维的全生命周期管理工具。让开发者通过可视化界面配置并生成 API 提供给全平台使用，省掉了繁琐的服务开发及部署环节，五分钟即可完成 API 定制开发。
+
+使用 API 网关，还可以让运行在知晓云上的应用数据得以更加灵活地提供给外部系统集成，无需再通过知晓云的 OpenAPI 进行数据转接，使得业务推进速度跃升一个等级。
+
+> 知晓云控制台进入「引擎」即可开启使用。
+
+## 创建 API 网关
+
+选择「API 网关」tab，即可进入管理面板。
+
+![创建 API 网关](/images/dashboard/api-gateway-creation.png)
+
+## 增加路由，绑定云函数
+
+完成 API 网关创建后，在「API 管理」添加 API。
+
+![创建 API](/images/dashboard/api-gateway-add-route.png)
+
+
+API 可以根据需求进行认证服务，请求参数等的前端配置，按需选择。
+
+![API 前端配置](/images/dashboard/api-gateway-route-config.png)
+
+完成前端配置后，再进行后端云函数的配置，给正式/测试环境配置相对应的云函数，点击「新增云函数」会在新开的标签页中实现云函数的创建，完成后，点击刷新按钮即可选择。
+
+![API 后端配置](/images/dashboard/api-gateway-route-associate-cloud-function.png)
+
+## 编写云函数
+
+云函数中可使用的参数及返回数据都与普通云函数不一样，编写前先阅读[文档](/support/practice/api-gateway.md)，确保编写出正确可用的云函数。
+
+![云函数编写](/images/dashboard/api-gateway-create-cloud-function.png)
+
+编写成后，回到原有标签，进行关联操作。
+
+![API 绑定云函数](/images/dashboard/api-gateway-choose-cloud-function.png)
+
+## 发布 API 网关
+
+![API 发布](/images/dashboard/api-gateway-publish.png)
+
+## 验证 API 网关
+
+![API 验证](/images/dashboard/api-gateway-verify.png)
+
+

js-sdk/wechat/censor.md

@@ -102,8 +102,8 @@ HError 对象结构请参考[错误码和 HError 对象](./error-code.md)
 | 参数名   | 类型   | 说明     |
 |----------|--------|----------|
 | id            | String | 检测记录 id  |
-| error_code    | String | 错误码，=0 时不返回此字段  |
-| error_message | String | 错误信息，error_code=0 时不返回此字段  |
+| error_code    | Integer | 错误码 |
+| error_message | String | 错误信息  |
 | status_code   | Number | 默认为：0，4294966288(-1008)为链接无法下载  |
 | risky         | Boolean | 是否为违规内容，true 为风险，false 为未检测到风险，null 为微信尚未推送检查结果  |
 {% endmacro %}

support/practice/api-gateway-request-path.md

@@ -0,0 +1,157 @@
+# API 网关定义 API 路径指南
+
+API 路径是 URL 的组成一部分（path），具体含义可以参考：[什么是 URL](https://developer.mozilla.org/zh-CN/docs/Learn/Common_questions/What_is_a_URL)
+
+在 API 网关中 API 路径的定义有几个要求：
+
+1. 必须以 「/」
+2. 仅限小写英文字母，不支持中文
+3. 路径 + query string 的字符串长度不能超过 16k
+
+为了更好地丰富 API 路径的匹配模式，API 网关支持使用**正则表达式**来编写 API 路径。
+
+
+## API 路径中的正则表达式语法
+
+API 路径中使用正则表达式是为了实现从用户请求路径中获取符合某个条件的字符串（参数），所以使用的正则表达式会由匹配及重复字符组成。
+
+格式：
+
+    (<匹配字符><重复字符>)
+
+> 重复字符是用于描述匹配字符出现的重复次数才符合整个正则表达式。
+
+> `()` 表示正则表达式的开始与结束
+
+### 匹配字符
+
+`[]`
+
+它用于指定匹配字符，可以单独列出字符，也可以通过给出两个字符并用 '-' 标记将它们分开来表示一系列字符。
+
+例如，`[abc]` 将匹配任何字符 a、b 或 c，也可以写作 `[a-c]`，它使用一个范围来表示同一组字符。
+
+`\d`
+
+匹配任何十进制数字。
+
+`\D`
+
+匹配任何非数字字符。
+
+`\w`
+
+匹配任何字母与数字字符
+
+`\W`
+
+匹配任何非字母与数字字符
+
+`.`
+
+匹配任何字符
+
+
+### 重复字符
+
+`*`
+
+匹配零或多次
+
+`+`
+
+匹配一或多次
+
+`{n}`
+
+n 是一个非负整数。匹配确定的 n 次
+
+`{n,}`
+
+n 是一个非负整数。至少匹配 n 次
+
+`{n,m}`
+
+m 和 n 均为非负整数，其中 n <= m，最少匹配 n 次且最多匹配 m 次
+
+### 组合示例
+
+`[abc]+`
+
+字符串中只能包含 `a`，`b`，`c` 三个字符串，匹配一或多次。
+如 `a`，`aa`，`aaa`，`ab`，`bc`，`abbbbbc`匹配成功，`abd` 匹配失败。
+
+`\d{1}`
+
+任何十进制数字匹配一次。
+如 `1`，`2`... `9` 均能匹配成功，`10` 开始匹配失败。
+
+
+## API 路径中的正则表达式使用
+
+在 API 路径中写入正则表达式，API 网关捕获并将匹配到的字符串传入云函数中。
+
+API 网关支持两种正则表达式的写法：
+
+1. 位置表达式
+2. 命名表达式
+
+> 需注意，不支持同时使用两种写法，如同时使用，则只会将匹配命名表达式的参数传入云函数
+
+### 位置表达式
+
+在 API 路径的任意位置中写入 `(pattern)` 即可完成。
+
+下面是一个实际例子：
+
+    /article/(\d+)/
+
+当用户请求 `/article/1/` 在API 网关完成匹配后，云函数可通过 `event.request.meta.nested_arguments` 获取参数，event.request.meta 其数据结构为:
+
+    {
+        "request_method": "GET",
+        "nested_arguments": ["1"],
+        "named_arguments": {},
+        "request_path": "/article/1/",
+        "query_string": {},
+        "headers": {},
+        "ip_address": "127.0.0.1",
+        "user_agent": "user-agent",
+    }
+
+位置表达式可以写入多个
+
+    /article/(\d+)/(\w+)/
+
+当用户请求 `/article/1/comment/` 在API 网关完成匹配后，云函数可通过 `event.request.meta.nested_arguments` 获取参数，event.request.meta 其数据结构为:
+
+    {
+        "request_method": "GET",
+        "nested_arguments": ["1", "comment"],
+        "named_arguments": {},
+        "request_path": "/article/1/",
+        "query_string": {},
+        "headers": {},
+        "ip_address": "127.0.0.1",
+        "user_agent": "user-agent",
+    }
+
+`event.request.meta.nested_arguments` 数组的中的顺序取决于每个位置表达式在 API 路径中的顺序。
+
+### 命名表达式
+
+命名表达式的语法与位置表达式不同，增加了参数命名：
+
+    (?P<name>pattern)
+
+name 为对参数的命名，pattern 为正则表达式。下面是一个实际例子：
+
+    /hello/(?P<id>\d+)/
+
+当用户请求 `/hello/1` 在API 网关完成匹配后，云函数可通过 `event.request.meta.named_arguments` 获取参数，其数据结构为:
+
+    {
+        "event.request.meta.named_arguments": {
+            "id": "1"
+        }
+    }