This is an automated email from the ASF dual-hosted git repository.
bzp2010 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 4c7918fe6 docs: improve public-api plugin docs (#11951)
4c7918fe6 is described below
commit 4c7918fe6fe469c8e3b749cb520936fc1b5bc4ba
Author: Yilia Lin <[email protected]>
AuthorDate: Thu Feb 27 11:58:41 2025 +0800
docs: improve public-api plugin docs (#11951)
---
docs/en/latest/plugins/public-api.md | 299 +++++++++++++++++++----------------
docs/zh/latest/plugins/public-api.md | 299 ++++++++++++++++++-----------------
2 files changed, 322 insertions(+), 276 deletions(-)
diff --git a/docs/en/latest/plugins/public-api.md
b/docs/en/latest/plugins/public-api.md
index 6d1034119..c9c62c5e5 100644
--- a/docs/en/latest/plugins/public-api.md
+++ b/docs/en/latest/plugins/public-api.md
@@ -4,7 +4,7 @@ keywords:
- Apache APISIX
- API Gateway
- Public API
-description: The public-api is used for exposing an API endpoint through a
general HTTP API router.
+description: The public-api plugin exposes an internal API endpoint, making it
publicly accessible. One of the primary use cases of this plugin is to expose
internal endpoints created by other plugins.
---
<!--
@@ -26,189 +26,220 @@ description: The public-api is used for exposing an API
endpoint through a gener
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/public-api"; />
+</head>
+
## Description
-The `public-api` is used for exposing an API endpoint through a general HTTP
API router.
+The `public-api` Plugin exposes an internal API endpoint, making it publicly
accessible. One of the primary use cases of this Plugin is to expose internal
endpoints created by other Plugins.
-When you are using custom Plugins, you can use the `public-api` Plugin to
define a fixed, public API for a particular functionality. For example, you can
create a public API endpoint `/apisix/batch-requests` for grouping multiple API
requests in one request using the [batch-requests](./batch-requests.md) Plugin.
+## Attributes
-:::note
+| Name | Type | Required | Default | Valid Values | Description |
+|---------|-----------|----------|---------|--------------|-------------|
+| uri | string | False | | | Internal endpoint
to expose. If not configured, expose the Route URI. |
-The public API added in a custom Plugin is not exposed by default and the user
should manually configure a Route and enable the `public-api` Plugin on it.
+## Examples
-:::
+The examples below demonstrate how you can configure `public-api` in different
scenarios.
-## Attributes
+### Expose Prometheus Metrics at Custom Endpoint
-| Name | Type | Required | Default | Description
|
-|------|--------|----------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| uri | string | False | "" | URI of the public API. When setting up
a Route, use this attribute to configure the original public API URI. |
+The following example demonstrates how you can disable the Prometheus export
server that, by default, exposes an endpoint on port `9091`, and expose APISIX
Prometheus metrics on a new public API endpoint on port `9080`, which APISIX
uses to listen to other client requests.
-## Example usage
+You will also configure the Route such that the internal endpoint
`/apisix/prometheus/metrics` is exposed at a custom endpoint.
-The example below uses the [batch-requests](./batch-requests.md) Plugin and
the [key-auth](./key-auth.md) Plugin along with the `public-api` Plugin. Refer
to their documentation for its configuration. This step is omitted below and
only explains the configuration of the `public-api` Plugin.
+:::caution
-### Basic usage
+If a large quantity of metrics is being collected, the Plugin could take up a
significant amount of CPU resources for metric computations and negatively
impact the processing of regular requests.
-You can enable the Plugin on a specific Route as shown below:
+To address this issue, APISIX uses [privileged
agent](https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/process.md#enable_privileged_agent)
and offloads the metric computations to a separate process. This optimization
applies automatically if you use the metric endpoint configured under
`plugin_attr.prometheus.export_addr` in the configuration file. If you expose
the metric endpoint with the `public-api` Plugin, you will not benefit from
this optimization.
-```shell
-curl -X PUT 'http://127.0.0.1:9180/apisix/admin/routes/r1' \
- -H 'X-API-KEY: <api-key>' \
- -H 'Content-Type: application/json' \
- -d '{
- "uri": "/apisix/batch-requests",
- "plugins": {
- "public-api": {}
- }
-}'
-```
+:::
-Now, if you make a request to the configured URI, you will receive a
batch-requests response:
+Disable the Prometheus export server in the configuration file and reload
APISIX for changes to take effect:
-```shell
-curl --location --request POST 'http://127.0.0.1:9080/apisix/batch-requests' \
---header 'Content-Type: application/json' \
---data '{
- "headers": {
- "Content-Type": "application/json",
- "admin-jwt":"xxxx"
- },
- "timeout": 500,
- "pipeline": [
- {
- "method": "POST",
- "path": "/community.GiftSrv/GetGifts",
- "body": "test"
- },
- {
- "method": "POST",
- "path": "/community.GiftSrv/GetGifts",
- "body": "test2"
- }
- ]
-}'
+```yaml title="conf/config.yaml"
+plugin_attr:
+ prometheus:
+ enable_export_server: false
```
+Next, create a Route with the `public-api` Plugin and expose a public API
endpoint for APISIX metrics. You should set the Route `uri` to the custom
endpoint path and set the Plugin `uri` to the internal endpoint to be exposed.
+
```shell
-[
- {
- "status": 200,
- "reason": "OK",
- "body":
"{\"ret\":500,\"msg\":\"error\",\"game_info\":null,\"gift\":[],\"to_gets\":0,\"get_all_msg\":\"\"}",
- "headers": {
- "Connection": "keep-alive",
- "Date": "Sat, 11 Apr 2020 17:53:20 GMT",
- "Content-Type": "application/json",
- "Content-Length": "81",
- "Server": "APISIX web server"
- }
- },
- {
- "status": 200,
- "reason": "OK",
- "body":
"{\"ret\":500,\"msg\":\"error\",\"game_info\":null,\"gift\":[],\"to_gets\":0,\"get_all_msg\":\"\"}",
- "headers": {
- "Connection": "keep-alive",
- "Date": "Sat, 11 Apr 2020 17:53:20 GMT",
- "Content-Type": "application/json",
- "Content-Length": "81",
- "Server": "APISIX web server"
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "prometheus-metrics",
+ "uri": "/prometheus_metrics",
+ "plugins": {
+ "public-api": {
+ "uri": "/apisix/prometheus/metrics"
+ }
}
- }
-]
+ }'
```
-### Using custom URI
-
-You can also use a custom URI for exposing the API as shown below:
+Send a request to the custom metrics endpoint:
```shell
-curl -X PUT 'http://127.0.0.1:9180/apisix/admin/routes/r2' \
- -H 'X-API-KEY: <api-key>' \
- -H 'Content-Type: application/json' \
- -d '{
- "uri": "/batch-requests-gifs",
- "plugins": {
- "public-api": {
- "uri": "/apisix/batch-requests"
- }
- }
-}'
+curl "http://127.0.0.1:9080/prometheus_metrics";
```
-Now you can make requests to this new endpoint:
-
-```shell
-curl --location --request POST 'http://127.0.0.1:9080/batch-requests-gifs' \
---header 'Content-Type: application/json' \
---data '{...}'
+You should see an output similar to the following:
+
+```text
+# HELP apisix_http_requests_total The total number of client requests since
APISIX started
+# TYPE apisix_http_requests_total gauge
+apisix_http_requests_total 1
+# HELP apisix_nginx_http_current_connections Number of HTTP connections
+# TYPE apisix_nginx_http_current_connections gauge
+apisix_nginx_http_current_connections{state="accepted"} 1
+apisix_nginx_http_current_connections{state="active"} 1
+apisix_nginx_http_current_connections{state="handled"} 1
+apisix_nginx_http_current_connections{state="reading"} 0
+apisix_nginx_http_current_connections{state="waiting"} 0
+apisix_nginx_http_current_connections{state="writing"} 1
+...
```
-### Securing the Route
+### Expose Batch Requests Endpoint
+
+The following example demonstrates how you can use the `public-api` Plugin to
expose an endpoint for the `batch-requests` Plugin, which is used for
assembling multiple requests into one single request before sending them to the
gateway.
+
+[//]:<TODO: update link to batch-requests plugin doc when it is available>
-You can use the `key-auth` Plugin to add authentication and secure the Route:
+Create a sample Route to httpbin's `/anything` endpoint for verification
purpose:
```shell
-curl -X PUT 'http://127.0.0.1:9180/apisix/admin/routes/r2' \
- -H 'X-API-KEY: <api-key>' \
- -H 'Content-Type: application/json' \
- -d '{
- "uri": "/batch-requests-gifs",
- "plugins": {
- "public-api": {},
- "key-auth": {}
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "httpbin-anything",
+ "uri": "/anything",
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
+ }
}
-}'
+ }'
```
-Now, only authenticated requests are allowed:
+Create a Route with `public-api` Plugin and set the Route `uri` to the
internal endpoint to be exposed:
```shell
-curl --location --request POST 'http://127.0.0.1:9080/batch-requests-gifs' \
- -H "apikey: test-apikey"
- -H 'Content-Type: application/json' \
- --data '{...}'
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "batch-requests",
+ "uri": "/apisix/batch-requests",
+ "plugins": {
+ "public-api": {}
+ }
+ }'
```
+Send a pipelined request consisting of a GET and a POST request to the exposed
batch requests endpoint:
+
```shell
-HTTP/1.1 200 OK
+curl "http://127.0.0.1:9080/apisix/batch-requests"; -X POST -d '
+{
+ "pipeline": [
+ {
+ "method": "GET",
+ "path": "/anything"
+ },
+ {
+ "method": "POST",
+ "path": "/anything",
+ "body": "a post request"
+ }
+ ]
+}'
```
-The below request will fail:
+You should receive responses from both requests, similar to the following:
-```shell
-curl --location --request POST 'http://127.0.0.1:9080/batch-requests-gifs' \
- -H 'Content-Type: application/json' \
- --data '{...}'
+```json
+[
+ {
+ "reason": "OK",
+ "body": "{\n \"args\": {}, \n \"data\": \"\", \n \"files\": {}, \n
\"form\": {}, \n \"headers\": {\n \"Accept\": \"*/*\", \n \"Host\":
\"127.0.0.1\", \n \"User-Agent\": \"curl/8.6.0\", \n \"X-Amzn-Trace-Id\":
\"Root=1-67b6e33b-5a30174f5534287928c54ca9\", \n \"X-Forwarded-Host\":
\"127.0.0.1\"\n }, \n \"json\": null, \n \"method\": \"GET\", \n
\"origin\": \"192.168.107.1, 43.252.208.84\", \n \"url\":
\"http://127.0.0.1/anything\"\n}\n";,
+ "headers": {
+ ...
+ },
+ "status": 200
+ },
+ {
+ "reason": "OK",
+ "body": "{\n \"args\": {}, \n \"data\": \"a post request\", \n
\"files\": {}, \n \"form\": {}, \n \"headers\": {\n \"Accept\": \"*/*\",
\n \"Content-Length\": \"14\", \n \"Host\": \"127.0.0.1\", \n
\"User-Agent\": \"curl/8.6.0\", \n \"X-Amzn-Trace-Id\":
\"Root=1-67b6e33b-0eddcec07f154dac0d77876f\", \n \"X-Forwarded-Host\":
\"127.0.0.1\"\n }, \n \"json\": null, \n \"method\": \"POST\", \n
\"origin\": \"192.168.107.1, 43.252.208.84\", \n \"url\": \"http://12 [...]
+ "headers": {
+ ...
+ },
+ "status": 200
+ }
+]
```
+If you would like to expose the batch requests endpoint at a custom endpoint,
create a Route with `public-api` Plugin as such. You should set the Route `uri`
to the custom endpoint path and set the plugin `uri` to the internal endpoint
to be exposed.
+
```shell
-HTTP/1.1 401 Unauthorized
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "batch-requests",
+ "uri": "/batch-requests",
+ "plugins": {
+ "public-api": {
+ "uri": "/apisix/batch-requests"
+ }
+ }
+ }'
```
-## Delete Plugin
-
-To remove the `public-api` Plugin, you can delete the corresponding JSON
configuration from the Plugin configuration. APISIX will automatically reload
and you do not have to restart for this to take effect.
-
-:::note
-You can fetch the `admin_key` from `config.yaml` and save to an environment
variable with the following command:
+The batch requests endpoint should now be exposed as `/batch-requests`,
instead of `/apisix/batch-requests`.
-```bash
-admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed
's/"//g')
-```
-
-:::
+Send a pipelined request consisting of a GET and a POST request to the exposed
batch requests endpoint:
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X
PUT -d '
+curl "http://127.0.0.1:9080/batch-requests"; -X POST -d '
{
- "uri": "/hello",
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
+ "pipeline": [
+ {
+ "method": "GET",
+ "path": "/anything"
+ },
+ {
+ "method": "POST",
+ "path": "/anything",
+ "body": "a post request"
}
- }
+ ]
}'
```
+
+You should receive responses from both requests, similar to the following:
+
+```json
+[
+ {
+ "reason": "OK",
+ "body": "{\n \"args\": {}, \n \"data\": \"\", \n \"files\": {}, \n
\"form\": {}, \n \"headers\": {\n \"Accept\": \"*/*\", \n \"Host\":
\"127.0.0.1\", \n \"User-Agent\": \"curl/8.6.0\", \n \"X-Amzn-Trace-Id\":
\"Root=1-67b6e33b-5a30174f5534287928c54ca9\", \n \"X-Forwarded-Host\":
\"127.0.0.1\"\n }, \n \"json\": null, \n \"method\": \"GET\", \n
\"origin\": \"192.168.107.1, 43.252.208.84\", \n \"url\":
\"http://127.0.0.1/anything\"\n}\n";,
+ "headers": {
+ ...
+ },
+ "status": 200
+ },
+ {
+ "reason": "OK",
+ "body": "{\n \"args\": {}, \n \"data\": \"a post request\", \n
\"files\": {}, \n \"form\": {}, \n \"headers\": {\n \"Accept\": \"*/*\",
\n \"Content-Length\": \"14\", \n \"Host\": \"127.0.0.1\", \n
\"User-Agent\": \"curl/8.6.0\", \n \"X-Amzn-Trace-Id\":
\"Root=1-67b6e33b-0eddcec07f154dac0d77876f\", \n \"X-Forwarded-Host\":
\"127.0.0.1\"\n }, \n \"json\": null, \n \"method\": \"POST\", \n
\"origin\": \"192.168.107.1, 43.252.208.84\", \n \"url\": \"http://12 [...]
+ "headers": {
+ ...
+ },
+ "status": 200
+ }
+]
+```
diff --git a/docs/zh/latest/plugins/public-api.md
b/docs/zh/latest/plugins/public-api.md
index 56abc2532..b20f802e5 100644
--- a/docs/zh/latest/plugins/public-api.md
+++ b/docs/zh/latest/plugins/public-api.md
@@ -4,7 +4,7 @@ keywords:
- APISIX
- API 网关
- Public API
-description: 本文介绍了 public-api 的相关操作，你可以使用 public-api 插件保护你需要暴露的 API 的端点。
+description: public-api 插件公开了一个内部 API 端点，使其可被公开访问。该插件的主要用途之一是公开由其他插件创建的内部端点。
---
<!--
@@ -26,202 +26,217 @@ description: 本文介绍了 public-api 的相关操作，你可以使用 public
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/public-api"; />
+</head>
+
## 描述
-`public-api` 插件可用于通过创建路由的方式暴露用户自定义的 API。
+`public-api` 插件公开了一个内部 API 端点，使其可被公开访问。该插件的主要用途之一是公开由其他插件创建的内部端点。
-你可以通过在路由中添加 `public-api` 插件，来保护**自定义插件为了实现特定功能**而暴露的 API。例如，你可以使用
[batch-requests](./batch-requests.md) 插件创建一个公共 API 端点 `/apisix/batch-requests`
用于在一个请求中组合多个 API 请求。
+## 属性
-:::note 注意
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+|------|--------|-------|-------|------|------|
+| uri | string | 否 | | | 内部端点的 URI。如果未配置，则暴露路由的 URI。|
-默认情况下，在自定义插件中添加的公共 API 不对外暴露的，你需要手动配置一个路由并启用 `public-api` 插件。
+## 示例
-:::
-
-## 属性
+以下示例展示了如何在不同场景中配置 `public-api`。
-| 名称 | 类型 | 必选项 | 默认值 | 描述
|
-|------|--------|----------|---------|------------------------------------------------------------|
-| uri | string | 否 | "" | 公共 API 的 URI。在设置路由时，使用此属性来配置初始的公共 API
URI。 |
+### 在自定义端点暴露 Prometheus 指标
-## 启用插件
+以下示例演示如何禁用默认在端口 `9091` 上暴露端点的 Prometheus 导出服务器，并在 APISIX 用于监听其他客户端请求的端口 `9080`
上，通过新的公共 API 端点暴露 APISIX 的 Prometheus 指标。
-`public-api` 插件需要与授权插件一起配合使用，以下示例分别用到了 [batch-requests](./batch-requests.md)
插件和 [`key-auth`](./key-auth.md)
+此外，还会配置路由，使内部端点 `/apisix/prometheus/metrics` 通过自定义端点对外公开。
-### 基本用法
+:::caution
-首先，你需要启用并配置 `batch-requests` 插件，详细使用方法请参考
[batch-requests](./batch-requests.md) 插件文档。
+如果收集了大量指标，插件可能会占用大量 CPU 资源用于计算，从而影响正常请求的处理。
-然后，使用以下命令在指定路由上启用并配置 `public-api` 插件：
+为了解决这个问题，APISIX 使用
[特权代理进程](https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/process.md#enable_privileged_agent)
，并将指标计算卸载至独立进程。如果使用配置文件中 `plugin_attr.prometheus.export_addr`
设定的指标端点，该优化将自动生效。但如果通过 `public-api` 插件暴露指标端点，则不会受益于此优化。
-:::note
+:::
-您可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量：
+在配置文件中禁用 Prometheus 导出服务器，并重新加载 APISIX 以使更改生效：
-```bash
-admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed
's/"//g')
+```yaml
+plugin_attr:
+ prometheus:
+ enable_export_server: false
```
-:::
+接下来，创建一个带有 `public-api` 插件的路由，并为 APISIX 指标暴露一个公共 API 端点。你应将路由的 `uri`
设置为自定义端点路径，并将插件的 `uri` 设置为要暴露的内部端点。
```shell
-curl -X PUT 'http://127.0.0.1:9180/apisix/admin/routes/r1' \
- -H 'X-API-KEY: <api-key>' \
- -H 'Content-Type: application/json' \
- -d '{
- "uri": "/apisix/batch-requests",
- "plugins": {
- "public-api": {}
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H 'X-API-KEY: ${admin_key}' \
+ -d '{
+ "id": "prometheus-metrics",
+ "uri": "/prometheus_metrics",
+ "plugins": {
+ "public-api": {
+ "uri": "/apisix/prometheus/metrics"
+ }
}
-}'
+ }'
```
-**测试插件**
-
-向配置的 URI 发出访问请求，会返回一个包含多个 API 请求结果的的响应：
+向自定义指标端点发送请求：
```shell
-curl --location --request POST 'http://127.0.0.1:9080/apisix/batch-requests' \
---header 'Content-Type: application/json' \
---data '{
- "headers": {
- "Content-Type": "application/json",
- "admin-jwt":"xxxx"
- },
- "timeout": 500,
- "pipeline": [
- {
- "method": "POST",
- "path": "/community.GiftSrv/GetGifts",
- "body": "test"
- },
- {
- "method": "POST",
- "path": "/community.GiftSrv/GetGifts",
- "body": "test2"
- }
- ]
-}'
+curl http://127.0.0.1:9080/prometheus_metrics
```
-```shell
-[
- {
- "status": 200,
- "reason": "OK",
- "body":
"{\"ret\":500,\"msg\":\"error\",\"game_info\":null,\"gift\":[],\"to_gets\":0,\"get_all_msg\":\"\"}",
- "headers": {
- "Connection": "keep-alive",
- "Date": "Sat, 11 Apr 2020 17:53:20 GMT",
- "Content-Type": "application/json",
- "Content-Length": "81",
- "Server": "APISIX web server"
- }
- },
- {
- "status": 200,
- "reason": "OK",
- "body":
"{\"ret\":500,\"msg\":\"error\",\"game_info\":null,\"gift\":[],\"to_gets\":0,\"get_all_msg\":\"\"}",
- "headers": {
- "Connection": "keep-alive",
- "Date": "Sat, 11 Apr 2020 17:53:20 GMT",
- "Content-Type": "application/json",
- "Content-Length": "81",
- "Server": "APISIX web server"
- }
- }
-]
+你应看到类似以下的输出：
+
+```text
+# HELP apisix_http_requests_total The total number of client requests since
APISIX started
+# TYPE apisix_http_requests_total gauge
+apisix_http_requests_total 1
+# HELP apisix_nginx_http_current_connections Number of HTTP connections
+# TYPE apisix_nginx_http_current_connections gauge
+apisix_nginx_http_current_connections{state="accepted"} 1
+apisix_nginx_http_current_connections{state="active"} 1
+apisix_nginx_http_current_connections{state="handled"} 1
+apisix_nginx_http_current_connections{state="reading"} 0
+apisix_nginx_http_current_connections{state="waiting"} 0
+apisix_nginx_http_current_connections{state="writing"} 1
+...
```
-### 使用自定义 URI
+### 暴露批量请求端点
-首先，你需要启用并配置 `batch-requests` 插件，详细使用方法请参考
[batch-requests](./batch-requests.md) 插件文档。
+以下示例展示了如何使用 `public-api` 插件来暴露 `batch-requests`
插件的端点，该插件用于将多个请求组合成一个请求，然后将它们发送到网关。
-然后，你可以使用一个自定义的 URI 来暴露 API：
+创建一个样本路由到 httpbin 的 `/anything` 端点，用于验证目的：
```shell
-curl -X PUT 'http://127.0.0.1:9180/apisix/admin/routes/r2' \
- -H 'X-API-KEY: <api-key>' \
- -H 'Content-Type: application/json' \
- -d '{
- "uri": "/batch-requests-gifs",
- "plugins": {
- "public-api": {
- "uri": "/apisix/batch-requests"
- }
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "httpbin-anything",
+ "uri": "/anything",
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
+ }
}
-}'
+ }'
```
-**测试插件**
-
-向自定义的 URI 发出访问请求，如果返回一个包含多个 API 请求结果的响应，则代表插件生效：
+创建一个带有 `public-api` 插件的路由，并将路由的 `uri` 设置为要暴露的内部端点：
```shell
-curl --location --request POST 'http://127.0.0.1:9080/batch-requests-gifs' \
---header 'Content-Type: application/json' \
---data '{...}'
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "batch-requests",
+ "uri": "/apisix/batch-requests",
+ "plugins": {
+ "public-api": {}
+ }
+ }'
```
-### 确保 Route 安全
-
-你可以配合使用 `key-auth` 插件来添加认证，从而确保路由的安全：
+向暴露的批量请求端点发送一个包含 GET 和 POST 请求的流水线请求：
```shell
-curl -X PUT 'http://127.0.0.1:9180/apisix/admin/routes/r2' \
- -H 'X-API-KEY: <api-key>' \
- -H 'Content-Type: application/json' \
- -d '{
- "uri": "/batch-requests-gifs",
- "plugins": {
- "public-api": {},
- "key-auth": {}
+curl "http://127.0.0.1:9080/apisix/batch-requests"; -X POST -d '
+{
+ "pipeline": [
+ {
+ "method": "GET",
+ "path": "/anything"
+ },
+ {
+ "method": "POST",
+ "path": "/anything",
+ "body": "a post request"
}
+ ]
}'
```
-**测试插件**
+您应该会收到两个请求的响应，类似于以下内容：
-通过上述命令启用插件并添加认证后，只有经过认证的请求才能访问。
-
-发出访问请求并指定 `apikey`，如果返回 `200` HTTP 状态码，则说明请求被允许：
-
-```shell
-curl --location --request POST 'http://127.0.0.1:9080/batch-requests-gifs' \
- -H "apikey: test-apikey"
- -H 'Content-Type: application/json' \
- --data '{...}'
-```
-
-```shell
-HTTP/1.1 200 OK
+```json
+[
+ {
+ "reason": "OK",
+ "body": "{\n \"args\": {}, \n \"data\": \"\", \n \"files\": {}, \n
\"form\": {}, \n \"headers\": {\n \"Accept\": \"*/*\", \n \"Host\":
\"127.0.0.1\", \n \"User-Agent\": \"curl/8.6.0\", \n \"X-Amzn-Trace-Id\":
\"Root=1-67b6e33b-5a30174f5534287928c54ca9\", \n \"X-Forwarded-Host\":
\"127.0.0.1\"\n }, \n \"json\": null, \n \"method\": \"GET\", \n
\"origin\": \"192.168.107.1, 43.252.208.84\", \n \"url\":
\"http://127.0.0.1/anything\"\n}\n";,
+ "headers": {
+ ...
+ },
+ "status": 200
+ },
+ {
+ "reason": "OK",
+ "body": "{\n \"args\": {}, \n \"data\": \"a post request\", \n
\"files\": {}, \n \"form\": {}, \n \"headers\": {\n \"Accept\": \"*/*\",
\n \"Content-Length\": \"14\", \n \"Host\": \"127.0.0.1\", \n
\"User-Agent\": \"curl/8.6.0\", \n \"X-Amzn-Trace-Id\":
\"Root=1-67b6e33b-0eddcec07f154dac0d77876f\", \n \"X-Forwarded-Host\":
\"127.0.0.1\"\n }, \n \"json\": null, \n \"method\": \"POST\", \n
\"origin\": \"192.168.107.1, 43.252.208.84\", \n \"url\": \"http://12 [...]
+ "headers": {
+ ...
+ },
+ "status": 200
+ }
+]
```
-发出访问请求，如果返回 `401` HTTP 状态码，则说明请求被阻止，插件生效：
+如果您希望在自定义端点处暴露批量请求端点，请创建一个带有 `public-api` 插件的路由。您应该将路由的 `uri` 设置为自定义端点路径，并将插件的
uri 设置为要暴露的内部端点。
```shell
-curl --location --request POST 'http://127.0.0.1:9080/batch-requests-gifs' \
- -H 'Content-Type: application/json' \
- --data '{...}'
-```
-
-```shell
-HTTP/1.1 401 Unauthorized
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "batch-requests",
+ "uri": "/batch-requests",
+ "plugins": {
+ "public-api": {
+ "uri": "/apisix/batch-requests"
+ }
+ }
+ }'
```
-## 删除插件
-
-当你需要删除该插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
+现在批量请求端点应该被暴露为 `/batch-requests`，而不是 `/apisix/batch-requests`。
+向暴露的批量请求端点发送一个包含 GET 和 POST 请求的流水线请求：
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X
PUT -d '
+curl "http://127.0.0.1:9080/batch-requests"; -X POST -d '
{
- "uri": "/hello",
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
+ "pipeline": [
+ {
+ "method": "GET",
+ "path": "/anything"
+ },
+ {
+ "method": "POST",
+ "path": "/anything",
+ "body": "a post request"
}
- }
+ ]
}'
```
+
+您应该会收到两个请求的响应，类似于以下内容：
+
+```json
+[
+ {
+ "reason": "OK",
+ "body": "{\n \"args\": {}, \n \"data\": \"\", \n \"files\": {}, \n
\"form\": {}, \n \"headers\": {\n \"Accept\": \"*/*\", \n \"Host\":
\"127.0.0.1\", \n \"User-Agent\": \"curl/8.6.0\", \n \"X-Amzn-Trace-Id\":
\"Root=1-67b6e33b-5a30174f5534287928c54ca9\", \n \"X-Forwarded-Host\":
\"127.0.0.1\"\n }, \n \"json\": null, \n \"method\": \"GET\", \n
\"origin\": \"192.168.107.1, 43.252.208.84\", \n \"url\":
\"http://127.0.0.1/anything\"\n}\n";,
+ "headers": {
+ ...
+ },
+ "status": 200
+ },
+ {
+ "reason": "OK",
+ "body": "{\n \"args\": {}, \n \"data\": \"a post request\", \n
\"files\": {}, \n \"form\": {}, \n \"headers\": {\n \"Accept\": \"*/*\",
\n \"Content-Length\": \"14\", \n \"Host\": \"127.0.0.1\", \n
\"User-Agent\": \"curl/8.6.0\", \n \"X-Amzn-Trace-Id\":
\"Root=1-67b6e33b-0eddcec07f154dac0d77876f\", \n \"X-Forwarded-Host\":
\"127.0.0.1\"\n }, \n \"json\": null, \n \"method\": \"POST\", \n
\"origin\": \"192.168.107.1, 43.252.208.84\", \n \"url\": \"http://12 [...]
+ "headers": {
+ ...
+ },
+ "status": 200
+ }
+]
+```
