This is an automated email from the ASF dual-hosted git repository.
sylviasu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 97272dcba docs: refactor serverless plugins (#7829)
97272dcba is described below
commit 97272dcba0612946c88941a6d45ea5f26aa9b821
Author: Fei Han <[email protected]>
AuthorDate: Thu Sep 15 10:05:59 2022 +0800
docs: refactor serverless plugins (#7829)
* docs: refactor serverless plugins
* Update docs/zh/latest/plugins/serverless.md
Co-authored-by: Sylvia <[email protected]>
Co-authored-by: hf400159 <[email protected]>
Co-authored-by: Sylvia <[email protected]>
---
docs/zh/latest/plugins/aws-lambda.md | 28 ++++++++-------
docs/zh/latest/plugins/azure-functions.md | 22 +++++++-----
docs/zh/latest/plugins/openwhisk.md | 12 ++++---
docs/zh/latest/plugins/serverless.md | 58 +++++++++++++++++++------------
4 files changed, 71 insertions(+), 49 deletions(-)
diff --git a/docs/zh/latest/plugins/aws-lambda.md
b/docs/zh/latest/plugins/aws-lambda.md
index 7398016e4..52190cafb 100644
--- a/docs/zh/latest/plugins/aws-lambda.md
+++ b/docs/zh/latest/plugins/aws-lambda.md
@@ -37,17 +37,17 @@ description: 本文介绍了关于 Apache APISIX aws-lambda 插件的基本信
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述
|
-| ------------------- | ------- | ------ | ------- | ------------ |
------------------------------------------------------------ |
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述
|
+| ------------------ - | ------- | -------- | ------- | ------------ |
------------------------------------------------------------ |
| function_uri | string | 是 | | | 触发
lambda serverless 函数的 AWS API Gateway 端点。 |
| authorization | object | 否 | | |
访问云函数的授权凭证。 |
| authorization.apikey | string | 否 | | | 生成的 API
密钥，用于授权对 AWS Gateway 端点的请求。 |
-| authorization.iam | object | 否 | | | 用于通过 AWS
v4 请求签名执行的基于 AWS IAM 角色的授权。 请参考 [IAM 授权方案](#IAM-授权方案)。 |
+| authorization.iam | object | 否 | | | 用于通过 AWS
v4 请求签名执行的基于 AWS IAM 角色的授权。 请参考 [IAM 授权方案](#iam-授权方案)。 |
| timeout | integer | 否 | 3000 | [100,...] |
代理请求超时（以毫秒为单位）。 |
| ssl_verify | boolean | 否 | true | true/false | 当设置为
`true` 时执行 SSL 验证。 |
| keepalive | boolean | 否 | true | true/false | 当设置为
`true` 时，保持连接的活动状态以便重复使用。 |
| keepalive_pool | integer | 否 | 5 | [1,...] |
在关闭该连接之前，可以在该连接上发送的最大请求数。 |
-| keepalive_timeout | integer | 否 | 60000 | [1000,...] |
当连接空闲时，保持该连接处于活动状态的时间（以毫秒为单位）。 |
+| keepalive_timeout | integer | 否 | 60000 | [1000,...] |
当连接空闲时，保持该连接处于活动状态的时间，以毫秒为单位。 |
### IAM 授权方案
@@ -60,10 +60,11 @@ description: 本文介绍了关于 Apache APISIX aws-lambda 插件的基本信
## 启用插件
-以下示例展示了如何在指定路由上启用 `aws-lambda` 插件：
+你可以通过以下命令在指定路由中启用该插件：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"aws-lambda": {
@@ -127,7 +128,8 @@ content-type: application/json
以下示例展示了如何通过配置文件实现授权：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"aws-lambda": {
@@ -145,7 +147,7 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-:::note
+:::note 注意
使用该方法时已经假设你有一个启用了程序化访问的 IAM 用户，并具有访问端点的必要权限（AmazonAPIGatewayInvokeFullAccess）。
@@ -155,7 +157,7 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
`aws-lambda` 插件在代理请求到 AWS 上游时也支持 URL 路径转发。基本请求路径的扩展被附加到插件配置中指定的 `function_uri`
字段上。
-:::info IMPORTANT
+:::info 重要
因为 APISIX 路由是严格匹配的，所以为了使 `aws-lambda` 插件正常工作，在路由上配置的 `uri` 字段必须以 `*` 结尾，`*`
意味着这个 URI 的任何子路径都会被匹配到同一个路由。
@@ -164,7 +166,8 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
以下示例展示了如何通过配置文件实现路径转发：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"aws-lambda": {
@@ -198,10 +201,11 @@ Content-Type: application/json
## 禁用插件
-当你需要禁用 `aws-lambda` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
+当你需要禁用该插件时，可以通过如下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/aws",
"plugins": {},
diff --git a/docs/zh/latest/plugins/azure-functions.md
b/docs/zh/latest/plugins/azure-functions.md
index 8e1ae90d0..4e7eaba30 100644
--- a/docs/zh/latest/plugins/azure-functions.md
+++ b/docs/zh/latest/plugins/azure-functions.md
@@ -5,7 +5,7 @@ keywords:
- Plugin
- Azure Functions
- azure-functions
-description: 本文介绍了关于 Apache APISIX azure-functions 插件的基本信息及使用方法。
+description: 本文介绍了关于 API 网关 Apache APISIX azure-functions 插件的基本信息及使用方法。
---
<!--
#
@@ -55,7 +55,7 @@ description: 本文介绍了关于 Apache APISIX azure-functions 插件的基本
`azure-functions` 插件的元数据提供了授权回退的功能。它定义了 `master_apikey` 和 `master_clientid`
字段，用户可以为关键任务的应用部署声明 API 密钥或客户端 ID。因此，如果在 `azure-functions`
插件属性中没有找到相关授权凭证，此时元数据中的授权凭证就会发挥作用。
-:::note
+:::note 注意
授权方式优先级排序如下：
@@ -68,7 +68,8 @@ description: 本文介绍了关于 Apache APISIX azure-functions 插件的基本
如果你想添加一个新的 API 密钥，请向 `/apisix/admin/plugin_metadata` 端点发出请求，并附上所需的元数据。示例如下：
```shell
-curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/azure-functions -H
'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/azure-functions \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"master_apikey" : "<Your Azure master access key>"
}'
@@ -76,10 +77,11 @@ curl
http://127.0.0.1:9180/apisix/admin/plugin_metadata/azure-functions -H 'X-AP
## 启用插件
-以下示例展示了如何在指定路由上启用 `azure-functions` 插件。请确保你的 Azure Functions 已提前部署好，并正常提供服务。
+你可以通过以下命令在指定路由中启用该插件，请确保你的 Azure Functions 已提前部署好，并正常提供服务。
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"azure-functions": {
@@ -141,7 +143,7 @@ Hello, APISIX
`azure-functions` 插件在代理请求到 Azure Functions 上游时也支持 URL
路径转发。基本请求路径的扩展被附加到插件配置中指定的 `function_uri` 字段上。
-:::info 注意
+:::info 重要
因为 APISIX 路由是严格匹配的，所以为了使 `azure-functions` 插件正常工作，在路由上配置的 `uri` 字段必须以 `*`
结尾，`*` 意味着这个 URI 的任何子路径都会被匹配到同一个路由。
@@ -150,7 +152,8 @@ Hello, APISIX
以下示例展示了如何通过配置文件实现路径转发：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"azure-functions": {
@@ -183,10 +186,11 @@ Hello, APISIX
## 禁用插件
-当你需要禁用 `azure-functions` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
+当你需要禁用该插件时，可以通过如下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/azure",
"plugins": {},
diff --git a/docs/zh/latest/plugins/openwhisk.md
b/docs/zh/latest/plugins/openwhisk.md
index aecdf3122..3d69aff22 100644
--- a/docs/zh/latest/plugins/openwhisk.md
+++ b/docs/zh/latest/plugins/openwhisk.md
@@ -48,7 +48,7 @@ description: 本文介绍了关于 Apache APISIX openwhisk 插件的基本信息
| keepalive_timeout | integer | 否 | 60000ms | [1000,...]ms |
当连接空闲时，保持该连接处于活动状态的时间（以毫秒为单位）。 |
| keepalive_pool | integer | 否 | 5 | [1,...] |
连接断开之前，可接收的最大请求数。 |
-:::note
+:::note 注意
`timeout` 字段规定了 OpenWhisk action 的最大执行时间，以及 APISIX 中 HTTP 客户端的请求超时时间。
@@ -86,10 +86,11 @@ wsk action update test <(echo 'function main(){return
{"ready":true}}') --kind n
### 创建路由
-通过以下命令创建一个路由，并在配置文件中添加 `openwhisk` 插件：
+你可以通过以下命令在指定路由中启用该插件：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/hello",
"plugins": {
@@ -119,10 +120,11 @@ curl -i http://127.0.0.1:9080/hello
## 禁用插件
-当你需要禁用 `openwhisk` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
+当你需要禁用该插件时，可以通过如下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/hello",
diff --git a/docs/zh/latest/plugins/serverless.md
b/docs/zh/latest/plugins/serverless.md
index 286e5ad54..8761bc56f 100644
--- a/docs/zh/latest/plugins/serverless.md
+++ b/docs/zh/latest/plugins/serverless.md
@@ -1,5 +1,11 @@
---
title: serverless
+keywords:
+ - APISIX
+ - Plugin
+ - Serverless
+ - serverless
+description: 本文介绍了关于 API 网关 Apache APISIX serverless-pre-function 和
serverless-post-function 插件的基本信息及使用方法。
---
<!--
@@ -23,19 +29,22 @@ title: serverless
## 描述
-serverless 的插件有两个，分别是 `serverless-pre-function` 和 `serverless-post-function`，
-前者会在指定阶段的最开始运行，后者是在指定阶段的最后运行。
+APISIX 有两个 `serverless` 插件：`serverless-pre-function` 和
`serverless-post-function`。
-这两个插件接收的参数都是一样的。
+`serverless-pre-function` 插件会在指定阶段开始时运行，`serverless-post-function`
插件会在指定阶段结束时运行。这两个插件使用相同的属性。
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 有效值
| 描述
|
-| --------- | ------------- | -------- | ---------- |
------------------------------------------------------------------------ |
------------------------------------------------------------------------------------------
|
-| phase | string | 可选 | ["access"] | ["rewrite", "access",
"header_filter", "body_filter", "log", "before_proxy"] |
|
-| functions | array[string] | 必须 | |
|
指定运行的函数列表，是数组类型，里面可以包含一个函数，也可以是多个函数，按照先后顺序执行。 |
+| 名称 | 类型 | 必选项 | 默认值 | 有效值
| 描述
|
+| --------- | ------------- | ------- | ---------- |
---------------------------------------------------------------------------- |
------------------------------------------------------------------------------ |
+| phase | string | 否 | ["access"] | ["rewrite", "access",
"header_filter", "body_filter", "log", "before_proxy"] | 执行 severless 函数的阶段。
|
+| functions | array[string] | 是 | |
|
指定运行的函数列表。该属性可以包含一个函数，也可以是多个函数，按照先后顺序执行。 |
-需要注意的是，这里只接受函数，而不接受其他类型的 Lua 代码。比如匿名函数是合法的：
+:::info 重要
+
+此处仅接受函数，不接受其他类型的 Lua 代码。
+
+比如匿名函数是合法的：
```lua
return function()
@@ -60,18 +69,23 @@ local count = 1
ngx.say(count)
```
-从 `v2.6` 版本开始，我们会把 `conf` 和 `ctx` 作为头两个参数传递给 serverless 函数，就跟一般的插件一样。
+:::
+
+:::note 注意
-`v2.12.0` 版本之前，`before_proxy` 这个 phase 曾被称作 `balancer`。考虑到这一方法事实上运行在 `access`
之后，代理到上游之前，跟 `balancer` 没有关系，新的命名会更加贴切。
+从 `v2.6` 版本开始，`conf` 和 `ctx` 作为前两个参数传递给 `serverless` 函数。
-## 示例
+在 `v2.12.0` 版本之前，`before_proxy` 阶段曾被称作 `balancer`。考虑到这一方法是在 `access`
阶段之后、请求到上游之前运行，并且与 `balancer` 没有关联，因此已经更新为 `before_proxy`。
-### 启动插件
+:::
-下面是一个示例，在指定的 route 上开启了 serverless 插件：
+## 启用插件
+
+你可以通过以下命令在指定路由中启用该插件：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
"plugins": {
@@ -93,23 +107,23 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f1
}'
```
-### 测试插件
+## 测试插件
-使用 curl 访问：
+你可以通过以下命令向 APISIX 发出请求：
```shell
curl -i http://127.0.0.1:9080/index.html
```
-然后你在 error.log 日志中就会发现 `serverless pre function` 和 `match uri /index.html` 两个
error 级别的日志，
-表示指定的函数已经生效。
+如果你在 `./logs/error.log` 中发现 `serverless pre function` 和 `match uri
/index.html` 两个 error 级别的日志，表示指定的函数已经生效。
-### 移除插件
+## 禁用插件
-当你想去掉插件的时候，很简单，在插件的配置中把对应的 json 配置删除即可，无须重启服务，即刻生效：
+当你需要禁用该插件时，可以通过如下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/index.html",
@@ -121,5 +135,3 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f1
}
}'
```
-
-现在就已经移除了 serverless 插件了。其他插件的开启和移除也是同样的方法。
