This is an automated email from the ASF dual-hosted git repository.
spacewander 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 c6fed6da0 docs: add azure-functions CN document (#7120)
c6fed6da0 is described below
commit c6fed6da02317bb3487954a7e1a041310d1eb300
Author: penghuima <[email protected]>
AuthorDate: Wed Jun 1 09:28:00 2022 +0800
docs: add azure-functions CN document (#7120)
---
docs/zh/latest/config.json | 1 +
docs/zh/latest/plugins/azure-functions.md | 202 ++++++++++++++++++++++++++++++
2 files changed, 203 insertions(+)
diff --git a/docs/zh/latest/config.json b/docs/zh/latest/config.json
index f2042cf06..79c038e66 100644
--- a/docs/zh/latest/config.json
+++ b/docs/zh/latest/config.json
@@ -160,6 +160,7 @@
"label": "Serverless",
"items": [
"plugins/serverless",
+ "plugins/azure-functions",
"plugins/openwhisk"
]
},
diff --git a/docs/zh/latest/plugins/azure-functions.md
b/docs/zh/latest/plugins/azure-functions.md
new file mode 100644
index 000000000..dac483406
--- /dev/null
+++ b/docs/zh/latest/plugins/azure-functions.md
@@ -0,0 +1,202 @@
+---
+title: azure-functions
+keywords:
+ - APISIX
+ - Plugin
+ - Azure Functions
+ - azure-functions
+description: 本文介绍了关于 Apache APISIX azure-functions 插件的基本信息及使用方法。
+---
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## 描述
+
+`azure-functions` 插件用于将 [Azure Serverless
Function](https://azure.microsoft.com/en-in/services/functions/) 作为动态上游集成至
APISIX，从而实现将访问指定 URI 的请求代理到 Microsoft Azure 云服务。
+
+启用 `azure-functions` 插件后，该插件会终止对已配置 URI 的请求，并代表客户端向 Azure Functions
发起一个新的请求。该新请求中携带了之前配置的授权详细信息，包括请求头、请求体和参数（以上参数都是从原始请求中传递的）。之后便会通过
`azure-functions` 插件，将带有响应头、状态码和响应体的信息返回给使用 APISIX 发起请求的客户端。
+
+## 属性
+
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述
|
+| ---------------------- | ------- | ------ | ------ | ---------- |
------------------------------------------------------------ |
+| function_uri | string | 是 | | | 触发
Serverless Functions 的 Azure Functions 端点。例如
`http://test-apisix.azurewebsites.net/api/HttpTrigger`。 |
+| authorization | object | 否 | | | 访问 Azure
Functions 的授权凭证。 |
+| authorization.apikey | string | 否 | | | 授权凭证内的字段。生成
API 密钥来授权对端点的请求。 |
+| authorization.clientid | string | 否 | | |
授权凭证内的字段。生成客户端 ID（Azure Active Directory）来授权对端点的请求。 |
+| 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,...] |
当连接空闲时，保持该连接处于活动状态的时间（以毫秒为单位）。 |
+
+## 元数据
+
+| 名称 | 类型 | 必选项 | 默认值 | 描述
|
+| --------------- | ------ | ------ | ------ |
------------------------------------------------------------ |
+| master_apikey | string | 否 | "" | 可用于访问 Azure Functions URI 的 API
密钥。 |
+| master_clientid | string | 否 | "" | 可用于授权 Azure Functions URI 的客户端
ID（Active Directory）。 |
+
+`azure-functions` 插件的元数据提供了授权回退的功能。它定义了 `master_apikey` 和 `master_clientid`
字段，用户可以为关键任务的应用部署声明 API 密钥或客户端 ID。因此，如果在 `azure-functions`
插件属性中没有找到相关授权凭证，此时元数据中的授权凭证就会发挥作用。
+
+:::note
+
+授权方式优先级排序如下：
+
+1. 首先，`azure-functions` 插件在 APISIX 代理的请求头中寻找 `x-functions-key` 或
`x-functions-clientid` 键。
+2. 如果没有找到，`azure-functions` 插件会检查插件属性中的授权凭证。如果授权凭证存在，`azure-functions`
插件会将相应的授权标头添加到发送到 Azure Functions 的请求中。
+3. 如果未配置 `azure-functions` 插件的授权凭证属性，APISIX 将获取插件元数据配置并使用 API 密钥。
+
+:::
+
+如果你想添加一个新的 API 密钥，请向 `/apisix/admin/plugin_metadata` 端点发出请求，并附上所需的元数据。示例如下：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/azure-functions -H
'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "master_apikey" : "<Your Azure master access key>"
+}'
+```
+
+## 启用插件
+
+以下示例展示了如何在指定路由上启用 `azure-functions` 插件。请确保你的 Azure Functions 已提前部署好，并正常提供服务。
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "plugins": {
+ "azure-functions": {
+ "function_uri":
"http://test-apisix.azurewebsites.net/api/HttpTrigger";,
+ "authorization": {
+ "apikey": "${Generated API key to access the Azure-Function}"
+ }
+ }
+ },
+ "uri": "/azure"
+}'
+```
+
+通过上述示例配置插件后，任何对 `/azure` URI 的请求（`HTTP/1.1`、`HTTPS`、`HTTP2`）都将调用已配置的 Azure
Functions 的 URI，并且会将响应信息返回给客户端。
+
+下述命令的含义是：Azure Functions 从请求中获取 `name` 参数，并返回一条 `"Hello $name"` 消息：
+
+```shell
+curl -i -XGET http://localhost:9080/azure\?name=APISIX
+```
+
+正常返回结果：
+
+```shell
+HTTP/1.1 200 OK
+Content-Type: text/plain; charset=utf-8
+...
+Hello, APISIX
+```
+
+以下示例是客户端通过 HTTP/2 协议与 APISIX 进行通信。
+
+在进行测试之前，由于该 `enable_http2: true` 默认是禁用状态，你可以通过在 `./conf/config.yaml` 中添加
`apisix.node_listen` 下的 `- port: 9081` 和 `enable_http2: true` 字段启用。示例如下：
+
+```yaml
+apisix:
+ admin_key:
+...
+ node_listen: # 支持监听多个端口
+ - 9080
+ - port: 9081
+ enable_http2: true # 该字段如果不设置，默认值为 `false`
+```
+
+使用 `curl` 命令测试：
+
+```shell
+curl -i -XGET --http2 --http2-prior-knowledge
http://localhost:9081/azure\?name=APISIX
+```
+
+正常返回结果：
+
+```shell
+HTTP/2 200
+content-type: text/plain; charset=utf-8
+...
+Hello, APISIX
+```
+
+### 配置路径转发
+
+`azure-functions` 插件在代理请求到 Azure Functions 上游时也支持 URL
路径转发。基本请求路径的扩展被附加到插件配置中指定的 `function_uri` 字段上。
+
+:::info 注意
+
+因为 APISIX 路由是严格匹配的，所以为了使 `azure-functions` 插件正常工作，在路由上配置的 `uri` 字段必须以 `*`
结尾，`*` 意味着这个 URI 的任何子路径都会被匹配到同一个路由。
+
+:::
+
+以下示例展示了如何通过配置文件实现路径转发：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "plugins": {
+ "azure-functions": {
+ "function_uri": "http://app-bisakh.azurewebsites.net/api";,
+ "authorization": {
+ "apikey": "${Generated API key to access the Azure-Function}"
+ }
+ }
+ },
+ "uri": "/azure/*"
+}'
+```
+
+通过上述示例配置插件后，任何访问 `azure/HttpTrigger1` 的请求都会调用 Azure Functions 并转发附加的参数。
+
+使用 `curl` 命令测试：
+
+```shell
+curl -i -XGET http://127.0.0.1:9080/azure/HttpTrigger1\?name\=APISIX\
+```
+
+正常返回结果：
+
+```shell
+HTTP/1.1 200 OK
+Content-Type: text/plain; charset=utf-8
+...
+Hello, APISIX
+```
+
+## 禁用插件
+
+当你需要禁用 `azure-functions` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/azure",
+ "plugins": {},
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ }
+}'
+```
