You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by sy...@apache.org on 2022/10/27 01:42:20 UTC
[apisix] branch master updated: docs: refactor admin api doc (#8145)
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 df6923913 docs: refactor admin api doc (#8145)
df6923913 is described below
commit df6923913b8add64883bb1df4a0507ce480837ca
Author: Fei Han <97...@users.noreply.github.com>
AuthorDate: Thu Oct 27 09:42:11 2022 +0800
docs: refactor admin api doc (#8145)
* docs: refactor admin api doc
---
docs/zh/latest/admin-api.md | 1702 ++++++++++++++++++++++++-------------------
1 file changed, 958 insertions(+), 744 deletions(-)
diff --git a/docs/zh/latest/admin-api.md b/docs/zh/latest/admin-api.md
index 070800bf7..9d66b8bbd 100644
--- a/docs/zh/latest/admin-api.md
+++ b/docs/zh/latest/admin-api.md
@@ -1,5 +1,13 @@
---
title: Admin API
+keywords:
+ - APISIX
+ - API 网关
+ - Admin API
+ - 路由
+ - 插件
+ - 上游
+description: 本文介绍了 Apache APISIX Admin API 支持的功能，你可以通过 Admin API 来获取、创建、更新以及删除资源。
---
<!--
@@ -21,78 +29,121 @@ title: Admin API
#
-->
-## 描述
+## 描述 {#description}
-Admin API 是为 Apache APISIX 服务的一组 API，我们可以将参数传递给 Admin API 以控制 APISIX 节点。更好地了解其工作原理，请参阅 [Architecture Design](./architecture-design/apisix.md) 中的文档。
+Admin API 是一组用于配置 Apache APISIX 路由、上游、服务、SSL 证书等功能的 RESTful API。
-启动 Apache APISIX 时，默认情况下 Admin API 将监听 `9180` 端口。您可以通过修改 [conf/config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 文件来改变默认监听的端口。
+你可以通过 Admin API 来获取、创建、更新以及删除资源。同时得益于 APISIX 的热加载能力，资源配置完成后 APISIX 将会自动更新配置，无需重启服务。如果你想要了解其工作原理，请参考 [Architecture Design](./architecture-design/apisix.md)。
-在下面出现的 `X-API-KEY` 指的是 `conf/config.yaml` 文件中的 `deployment.admin.admin_key.key`，它是 Admin API 的访问 token。
+## 相关配置 {#basic-configuration}
-## V3
+当 APISIX 启动时，Admin API 默认情况下将会监听 `9180` 端口，并且会占用前缀为 `/apisix/admin` 的 API。
-Admin API 在 V3 版本中做了一些不向下兼容的调整，以及支持更多特性。
+因此，为了避免你设计的 API 与 `/apisix/admin` 冲突，你可以通过修改配置文件 [`/conf/config.yaml`](https://github.com/apache/apisix/blob/master/conf/config.yaml) 中的配置修改默认监听端口。
-### 支持新的响应体格式
+APISIX 支持设置 Admin API 的 IP 访问白名单，防止 APISIX 被非法访问和攻击。你可以在 `./conf/config.yaml` 文件中的 `deployment.admin.allow_admin` 选项中，配置允许访问的 IP 地址。
-1. 移除响应体中的 `action` 字段；
-2. 调整获取资源列表时的响应体结构，新的响应体结构示例如下：
+在下文出现的 `X-API-KEY` 指的是 `./conf/config.yaml` 文件中的 `deployment.admin.admin_key.key`，它是 Admin API 的访问 token。
-返回单个资源：
+:::tip 提示
-```json
-{
- "modifiedIndex": 2685183,
- "value": {
- "id": "1",
- ...
- },
- "key": "/apisix/routes/1",
- "createdIndex": 2684956
-}
+建议你修改 Admin API 默认的监听端口、IP 访问白名单以及 Admin API 的 token，以保证你的 API 安全。
+
+:::
+
+```yaml title="./conf/config.yaml"
+deployment:
+ admin:
+ admin_key:
+ - name: admin
+ key: edd1c9f034335f136f87ad84b625c8f1 # 使用默认的 Admin API Key 存在安全风险，部署到生产环境时请及时更新
+ role: admin
+ allow_admin: # http://nginx.org/en/docs/http/ngx_http_access_module.html#allow
+ - 127.0.0.0/24
+ admin_listen:
+ ip: 0.0.0.0 # Admin API 监听的 IP，如果不设置，默认为“0.0.0.0”。
+ port: 9180 # Admin API 监听的 端口，必须使用与 node_listen 不同的端口。
```
-返回多个资源：
+## v3 版本新功能 {#v3-new-function}
-```json
-{
- "list": [
+在 APISIX v3 版本中，Admin API 支持了一些不向下兼容的新特性，比如支持新的响应体格式、支持分页查询、支持过滤资源等。
+
+### 支持新的响应体格式 {#support-new-response-body-format}
+
+APISIX 在 v3 版本对响应体做了以下调整：
+
+- 移除旧版本响应体中的 `action` 字段；
+- 调整获取资源列表时的响应体结构，新的响应体结构示例如下：
+
+返回单个资源：
+
+ ```json
{
- "modifiedIndex": 2685183,
- "value": {
+ "modifiedIndex": 2685183,
+ "value": {
"id": "1",
...
- },
- "key": "/apisix/routes/1",
- "createdIndex": 2684956
},
+ "key": "/apisix/routes/1",
+ "createdIndex": 2684956
+ }
+ ```
+
+返回多个资源：
+
+ ```json
{
- "modifiedIndex": 2685163,
- "value": {
- "id": "2",
- ...
- },
- "key": "/apisix/routes/2",
- "createdIndex": 2685163
+ "list": [
+ {
+ "modifiedIndex": 2685183,
+ "value": {
+ "id": "1",
+ ...
+ },
+ "key": "/apisix/routes/1",
+ "createdIndex": 2684956
+ },
+ {
+ "modifiedIndex": 2685163,
+ "value": {
+ "id": "2",
+ ...
+ },
+ "key": "/apisix/routes/2",
+ "createdIndex": 2685163
+ }
+ ],
+ "total": 2
}
- ],
- "total": 2
-}
-```
+ ```
+
+### 支持分页查询 {#support-paging-query}
+
+获取资源列表时支持分页查询，目前支持分页查询的资源如下：
-### 支持分页查询
+- [Consumer](#consumer)
+- [Consumer Group](#consumer-group)
+- [Global Rules](#global-rules)
+- [Plugin Config](#plugin-config)
+- [Protos](https://apisix.apache.org/zh/docs/apisix/plugins/grpc-transcode/#%E5%90%AF%E7%94%A8%E6%8F%92%E4%BB%B6)
+- [Route](#route)
+- [Service](#service)
+- [SSL](#ssl)
+- [Stream Route](#stream-route)
+- [Upstream](#upstream)
-获取资源列表时支持分页查询，分页参数包括：
+参数如下：
-| 参数 | 默认值 | 范围 | 说明 |
-| --------- | ------ | -------- | ------------ |
-| page | 1 | [1, ...] | 页数 |
-| page_size | | [10, 500]| 每页资源数量 |
+| 名称 | 默认值 | 范围 | 描述 |
+| --------- | ------ | -------- | -------------------------------------------------- |
+| page | 1 | [1, ...] | 页数，默认展示第一页。 |
+| page_size | | [10, 500]| 每页资源数量。如果不配置该参数，则展示所有查询到的资源。|
示例如下：
```shell
-$ curl "http://127.0.0.1:9180/apisix/admin/routes?page=1&page_size=10" \
+curl "http://127.0.0.1:9180/apisix/admin/routes?page=1&page_size=10" \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X GET
```
@@ -107,37 +158,31 @@ $ curl "http://127.0.0.1:9180/apisix/admin/routes?page=1&page_size=10" \
}
```
-目前支持分页查询的资源如下：
+### 支持过滤资源 {#support filtering query}
-- Consumer
-- Consumer Group
-- Global Rules
-- Plugin Config
-- Proto
-- Route
-- Service
-- SSL
-- Stream Route
-- Upstream
+在 APISIX v3 版本中，在获取资源列表时，你可以使用 `name`、`label` 和 `uri` 参数过滤资源。支持参数如下：
-### 支持过滤资源
+| 名称 | 描述 |
+| ----- | ------------------------------------------------------------------------------------------------------------------------ |
+| name | 根据资源的 `name` 属性进行查询，如果资源本身没有 `name` 属性则不会出现在查询结果中。 |
+| label | 根据资源的 `label` 属性进行查询，如果资源本身没有 `label` 属性则不会出现在查询结果中。 |
+| uri | 该参数仅在 Route 资源上支持。如果 Route 的 `uri` 等于查询的 `uri` 或 `uris` 包含查询的 `uri`，则该 Route 资源出现在查询结果中。 |
-获取资源列表时支持根据 `name`, `label`, `uri` 过滤资源。
+:::tip 提示
-| 参数 | 说明 |
-| ----- | --------------------------------------------------------------------------------------------------- |
-| name | 根据资源的 `name` 属性进行查询，如果资源本身没有 `name` 属性则不会出现在查询结果中。 |
-| label | 根据资源的 `label` 属性进行查询，如果资源本身没有 `labe`l 属性则不会出现在查询结果中。 |
-| uri | 仅在 Route 资源上支持。如果 Route 的 `uri` 等于查询的 uri 或 `uris` 包含查询的 uri，则该 Route 资源出现在查询结果中。 |
+当使用多个过滤参数时，APISIX 将对不同过滤参数的查询结果取交集。
-当启用了多个过滤参数时，对不同过滤参数的查询结果取交集。
-下述示例将返回一个路由列表，该路由列表中的所有路由满足以下条件：路由的 `name` 包含字符串 "test"；`uri` 包含字符串 "foo"；对路由的 `label` 没有限制，因为查询的 label 是空字符串。
+:::
+
+以下示例将返回一个路由列表，该路由列表中的所有路由需要满足以下条件：路由的 `name` 包含字符串 `test`；`uri` 包含字符串 `foo`；对路由的 `label` 没有限制，因为 `label` 为空字符串。
```shell
-$ curl 'http://127.0.0.1:9180/apisix/admin/routes?name=test&uri=foo&label=' \
+curl 'http://127.0.0.1:9180/apisix/admin/routes?name=test&uri=foo&label=' \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X GET
```
+返回结果：
+
```json
{
"total": 1,
@@ -151,65 +196,67 @@ $ curl 'http://127.0.0.1:9180/apisix/admin/routes?name=test&uri=foo&label=' \
## Route
-*地址*：/apisix/admin/routes/{id}?ttl=0
-
-*说明*：Route 字面意思就是路由，通过定义一些规则来匹配客户端的请求，然后根据匹配结果加载并执行相应的插件，并把请求转发给到指定 Upstream。
-
-注意：在启用 `Admin API` 时，它会占用前缀为 `/apisix/admin` 的 API。因此，为了避免您设计 API 与 `/apisix/admin` 冲突，建议为 Admin API 使用其他端口，您可以在 `conf/config.yaml` 中通过 `admin_listen` 进行自定义 Admin API 端口。
-
-### 请求方法
-
-| 名字 | 请求 uri | 请求 body | 说明 |
-| ------ | -------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| GET | /apisix/admin/routes | 无 | 获取资源列表 |
-| GET | /apisix/admin/routes/{id} | 无 | 获取资源 |
-| PUT | /apisix/admin/routes/{id} | {...} | 根据 id 创建资源 |
-| POST | /apisix/admin/routes | {...} | 创建资源，id 由后台服务自动生成 |
-| DELETE | /apisix/admin/routes/{id} | 无 | 删除资源 |
-| PATCH | /apisix/admin/routes/{id} | {...} | 标准 PATCH ，修改已有 Route 的部分属性，其他不涉及的属性会原样保留；如果你要删除某个属性，将该属性的值设置为 null 即可删除；特别地，当需要修改属性的值为数组时，该属性将全量更新 |
-| PATCH | /apisix/admin/routes/{id}/{path} | {...} | SubPath PATCH，通过 {path} 指定 Route 要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。两种 PATCH 的区别可以参考后面的示例 |
-
-### URL 请求参数
-
-| 名字 | 可选项 | 类型 | 说明 | 示例 |
-| ---- | ------ | ---- | ---------------------------------- | ----- |
-| ttl | 可选 | 辅助 | 超过这个时间会被自动删除，单位：秒 | ttl=1 |
-
-### body 请求参数
-
-| 名字 | 可选项 | 类型 | 说明 | 示例 |
-| ---------------- | ---------------------------------- | -------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ---------------------------------------------------- |
-| uri | 必选，不能与 `uris` 一起使用 | 匹配规则 | 除了如 `/foo/bar`、`/foo/gloo` 这种全量匹配外，使用不同 [Router](terminology/router.md) 还允许更高级匹配，更多见 [Router](terminology/router.md)。 | "/hello" |
-| uris | 必选，不能与 `uri` 一起使用 | 匹配规则 | 非空数组形式，可以匹配多个 `uri` | ["/hello", "/world"] |
-| plugins | 可选 | Plugin | 详见 [Plugin](terminology/plugin.md) | |
-| script | 可选 | Script | 详见 [Script](terminology/script.md) | |
-| upstream | 可选 | Upstream | 启用的 Upstream 配置，详见 [Upstream](terminology/upstream.md) | |
-| upstream_id | 可选 | Upstream | 启用的 upstream id，详见 [Upstream](terminology/upstream.md) | |
-| service_id | 可选 | Service | 绑定的 Service 配置，详见 [Service](terminology/service.md) | |
-| plugin_config_id | 可选，无法跟 script 一起配置 | Plugin | 绑定的 Plugin config 配置，详见 [Plugin config](terminology/plugin-config.md) | |
-| name | 可选 | 辅助 | 标识路由名称 | route-xxxx |
-| desc | 可选 | 辅助 | 标识描述、使用场景等。 | 路由 xxxx |
-| host | 可选，不能与 `hosts` 一起使用 | 匹配规则 | 当前请求域名，比如 `foo.com`；也支持泛域名，比如 `*.foo.com`。 | "foo.com" |
-| hosts | 可选，不能与 `host` 一起使用 | 匹配规则 | 非空列表形态的 `host`，表示允许有多个不同 `host`，匹配其中任意一个即可。 | ["foo.com", "\*.bar.com"] |
-| remote_addr | 可选，不能与 `remote_addrs` 一起使用 | 匹配规则 | 客户端请求 IP 地址：`192.168.1.101`、`192.168.1.102` 以及 CIDR 格式的支持 `192.168.1.0/24`。特别的，APISIX 也完整支持 IPv6 地址匹配：`::1`，`fe80::1`，`fe80::1/64` 等。 | "192.168.1.0/24" |
-| remote_addrs | 可选，不能与 `remote_addr` 一起使用 | 匹配规则 | 非空列表形态的 `remote_addr`，表示允许有多个不同 IP 地址，符合其中任意一个即可。 | ["127.0.0.1", "192.0.0.0/8", "::1"] |
-| methods | 可选 | 匹配规则 | 如果为空或没有该选项，代表没有任何 `method` 限制，也可以是一个或多个的组合：`GET`，`POST`，`PUT`，`DELETE`，`PATCH`，`HEAD`，`OPTIONS`，`CONNECT`，`TRACE`，`PURGE`。 | ["GET", "POST"] |
-| priority | 可选 | 匹配规则 | 如果不同路由包含相同 `uri`，根据属性 `priority` 确定哪个 `route` 被优先匹配，值越大优先级越高，默认值为 0。 | priority = 10 |
-| vars | 可选 | 匹配规则 | 由一个或多个`[var, operator, val]`元素组成的列表，类似这样：`[[var, operator, val], [var, operator, val], ...]]`。例如：`["arg_name", "==", "json"]`，表示当前请求参数 `name` 是 `json`。这里的 `var` 与 Nginx 内部自身变量命名是保持一致，所以也可以使用 `request_uri`、`host` 等。更多细节请参考[lua-resty-expr](https://github.com/api7/lua-resty-expr) | [["arg_name", "==", "json"], ["arg_age", ">", 18]] |
-| filter_func | 可选 | 匹配规则 | 用户自定义的过滤函数。可以使用它来实现特殊场景的匹配要求实现。该函数默认接受一个名为 vars 的输入参数，可以用它来获取 Nginx 变量。 | function(vars) return vars["arg_name"] == "json" end |
-| labels | 可选 | 匹配规则 | 标识附加属性的键值对 | {"version":"v2","build":"16","env":"production"} |
-| timeout | 可选 | 辅助 | 为 route 设置 upstream 的连接、发送消息、接收消息的超时时间（单位为秒）。这个配置将会覆盖在 upstream 中 配置的 [timeout](#upstream) 选项 | {"connect": 3, "send": 3, "read": 3} |
-| enable_websocket | 可选 | 辅助 | 是否启用 `websocket`(boolean), 缺省 `false`。 | |
-| status | 可选 | 辅助 | 是否启用此路由，缺省 `1`。 | `1` 表示启用，`0` 表示禁用 |
-| create_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 |
-| update_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 |
-
-有两点需要特别注意：
-
-- 对于同一类参数比如 `uri`与 `uris`，`upstream` 与 `upstream_id`，`host` 与 `hosts`，`remote_addr` 与 `remote_addrs` 等，是不能同时存在，二者只能选择其一。如果同时启用，接口会报错。
-- 在 `vars` 中，当获取 cookie 的值时，cookie name 是**区分大小写字母**的。例如：`var` 等于 "cookie_x_foo" 与 `var` 等于 "cookie_X_Foo" 表示不同的 `cookie`。
-
-route 对象 json 配置内容：
+Route 也称之为路由，可以通过定义一些规则来匹配客户端的请求，然后根据匹配结果加载并执行相应的插件，并把请求转发给到指定 Upstream（上游）。
+
+### 请求地址 {#route-uri}
+
+路由资源请求地址：/apisix/admin/routes/{id}?ttl=0
+
+### 请求方法 {#route-request-methods}
+
+| 名称 | 请求 URI | 请求 body | 描述 |
+| ------ | -------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| GET | /apisix/admin/routes | 无 | 获取资源列表。 |
+| GET | /apisix/admin/routes/{id} | 无 | 获取资源。 |
+| PUT | /apisix/admin/routes/{id} | {...} | 根据 id 创建资源。 |
+| POST | /apisix/admin/routes | {...} | 创建资源，id 将会自动生成成。 |
+| DELETE | /apisix/admin/routes/{id} | 无 | 删除指定资源。 |
+| PATCH | /apisix/admin/routes/{id} | {...} | 标准 PATCH，修改指定 Route 的部分属性，其他不涉及的属性会原样保留；如果你需要删除某个属性，可以将该属性的值设置为 `null`；当需要修改属性的值为数组时，该属性将全量更新。 |
+| PATCH | /apisix/admin/routes/{id}/{path} | {...} | SubPath PATCH，通过 `{path}` 指定 Route 要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。两种 PATCH 的区别，请参考使用示例。 |
+
+### URI 请求参数 {#route-uri-request-parameters}
+
+| 名称 | 必选项 | 类型 | 描述 | 示例 |
+| ---- | ------ | ---- | -------------------------------------------- | ----- |
+| ttl | 否 | 辅助 | 路由的有效期。超过定义的时间，APISIX 将会自动删除路由，单位为秒。 | ttl=1 |
+
+### body 请求参数 {#route-request-body-parameters}
+
+| 名称 | 必选项 | 类型 | 描述 | 示例值 |
+| ---------------- | -------------------------------- | -------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ---------------------------------------------------- |
+| uri | 是，与 `uris` 二选一。 | 匹配规则 | 除了如 `/foo/bar`、`/foo/gloo` 这种全量匹配外，使用不同 [Router](terminology/router.md) 还允许更高级匹配，更多信息请参考 [Router](terminology/router.md)。 | "/hello" |
+| uris | 是，不能与 `uri` 二选一。 | 匹配规则 | 非空数组形式，可以匹配多个 `uri`。 | ["/hello", "/world"] |
+| plugins | 否 | Plugin | Plugin 配置，请参考 [Plugin](terminology/plugin.md)。 | |
+| script | 否 | Script | Script 配置，请参考 [Script](terminology/script.md)。 | |
+| upstream | 否 | Upstream | Upstream 配置，请参考 [Upstream](terminology/upstream.md)。 | |
+| upstream_id | 否 | Upstream | 需要使用的 Upstream id，请参考 [Upstream](terminology/upstream.md)。 | |
+| service_id | 否 | Service | 需要绑定的 Service id，请参考 [Service](terminology/service.md)。 | |
+| plugin_config_id | 否，不能与 Script 共同使用。 | Plugin | 需要绑定的 Plugin Config id，请参考 [Plugin Config](terminology/plugin-config.md)。 | |
+| name | 否 | 辅助 | 路由名称。 | route-test |
+| desc | 否 | 辅助 | 路由描述信息。 | 用来测试的路由。 |
+| host | 否，与 `hosts` 二选一。 | 匹配规则 | 当前请求域名，比如 `foo.com`；也支持泛域名，比如 `*.foo.com`。 | "foo.com" |
+| hosts | 否，与 `host` 二选一。 | 匹配规则 | 非空列表形态的 `host`，表示允许有多个不同 `host`，匹配其中任意一个即可。 | ["foo.com", "\*.bar.com"] |
+| remote_addr | 否，与 `remote_addrs` 二选一。| 匹配规则 | 客户端请求的 IP 地址。支持 IPv4 地址，如：`192.168.1.101` 以及 CIDR 格式的支持 `192.168.1.0/24`；支持 IPv6 地址匹配，如 `::1`，`fe80::1`，`fe80::1/64` 等。 | "192.168.1.0/24" |
+| remote_addrs | 否，与 `remote_addr` 二选一。| 匹配规则 | 非空列表形态的 `remote_addr`，表示允许有多个不同 IP 地址，符合其中任意一个即可。 | ["127.0.0.1", "192.0.0.0/8", "::1"] |
+| methods | 否 | 匹配规则 | 如果为空或没有该选项，则表示没有任何 `method` 限制。你也可以配置一个或多个的组合：`GET`，`POST`，`PUT`，`DELETE`，`PATCH`，`HEAD`，`OPTIONS`，`CONNECT`，`TRACE`，`PURGE`。 | ["GET", "POST"] |
+| priority | 否 | 匹配规则 | 如果不同路由包含相同的 `uri`，则根据属性 `priority` 确定哪个 `route` 被优先匹配，值越大优先级越高，默认值为 `0`。 | priority = 10 |
+| vars | 否 | 匹配规则 | 由一个或多个`[var, operator, val]`元素组成的列表，类似 `[[var, operator, val], [var, operator, val], ...]]`。例如：`["arg_name", "==", "json"]` 则表示当前请求参数 `name` 是 `json`。此处 `var` 与 NGINX 内部自身变量命名是保持一致的，所以也可以使用 `request_uri`、`host` 等。更多细节请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 | [["arg_name", "==", "json"], ["arg_age", ">", 18]] |
+| filter_func | 否 | 匹配规则 | 用户自定义的过滤函数。可以使用它来实现特殊场景的匹配要求实现。该函数默认接受一个名为 `vars` 的输入参数，可以用它来获取 NGINX 变量。 | function(vars) return vars["arg_name"] == "json" end |
+| labels | 否 | 匹配规则 | 标识附加属性的键值对。 | {"version":"v2","build":"16","env":"production"} |
+| timeout | 否 | 辅助 | 为 Route 设置 Upstream 连接、发送消息和接收消息的超时时间（单位为秒）。该配置将会覆盖在 Upstream 中配置的 [timeout](#upstream) 选项。 | {"connect": 3, "send": 3, "read": 3} |
+| enable_websocket | 否 | 辅助 | 当设置为 `true` 时，启用 `websocket`(boolean), 默认值为 `false`。 | |
+| status | 否 | 辅助 | 当设置为 `1` 时，启用该路由，默认值为 `1`。 | `1` 表示启用，`0` 表示禁用。 |
+| create_time | 否 | 辅助 | epoch 时间戳，单位为秒。如果不指定则自动创建。 | 1602883670 |
+| update_time | 否 | 辅助 | epoch 时间戳，单位为秒。如果不指定则自动创建。 | 1602883670 |
+
+:::note 注意
+
+- 对于同一类参数比如 `uri`与 `uris`，`upstream` 与 `upstream_id`，`host` 与 `hosts`，`remote_addr` 与 `remote_addrs` 等，是不能同时存在，二者只能选择其一。如果同时启用，则会出现异常。
+- 在 `vars` 中，当获取 Cookie 的值时，Cookie name 是**区分大小写字母**的。例如：`var = cookie_x_foo` 与 `var = cookie_X_Foo` 表示不同的 `cookie`。
+
+:::
+
+Route 对象 JSON 配置示例：
```shell
{
@@ -234,207 +281,286 @@ route 对象 json 配置内容：
}
```
-具体示例：
+### 使用示例 {#route-example}
-```shell
-# 创建一个路由
-$ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
-{
- "uri": "/index.html",
- "hosts": ["foo.com", "*.bar.com"],
- "remote_addrs": ["127.0.0.0/8"],
- "methods": ["PUT", "GET"],
- "enable_websocket": true,
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
+- 创建一个路由：
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
+ {
+ "uri": "/index.html",
+ "hosts": ["foo.com", "*.bar.com"],
+ "remote_addrs": ["127.0.0.0/8"],
+ "methods": ["PUT", "GET"],
+ "enable_websocket": true,
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
}
- }
-}'
+ }'
+ ```
-HTTP/1.1 201 Created
-Date: Sat, 31 Aug 2019 01:17:15 GMT
-...
+ ```
+ HTTP/1.1 201 Created
+ Date: Sat, 31 Aug 2019 01:17:15 GMT
+ ...
+ ```
-# 创建一个有效期为 60 秒的路由，过期后自动删除
-$ curl 'http://127.0.0.1:9180/apisix/admin/routes/2?ttl=60' -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
-{
- "uri": "/aa/index.html",
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
+- 创建一个有效期为 60 秒的路由，过期后自动删除：
+
+ ```shell
+ curl 'http://127.0.0.1:9180/apisix/admin/routes/2?ttl=60' \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
+ {
+ "uri": "/aa/index.html",
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
}
- }
-}'
+ }'
+ ```
-HTTP/1.1 201 Created
-Date: Sat, 31 Aug 2019 01:17:15 GMT
-...
+ ```
+ HTTP/1.1 201 Created
+ Date: Sat, 31 Aug 2019 01:17:15 GMT
+ ...
+ ```
+- 在路由中新增一个上游节点：
-# 给路由增加一个 upstream node
-$ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
-{
- "upstream": {
- "nodes": {
- "127.0.0.1:1981": 1
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
+ {
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:1981": 1
+ }
}
- }
-}'
-HTTP/1.1 200 OK
-...
+ }'
+ ```
-执行成功后，upstream nodes 将更新为：
-{
- "127.0.0.1:1980": 1,
- "127.0.0.1:1981": 1
-}
+ ```
+ HTTP/1.1 200 OK
+ ...
+ ```
+ 执行成功后，上游节点将更新为：
-# 给路由更新一个 upstream node 的权重
-$ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
-{
- "upstream": {
- "nodes": {
- "127.0.0.1:1981": 10
- }
+ ```
+ {
+ "127.0.0.1:1980": 1,
+ "127.0.0.1:1981": 1
}
-}'
-HTTP/1.1 200 OK
-...
+ ```
-执行成功后，upstream nodes 将更新为：
-{
- "127.0.0.1:1980": 1,
- "127.0.0.1:1981": 10
-}
+- 更新路由中上游节点的权重：
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
+ {
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:1981": 10
+ }
+ }
+ }'
+ ```
+ ```
+ HTTP/1.1 200 OK
+ ...
+ ```
-# 给路由删除一个 upstream node
-$ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
-{
- "upstream": {
- "nodes": {
- "127.0.0.1:1980": null
+ 执行成功后，上游节点将更新为：
+
+ ```
+ {
+ "127.0.0.1:1980": 1,
+ "127.0.0.1:1981": 10
+ }
+ ```
+
+- 从路由中删除一个上游节点：
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
+ {
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:1980": null
+ }
}
+ }'
+ ```
+
+ ```
+ HTTP/1.1 200 OK
+ ...
+ ```
+
+ 执行成功后，Upstream `nodes` 将更新为：
+
+ ```shell
+ {
+ "127.0.0.1:1981": 10
}
-}'
-HTTP/1.1 200 OK
-...
+ ```
-执行成功后，upstream nodes 将更新为：
-{
- "127.0.0.1:1981": 10
-}
+- 更新路由中的 `methods` 数组
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '{
+ "methods": ["GET", "POST"]
+ }'
+ ```
-# 替换路由的 methods -- 数组
-$ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '{
- "methods": ["GET", "POST"]
-}'
-HTTP/1.1 200 OK
-...
+ ```
+ HTTP/1.1 200 OK
+ ...
+ ```
-执行成功后，methods 将不保留原来的数据，整个更新为：
-["GET", "POST"]
+ 执行成功后，`methods` 将不保留原来的数据，将更新为：
+ ```
+ ["GET", "POST"]
+ ```
-# 替换路由的 upstream nodes -- sub path
-$ curl http://127.0.0.1:9180/apisix/admin/routes/1/upstream/nodes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
-{
- "127.0.0.1:1982": 1
-}'
-HTTP/1.1 200 OK
-...
+- 使用 `sub path` 更新路由中的上游节点：
-执行成功后，nodes 将不保留原来的数据，整个更新为：
-{
- "127.0.0.1:1982": 1
-}
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1/upstream/nodes \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
+ {
+ "127.0.0.1:1982": 1
+ }'
+ ```
+ ```
+ HTTP/1.1 200 OK
+ ...
+ ```
-# 替换路由的 methods -- sub path
-$ curl http://127.0.0.1:9180/apisix/admin/routes/1/methods -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '["POST", "DELETE", "PATCH"]'
-HTTP/1.1 200 OK
-...
+ 执行成功后，`nodes` 将不保留原来的数据，整个更新为：
-执行成功后，methods 将不保留原来的数据，整个更新为：
-["POST", "DELETE", "PATCH"]
+ ```
+ {
+ "127.0.0.1:1982": 1
+ }
+ ```
+- 使用 `sub path` 更新路由中的 `methods`：
-# 禁用路由
-$ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
-{
- "status": 0
-}'
-HTTP/1.1 200 OK
-...
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1/methods \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '["POST", "DELETE", "PATCH"]'
+ ```
-执行成功后，status 将更新为：
-{
- "status": 0
-}
+ ```
+ HTTP/1.1 200 OK
+ ...
+ ```
+ 执行成功后，`methods` 将不保留原来的数据，更新为：
-# 启用路由
-$ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
-{
- "status": 1
-}'
-HTTP/1.1 200 OK
-...
+ ```
+ ["POST", "DELETE", "PATCH"]
+ ```
-执行成功后，status 将更新为：
-{
- "status": 1
-}
+- 禁用路由
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
+ {
+ "status": 0
+ }'
+ ```
-```
+ ```
+ HTTP/1.1 200 OK
+ ...
+ ```
-### 应答参数
+ 执行成功后，`status` 将更新为：
-目前是直接返回与 etcd 交互后的结果。
+ ```
+ {
+ "status": 0
+ }
+ ```
+
+- 启用路由
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
+ {
+ "status": 1
+ }'
+ ```
+
+ ```
+ HTTP/1.1 200 OK
+ ...
+ ```
+
+ 执行成功后，`status` 将更新为：
+
+ ```
+ {
+ "status": 1
+ }
+ ```
+
+### 应答参数 {#route-response-parameters}
-[Back to TOC](#目录)
+目前是直接返回与 etcd 交互后的结果。
## Service
-*地址*：/apisix/admin/services/{id}
+Service 是某类 API 的抽象（也可以理解为一组 Route 的抽象）。它通常与上游服务抽象是一一对应的，`Route` 与 `Service` 之间，通常是 N:1 的关系。
-*说明*：`Service` 是某类 API 的抽象（也可以理解为一组 Route 的抽象）。它通常与上游服务抽象是一一对应的，`Route`
-与 `Service` 之间，通常是 N:1 的关系。
+### 请求地址 {#service-uri}
-### 请求方法
+服务资源请求地址：/apisix/admin/services/{id}
-| 名字 | 请求 uri | 请求 body | 说明 |
-| ------ | ---------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| GET | /apisix/admin/services | 无 | 获取资源列表 |
-| GET | /apisix/admin/services/{id} | 无 | 获取资源 |
-| PUT | /apisix/admin/services/{id} | {...} | 根据 id 创建资源 |
-| POST | /apisix/admin/services | {...} | 创建资源，id 由后台服务自动生成 |
-| DELETE | /apisix/admin/services/{id} | 无 | 删除资源 |
-| PATCH | /apisix/admin/services/{id} | {...} | 标准 PATCH ，修改已有 Service 的部分属性，其他不涉及的属性会原样保留；如果你要删除某个属性，将该属性的值设置为 null 即可删除；特别地，当需要修改属性的值为数组时，该属性将全量更新 |
-| PATCH | /apisix/admin/services/{id}/{path} | {...} | SubPath PATCH，通过 {path} 指定 Service 需要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留 |
+### 请求方法 {#service-request-methods}
-### body 请求参数
+| 名称 | 请求 URI | 请求 body | 描述 |
+| ------ | ---------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| GET | /apisix/admin/services | 无 | 获取资源列表。 |
+| GET | /apisix/admin/services/{id} | 无 | 获取资源。 |
+| PUT | /apisix/admin/services/{id} | {...} | 创建指定 id 资源。 |
+| POST | /apisix/admin/services | {...} | 创建资源，id 由后台服务自动生成。 |
+| DELETE | /apisix/admin/services/{id} | 无 | 删除资源。 |
+| PATCH | /apisix/admin/services/{id} | {...} | 标准 PATCH ，修改已有 Service 的部分属性，其他不涉及的属性会原样保留；如果你要删除某个属性，将该属性的值设置为 null 即可删除；**注意**：当需要修改属性的值为数组时，该属性将全量更新。|
+| PATCH | /apisix/admin/services/{id}/{path} | {...} | SubPath PATCH，通过 {path} 指定 Service 需要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。 |
-| 名字 | 可选项 | 类型 | 说明 | 示例 |
-| ---------------- | ---------------------------------- | -------- | ---------------------------------------------------------------------- | ------------------------------------------------ |
-| plugins | 可选 | Plugin | 详见 [Plugin](terminology/plugin.md) | |
-| upstream | upstream 或 upstream_id 两个选一个 | Upstream | 启用的 Upstream 配置，详见 [Upstream](terminology/upstream.md) | |
-| upstream_id | upstream 或 upstream_id 两个选一个 | Upstream | 启用的 upstream id，详见 [Upstream](terminology/upstream.md) | |
-| name | 可选 | 辅助 | 标识服务名称。 | |
-| desc | 可选 | 辅助 | 服务描述、使用场景等。 | |
-| labels | 可选 | 匹配规则 | 标识附加属性的键值对 | {"version":"v2","build":"16","env":"production"} |
-| enable_websocket | 可选 | 辅助 | 是否启用 `websocket`(boolean), 缺省 `false`. | |
-| hosts | 可选 | 匹配规则 | 非空列表形态的 `host`，表示允许有多个不同 `host`，匹配其中任意一个即可。| ["foo.com", "\*.bar.com"] |
-| create_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 |
-| update_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 |
+### body 请求参数 {#service-request-body-parameters}
-service 对象 json 配置内容：
+| 名称 | 必选项 | 类型 | 描述 | 示例 |
+| ---------------- | ----------------------- | -------- | ---------------------------------------------------------------- | ------------------------------------------------ |
+| plugins | 否 | Plugin | Plugin 配置，请参考 [Plugin](terminology/plugin.md)。 | |
+| upstream | 与 `upstream_id` 二选一。 | Upstream | Upstream 配置，请参考 [Upstream](terminology/upstream.md)。 | |
+| upstream_id | 与 `upstream` 二选一。 | Upstream | 需要使用的 upstream id，请参考 [Upstream](terminology/upstream.md)。| |
+| name | 否 | 辅助 | 服务名称。 | |
+| desc | 否 | 辅助 | 服务描述。 | |
+| labels | 否 | 匹配规则 | 标识附加属性的键值对。 | {"version":"v2","build":"16","env":"production"} |
+| enable_websocket | 否 | 辅助 | `websocket`(boolean) 配置，默认值为 `false`。 | |
+| hosts | 否 | 匹配规则 | 非空列表形态的 `host`，表示允许有多个不同 `host`，匹配其中任意一个即可。| ["foo.com", "\*.bar.com"] |
+| create_time | 否 | 辅助 | epoch 时间戳，单位为秒。如果不指定则自动创建。 | 1602883670 |
+| update_time | 否 | 辅助 | epoch 时间戳，单位为秒。如果不指定则自动创建。 | 1602883670 |
+
+Service 对象 JSON 配置示例：
```shell
{
@@ -449,140 +575,177 @@ service 对象 json 配置内容：
}
```
-具体示例：
+### 使用示例 {#service-example}
-```shell
-# 创建一个 Service
-$ curl http://127.0.0.1:9180/apisix/admin/services/201 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
-{
- "plugins": {
- "limit-count": {
- "count": 2,
- "time_window": 60,
- "rejected_code": 503,
- "key": "remote_addr"
+- 创建一个 Service：
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/services/201 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
+ {
+ "plugins": {
+ "limit-count": {
+ "count": 2,
+ "time_window": 60,
+ "rejected_code": 503,
+ "key": "remote_addr"
+ }
+ },
+ "enable_websocket": true,
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
}
- },
- "enable_websocket": true,
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
+ }'
+ ```
+
+ ```
+ HTTP/1.1 201 Created
+ ...
+ ```
+
+- 在 Service 中添加一个上游节点：
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/services/201 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
+ {
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:1981": 1
+ }
}
- }
-}'
+ }'
+ ```
-# 返回结果
+ ```
+ HTTP/1.1 200 OK
+ ...
+ ```
-HTTP/1.1 201 Created
-...
+ 执行成功后，上游节点将更新为：
+ ```json
+ {
+ "127.0.0.1:1980": 1,
+ "127.0.0.1:1981": 1
+ }
+ ```
-# 给 Service 增加一个 upstream node
-$ curl http://127.0.0.1:9180/apisix/admin/services/201 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
-{
- "upstream": {
- "nodes": {
- "127.0.0.1:1981": 1
+- 更新一个上游节点的权重：
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/services/201 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
+ {
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:1981": 10
+ }
}
- }
-}'
-HTTP/1.1 200 OK
-...
+ }'
+ ```
-执行成功后，upstream nodes 将更新为：
-{
- "127.0.0.1:1980": 1,
- "127.0.0.1:1981": 1
-}
+ ```
+ HTTP/1.1 200 OK
+ ...
+ ```
+ 执行成功后，上游节点将更新为：
-# 给 Service 更新一个 upstream node 的权重
-$ curl http://127.0.0.1:9180/apisix/admin/services/201 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
-{
- "upstream": {
- "nodes": {
- "127.0.0.1:1981": 10
- }
+ ```
+ {
+ "127.0.0.1:1980": 1,
+ "127.0.0.1:1981": 10
}
-}'
-HTTP/1.1 200 OK
-...
+ ```
-执行成功后，upstream nodes 将更新为：
-{
- "127.0.0.1:1980": 1,
- "127.0.0.1:1981": 10
-}
+- 删除 Service 中的一个上游节点：
-
-# 给 Service 删除一个 upstream node
-$ curl http://127.0.0.1:9180/apisix/admin/services/201 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
-{
- "upstream": {
- "nodes": {
- "127.0.0.1:1980": null
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/services/201 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
+ {
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:1980": null
+ }
}
+ }'
+ ```
+
+ ```
+ HTTP/1.1 200 OK
+ ...
+ ```
+
+ 执行成功后，上游节点将更新为：
+
+ ```
+ {
+ "127.0.0.1:1981": 10
}
-}'
-HTTP/1.1 200 OK
-...
+ ```
-执行成功后，upstream nodes 将更新为：
-{
- "127.0.0.1:1981": 10
-}
+- 替换 Service 的上游节点：
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/services/201/upstream/nodes \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
+ {
+ "127.0.0.1:1982": 1
+ }'
+ ```
-# 替换 Service 的 upstream nodes
-$ curl http://127.0.0.1:9180/apisix/admin/services/201/upstream/nodes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
-{
- "127.0.0.1:1982": 1
-}'
-HTTP/1.1 200 OK
-...
+ ```
+ HTTP/1.1 200 OK
+ ...
+ ```
-执行成功后，upstream nodes 将不保留原来的数据，整个更新为：
-{
- "127.0.0.1:1982": 1
-}
+ 执行成功后，上游节点不再保留原来的数据，将更新为：
-```
+ ```
+ {
+ "127.0.0.1:1982": 1
+ }
+ ```
-### 应答参数
+### 应答参数 {#service-response-parameters}
目前是直接返回与 etcd 交互后的结果。
-[Back to TOC](#目录)
-
## Consumer
-*地址*：/apisix/admin/consumers/{username}
+Consumer 是某类服务的消费者，需要与用户认证体系配合才能使用。Consumer 使用 `username` 作为唯一标识，仅支持使用 HTTP `PUT` 方法创建 Consumer。
-*说明*：Consumer 是某类服务的消费者，需与用户认证体系配合才能使用。Consumer 使用 `username` 作为唯一标识，只支持使用 HTTP `PUT` 方法创建 Consumer。
+### 请求地址 {#consumer-uri}
-### 请求方法
+Consumer 资源请求地址：/apisix/admin/consumers/{username}
-| 名字 | 请求 uri | 请求 body | 说明 |
+### 请求方法 {#consumer-request-methods}
+
+| 名称 | 请求 URI | 请求 body | 描述 |
| ------ | ---------------------------- | --------- | ------------ |
-| GET | /apisix/admin/consumers | 无 | 获取资源列表 |
-| GET | /apisix/admin/consumers/{id} | 无 | 获取资源 |
-| PUT | /apisix/admin/consumers | {...} | 创建资源 |
-| DELETE | /apisix/admin/consumers/{id} | 无 | 删除资源 |
+| GET | /apisix/admin/consumers | 无 | 获取资源列表。 |
+| GET | /apisix/admin/consumers/{id} | 无 | 获取资源。 |
+| PUT | /apisix/admin/consumers | {...} | 创建资源。 |
+| DELETE | /apisix/admin/consumers/{id} | 无 | 删除资源。 |
-### body 请求参数
+### body 请求参数 {#consumer-body-request-methods}
-| 名字 | 可选项 | 类型 | 说明 | 示例 |
-| ----------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
-| username | 必需 | 辅助 | Consumer 名称。 | |
-| group_id | 可选 | 辅助 | Consumer Group 名称。 | |
-| plugins | 可选 | Plugin | 该 Consumer 对应的插件配置，它的优先级是最高的：Consumer > Route > Service。对于具体插件配置，可以参考 [Plugins](#plugin) 章节。 | |
-| desc | 可选 | 辅助 | consumer 描述 | |
-| labels | 可选 | 匹配规则 | 标识附加属性的键值对 | {"version":"v2","build":"16","env":"production"} |
-| create_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 |
-| update_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 |
+| 名称 | 必选项 | 类型 | 描述 | 示例值 |
+| ----------- | ----- | ------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| username | 是 | 辅助 | Consumer 名称。 | |
+| group_id | 否 | 辅助 | Consumer Group 名称。 | |
+| plugins | 否 | Plugin | 该 Consumer 对应的插件配置，它的优先级是最高的：Consumer > Route > Service。对于具体插件配置，请可以参考 [Plugins](#plugin)。 | |
+| desc | 否 | 辅助 | consumer 描述。 | |
+| labels | 否 | 匹配规则 | 标识附加属性的键值对。 | {"version":"v2","build":"16","env":"production"} |
+| create_time | 否 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建。 | 1602883670 |
+| update_time | 否 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建。 | 1602883670 |
-consumer 对象 json 配置内容：
+Consumer 对象 JSON 配置示例：
```shell
{
@@ -592,121 +755,123 @@ consumer 对象 json 配置内容：
}
```
-绑定认证插件有些特别，当它需要与 consumer 联合使用时，需要提供用户名、密码等信息；另一方面，当它与 route/service 绑定时，是不需要任何参数的。因为这时候是根据用户请求数据来反向推出用户对应的是哪个 consumer
+当认证插件与 Consumer 一起使用时，需要提供用户名、密码等信息；当认证插件与 Route 或 Service 绑定时，则不需要任何参数，因为此时 APISIX 是根据用户请求数据来判断用户对应的是哪个 Consumer。
-示例：
+:::note 注意
-```shell
-# 创建 Consumer ，指定认证插件 key-auth ，并开启特定插件 limit-count
-$ curl http://127.0.0.1:9180/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
-{
- "username": "jack",
- "plugins": {
- "key-auth": {
- "key": "auth-one"
- },
- "limit-count": {
- "count": 2,
- "time_window": 60,
- "rejected_code": 503,
- "key": "remote_addr"
+从 APISIX v2.2 版本开始，同一个 Consumer 可以绑定多个认证插件。
+
+:::
+
+### 使用示例 {#consumer-example}
+
+- 创建 Consumer，并指定认证插件 `key-auth`，并开启指定插件 `limit-count`：
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/consumers \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
+ {
+ "username": "jack",
+ "plugins": {
+ "key-auth": {
+ "key": "auth-one"
+ },
+ "limit-count": {
+ "count": 2,
+ "time_window": 60,
+ "rejected_code": 503,
+ "key": "remote_addr"
+ }
}
- }
-}'
-HTTP/1.1 200 OK
-Date: Thu, 26 Dec 2019 08:17:49 GMT
-...
+ }'
+ ```
-{"node":{"value":{"username":"jack","plugins":{"key-auth":{"key":"auth-one"},"limit-count":{"time_window":60,"count":2,"rejected_code":503,"key":"remote_addr","policy":"local"}}},"createdIndex":64,"key":"\/apisix\/consumers\/jack","modifiedIndex":64},"prevNode":{"value":"{\"username\":\"jack\",\"plugins\":{\"key-auth\":{\"key\":\"auth-one\"},\"limit-count\":{\"time_window\":60,\"count\":2,\"rejected_code\":503,\"key\":\"remote_addr\",\"policy\":\"local\"}}}","createdIndex":63,"key":"\/ap [...]
-```
+ ```
+ HTTP/1.1 200 OK
+ Date: Thu, 26 Dec 2019 08:17:49 GMT
+ ...
-从 `v2.2` 版本之后，同一个 consumer 可以绑定多个认证插件。
+ {"key":"\/apisix\/consumers\/jack","value":{"username":"jack","update_time":1666260780,"plugins":{"limit-count":{"key_type":"var","count":2,"rejected_code":503,"show_limit_quota_header":true,"time_window":60,"key":"remote_addr","allow_degradation":false,"policy":"local"},"key-auth":{"key":"auth-one"}},"create_time":1666260780}}
+ ```
-### 应答参数
+### 应答参数 {#consumer-response-parameters}
目前是直接返回与 etcd 交互后的结果。
-[Back to TOC](#目录)
-
## Upstream
-*地址*：/apisix/admin/upstreams/{id}
+Upstream 是虚拟主机抽象，对给定的多个服务节点按照配置规则进行负载均衡。Upstream 的地址信息可以直接配置到 `Route`（或 `Service`) 上，当 Upstream 有重复时，需要用“引用”方式避免重复。
-*说明*：Upstream 是虚拟主机抽象，对给定的多个服务节点按照配置规则进行负载均衡。Upstream 的地址信息可以直接配置到 `Route`（或 `Service`) 上，当 Upstream 有重复时，就需要用“引用”方式避免重复了。
+### 请求地址 {#upstream-uri}
-### 请求方法
+Upstream 资源请求地址：/apisix/admin/upstreams/{id}
-| 名字 | 请求 uri | 请求 body | 说明 |
-| ------ | ----------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| GET | /apisix/admin/upstreams | 无 | 获取资源列表 |
-| GET | /apisix/admin/upstreams/{id} | 无 | 获取资源 |
-| PUT | /apisix/admin/upstreams/{id} | {...} | 根据 id 创建资源 |
-| POST | /apisix/admin/upstreams | {...} | 创建资源，id 由后台服务自动生成 |
-| DELETE | /apisix/admin/upstreams/{id} | 无 | 删除资源 |
-| PATCH | /apisix/admin/upstreams/{id} | {...} | 标准 PATCH ，修改已有 Upstream 的部分属性，其他不涉及的属性会原样保留；如果你要删除某个属性，将该属性的值设置为 null 即可删除；特别地，当需要修改属性的值为数组时，该属性将全量更新 |
-| PATCH | /apisix/admin/upstreams/{id}/{path} | {...} | SubPath PATCH，通过 {path} 指定 Upstream 需要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。 |
+### 请求方法 {#upstream-request-methods}
-### body 请求参数
+| 名称 | 请求 URI | 请求 body | 描述 |
+| ------ | ----------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| GET | /apisix/admin/upstreams/{id} | 无 | 获取资源。 |
+| PUT | /apisix/admin/upstreams/{id} | {...} | 创建指定 id 的资源。 |
+| POST | /apisix/admin/upstreams | {...} | 创建资源，id 由后台服务自动生成。 |
+| DELETE | /apisix/admin/upstreams/{id} | 无 | 删除资源。 |
+| PATCH | /apisix/admin/upstreams/{id} | {...} | 标准 PATCH ，修改已有 Upstream 的部分属性，其他不涉及的属性会原样保留；如果需要删除某个属性，可将该属性的值设置为 `null`；**注意**：当需要修改属性的值为数组时，该属性将全量更新。|
+| PATCH | /apisix/admin/upstreams/{id}/{path} | {...} | SubPath PATCH，通过 `{path}` 指定 Upstream 需要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。 |
-APISIX 的 Upstream 除了基本的负载均衡算法选择外，还支持对上游做主被动健康检查、重试等逻辑，具体看下面表格。
+### body 请求参数 {#upstream-body-request-methods}
-| 名字 | 可选项 | 类型 | 说明 | 示例 |
+APISIX 的 Upstream 除了基本的负载均衡算法选择外，还支持对上游做主被动健康检查、重试等逻辑。详细信息如下：
+
+| 名称 | 必选项 | 类型 | 描述 | 示例 |
| -------------- | ---------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
-| type | 必需 | 枚举 | 负载均衡算法 | | |
-| nodes | 必需，不能和 `service_name` 一起用 | Node | 哈希表或数组。当它是哈希表时，内部元素的 key 是上游机器地址列表，格式为`地址 +（可选的）端口`，其中地址部分可以是 IP 也可以是域名，比如 `192.168.1.100:80`、`foo.com:80`等。对于哈希表的情况，如果 key 是 IPv6 地址加端口，则必须用中括号将 IPv6 地址括起来。value 则是节点的权重。当它是数组时，数组中每个元素都是一个哈希表，其中包含 `host`、`weight` 以及可选的 `port`、`priority`。`nodes` 可以为空，这通常用作占位符。客户端命中这样的上游会返回 502。 | `192.168.1.100:80`, `[::1]:80` |
-| service_name | 必需，不能和 `nodes` 一起用 | string | 服务发现时使用的服务名，见[集成服务发现注册中心](./discovery.md) | `a-bootiful-client` |
-| discovery_type | 必需，如果设置了 `service_name` | string | 服务发现类型，见 [集成服务发现注册中心](./discovery.md) | `eureka` |
-| key | 条件必需 | 匹配类型 | 该选项只有类型是 `chash` 才有效。根据 `key` 来查找对应的 node `id`，相同的 `key` 在同一个对象中，永远返回相同 id，目前支持的 Nginx 内置变量有 `uri, server_name, server_addr, request_uri, remote_port, remote_addr, query_string, host, hostname, arg_***`，其中 `arg_***` 是来自 URL 的请求参数，[Nginx 变量列表](http://nginx.org/en/docs/varindex.html) | |
-| checks | 可选 | health_checker | 配置健康检查的参数，详细可参考[health-check](./tutorials/health-check.md) | |
-| retries | 可选 | 整型 | 使用底层的 Nginx 重试机制将请求传递给下一个上游，默认启用重试且次数为后端可用的 node 数量。如果指定了具体重试次数，它将覆盖默认值。`0` 代表不启用重试机制。 | |
-| retry_timeout | 可选 | number | 限制是否继续重试的时间，若之前的请求和重试请求花费太多时间就不再继续重试。`0` 代表不启用重试超时机制。 | |
-| timeout | 可选 | 超时时间对象 | 设置连接、发送消息、接收消息的超时时间，以秒为单位 | |
-| hash_on | 可选 | 辅助 | `hash_on` 支持的类型有 `vars`（Nginx 内置变量），`header`（自定义 header），`cookie`，`consumer`，默认值为 `vars` |
-| name | 可选 | 辅助 | 标识上游服务名称、使用场景等。 | |
-| desc | 可选 | 辅助 | 上游服务描述、使用场景等。 | |
-| pass_host | 可选 | 枚举 | 请求发给上游时的 host 设置选型。 [`pass`，`node`，`rewrite`] 之一，默认是`pass`。`pass`: 将客户端的 host 透传给上游； `node`: 使用 `upstream` node 中配置的 host； `rewrite`: 使用配置项 `upstream_host` 的值。 | |
-| upstream_host | 可选 | 辅助 | 指定上游请求的 host，只在 `pass_host` 配置为 `rewrite` 时有效。 | |
-| scheme | 可选 | 辅助 | 跟上游通信时使用的 scheme。对于 7 层代理，需要是 ['http', 'https', 'grpc', 'grpcs'] 其中的一个。对于 4 层代理，需要是 ['tcp', 'udp', 'tls'] 其中的一个。默认是 'http'。细节见下文。 |
-| labels | 可选 | 匹配规则 | 标识附加属性的键值对 | {"version":"v2","build":"16","env":"production"} |
-| create_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 |
-| update_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 |
-| tls.client_cert | 可选，不能和 `tls.client_cert_id` 一起使用 | https 证书 | 设置跟上游通信时的客户端证书，细节见下文 | |
-| tls.client_key | 可选，不能和 `tls.client_cert_id` 一起使用 | https 证书私钥 | 设置跟上游通信时的客户端私钥，细节见下文 | |
-| tls.client_cert_id | 可选，不能和 `tls.client_cert`、`tls.client_key` 一起使用 | SSL | 设置引用的 ssl id，详见 [SSL](#ssl) | |
-|keepalive_pool.size | 可选 | 辅助 | 动态设置 `keepalive` 指令，细节见下文 |
-|keepalive_pool.idle_timeout | 可选 | 辅助 | 动态设置 `keepalive_timeout` 指令，细节见下文 |
-|keepalive_pool.requests | 可选 | 辅助 | 动态设置 `keepalive_requests` 指令，细节见下文 |
-
-`type` 可以是以下的一种：
-
-- `roundrobin`: 带权重的 roundrobin
-- `chash`: 一致性哈希
-- `ewma`: 选择延迟最小的节点，计算细节参考 https://en.wikipedia.org/wiki/EWMA_chart
-- `least_conn`: 选择 `(active_conn + 1) / weight` 最小的节点。注意这里的 `active connection` 概念跟 Nginx 的相同：它是当前正在被请求使用的连接。
+| type | 是 | 枚举 | 负载均衡算法。 | | |
+| nodes | 是，与 `service_name` 二选一。 | Node | 哈希表或数组。当它是哈希表时，内部元素的 key 是上游机器地址列表，格式为`地址 +（可选的）端口`，其中地址部分可以是 IP 也可以是域名，比如 `192.168.1.100:80`、`foo.com:80`等。对于哈希表的情况，如果 key 是 IPv6 地址加端口，则必须用中括号将 IPv6 地址括起来。`value` 则是节点的权重。当它是数组时，数组中每个元素都是一个哈希表，其中包含 `host`、`weight` 以及可选的 `port`、`priority`。`nodes` 可以为空，这通常用作占位符。客户端命中这样的上游会返回 `502`。 | `192.168.1.100:80`, `[::1]:80` |
+| service_name | 是，与 `nodes` 二选一。 | string | 服务发现时使用的服务名，请参考 [集成服务发现注册中心](./discovery.md)。 | `a-bootiful-client` |
+| discovery_type | 是，与 `service_name` 配合使用。 | string | 服务发现类型，请参考 [集成服务发现注册中心](./discovery.md)。 | `eureka` |
+| key | 条件必需 | 匹配类型 | 该选项只有类型是 `chash` 才有效。根据 `key` 来查找对应的节点 `id`，相同的 `key` 在同一个对象中，则返回相同 id。目前支持的 NGINX 内置变量有 `uri, server_name, server_addr, request_uri, remote_port, remote_addr, query_string, host, hostname, arg_***`，其中 `arg_***` 是来自 URL 的请求参数，详细信息请参考 [NGINX 变量列表](http://nginx.org/en/docs/varindex.html)。 | |
+| checks | 否 | health_checker | 配置健康检查的参数，详细信息请参考 [health-check](health-check.md)。 | |
+| retries | 否 | 整型 | 使用 NGINX 重试机制将请求传递给下一个上游，默认启用重试机制且次数为后端可用的节点数量。如果指定了具体重试次数，它将覆盖默认值。当设置为 `0` 时，表示不启用重试机制。 | |
+| retry_timeout | 否 | number | 限制是否继续重试的时间，若之前的请求和重试请求花费太多时间就不再继续重试。当设置为 `0` 时，表示不启用重试超时机制。 | |
+| timeout | 否 | 超时时间对象 | 设置连接、发送消息、接收消息的超时时间，以秒为单位。 | |
+| hash_on | 否 | 辅助 | `hash_on` 支持的类型有 `vars`（NGINX 内置变量），`header`（自定义 header），`cookie`，`consumer`，默认值为 `vars`。 |
+| name | 否 | 辅助 | 标识上游服务名称、使用场景等。 | |
+| desc | 否 | 辅助 | 上游服务描述、使用场景等。 | |
+| pass_host | 否 | 枚举 | 请求发给上游时的 `host` 设置选型。 [`pass`，`node`，`rewrite`] 之一，默认是 `pass`。`pass`: 将客户端的 host 透传给上游； `node`: 使用 `upstream` node 中配置的 `host`； `rewrite`: 使用配置项 `upstream_host` 的值。 | |
+| upstream_host | 否 | 辅助 | 指定上游请求的 host，只在 `pass_host` 配置为 `rewrite` 时有效。 | |
+| scheme | 否 | 辅助 | 跟上游通信时使用的 scheme。对于 7 层代理，可选值为 [`http`, `https`, `grpc`, `grpcs`]。对于 4 层代理，可选值为 [`tcp`, `udp`, `tls`]。默认值为 `http`，详细信息请参考下文。 |
+| labels | 否 | 匹配规则 | 标识附加属性的键值对。 | {"version":"v2","build":"16","env":"production"} |
+| create_time | 否 | 辅助 | epoch 时间戳，单位为秒。如果不指定则自动创建。 | 1602883670 |
+| update_time | 否 | 辅助 | epoch 时间戳，单位为秒。如果不指定则自动创建。 | 1602883670 |
+| tls.client_cert | 否，不能和 `tls.client_cert_id` 一起使用 | https 证书 | 设置跟上游通信时的客户端证书，详细信息请参考下文。 | |
+| tls.client_key | 否，不能和 `tls.client_cert_id` 一起使用 | https 证书私钥 | 设置跟上游通信时的客户端私钥，详细信息请参考下文。 | |
+| tls.client_cert_id | 否，不能和 `tls.client_cert`、`tls.client_key` 一起使用 | SSL | 设置引用的 SSL id，详见 [SSL](#ssl)。 | |
+|keepalive_pool.size | 否 | 辅助 | 动态设置 `keepalive` 指令，详细信息请参考下文。 |
+|keepalive_pool.idle_timeout | 否 | 辅助 | 动态设置 `keepalive_timeout` 指令，详细信息请参考下文。 |
+|keepalive_pool.requests | 否 | 辅助 | 动态设置 `keepalive_requests` 指令，详细信息请参考下文。 |
+
+`type` 详细信息如下：
+
+- `roundrobin`: 带权重的 Round Robin。
+- `chash`: 一致性哈希。
+- `ewma`: 选择延迟最小的节点，请参考 [EWMA_chart](https://en.wikipedia.org/wiki/EWMA_chart)。
+- `least_conn`: 选择 `(active_conn + 1) / weight` 最小的节点。此处的 `active connection` 概念跟 NGINX 的相同，它是当前正在被请求使用的连接。
- 用户自定义的 balancer，需要可以通过 `require("apisix.balancer.your_balancer")` 来加载。
-`hash_on` 比较复杂，这里专门说明下：
+`hash_on` 详细信息如下：
-1. 设为 `vars` 时，`key` 为必传参数，目前支持的 Nginx 内置变量有 `uri, server_name, server_addr, request_uri, remote_port, remote_addr, query_string, host, hostname, arg_***`，其中 `arg_***` 是来自 URL 的请求参数，[Nginx 变量列表](http://nginx.org/en/docs/varindex.html)
-2. 设为 `header` 时，`key` 为必传参数，其值为自定义的 header name，即 "http\_`key`"
-3. 设为 `cookie` 时，`key` 为必传参数，其值为自定义的 cookie name，即 "cookie\_`key`"。请注意 cookie name 是**区分大小写字母**的。例如："cookie_x_foo" 与 "cookie_X_Foo" 表示不同的 `cookie`。
-4. 设为 `consumer` 时，`key` 不需要设置。此时哈希算法采用的 `key` 为认证通过的 `consumer_name`。
-5. 如果指定的 `hash_on` 和 `key` 获取不到值时，就是用默认值：`remote_addr`。
+- 设为 `vars` 时，`key` 为必传参数，目前支持的 NGINX 内置变量有 `uri, server_name, server_addr, request_uri, remote_port, remote_addr, query_string, host, hostname, arg_***`，其中 `arg_***` 是来自 URL 的请求参数。详细信息请参考 [NGINX 变量列表](http://nginx.org/en/docs/varindex.html)。
+- 设为 `header` 时，`key` 为必传参数，其值为自定义的 Header name，即 "http\_`key`"。
+- 设为 `cookie` 时，`key` 为必传参数，其值为自定义的 cookie name，即 "cookie\_`key`"。请注意 cookie name 是**区分大小写字母**的。例如：`cookie_x_foo` 与 `cookie_X_Foo` 表示不同的 `cookie`。
+- 设为 `consumer` 时，`key` 不需要设置。此时哈希算法采用的 `key` 为认证通过的 `consumer_name`。
+- 如果指定的 `hash_on` 和 `key` 获取不到值时，使用默认值：`remote_addr`。
以下特性需要 APISIX 运行于 [APISIX-Base](./FAQ.md#如何构建-APISIX-Base-环境？)：
-`scheme` 可以设置成 `tls`，表示 "TLS over TCP"。
-
-`tls.client_cert/key` 可以用来跟上游进行 mTLS 通信。
-他们的格式和 SSL 对象的 `cert` 和 `key` 一样。
+- `scheme` 可以设置成 `tls`，表示 `TLS over TCP`。
+- `tls.client_cert/key` 可以用来跟上游进行 mTLS 通信。他们的格式和 SSL 对象的 `cert` 和 `key` 一样。
+- `tls.client_cert_id` 可以用来指定引用的 SSL 对象。只有当 SSL 对象的 `type` 字段为 client 时才能被引用，否则请求会被 APISIX 拒绝。另外，SSL 对象中只有 `cert` 和 `key` 会被使用。
+- `keepalive_pool` 允许 Upstream 有自己单独的连接池。它下属的字段，比如 `requests`，可以用于配置上游连接保持的参数。该特性需要 APISIX 运行于 [APISIX-Base](./FAQ.md#如何构建-apisix-base-环境) 中。
-`tls.client_cert_id` 可以用来指定引用的 SSL 对象。只有当 SSL 对象的 `type` 字段为 client 时才能被引用，否则请求会被 APISIX 拒绝。另外，SSL 对象中只有 `cert`和`key` 会被使用。
-
-`keepalive_pool` 允许 upstream 对象有自己单独的连接池。
-它下属的字段，比如 `requests`，可以用了配置上游连接保持的参数。
-这个特性需要 APISIX 运行于 [APISIX-Base](./FAQ.md#如何构建-apisix-base-环境)。
-
-**upstream 对象 json 配置内容：**
+Upstream 对象 JSON 配置示例：
```shell
{
@@ -729,204 +894,248 @@ APISIX 的 Upstream 除了基本的负载均衡算法选择外，还支持对上
}
```
-**具体示例：**
+### 使用示例 {#upstream-example}
-示例一：创建一个 upstream 并对 `nodes` 的数据做修改
+#### 创建 Upstream 并对 `nodes` 的数据进行修改 {#create-upstream}
-```shell
-# 创建一个 upstream
-$ curl http://127.0.0.1:9180/apisix/admin/upstreams/100 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -i -X PUT -d '
-{
- "type":"roundrobin",
- "nodes":{
- "127.0.0.1:1980": 1
- }
-}'
-HTTP/1.1 201 Created
-...
+1. 创建 Upstream：
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/upstreams/100 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -i -X PUT -d '
+ {
+ "type":"roundrobin",
+ "nodes":{
+ "127.0.0.1:1980": 1
+ }
+ }'
+ ```
-# 给 Upstream 增加一个 node
-$ curl http://127.0.0.1:9180/apisix/admin/upstreams/100 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
-{
- "nodes": {
+ ```
+ HTTP/1.1 201 Created
+ ...
+ ```
+
+2. 在 Upstream 中添加一个节点：
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/upstreams/100 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
+ {
+ "nodes": {
+ "127.0.0.1:1981": 1
+ }
+ }'
+ ```
+
+ ```
+ HTTP/1.1 200 OK
+ ...
+ ```
+
+ 执行成功后，`nodes` 将更新为：
+
+ ```
+ {
+ "127.0.0.1:1980": 1,
"127.0.0.1:1981": 1
}
-}'
-HTTP/1.1 200 OK
-...
+ ```
-执行成功后，nodes 将更新为：
-{
- "127.0.0.1:1980": 1,
- "127.0.0.1:1981": 1
-}
+3. 更新 Upstream 中单个节点的权重：
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/upstreams/100 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
+ {
+ "nodes": {
+ "127.0.0.1:1981": 10
+ }
+ }'
+ ```
+ ```
+ HTTP/1.1 200 OK
+ ...
+ ```
-# 给 Upstream 更新一个 node 的权重
-$ curl http://127.0.0.1:9180/apisix/admin/upstreams/100 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
-{
- "nodes": {
+ 执行成功后，`nodes` 将更新为：
+
+ ```
+ {
+ "127.0.0.1:1980": 1,
"127.0.0.1:1981": 10
}
-}'
-HTTP/1.1 200 OK
-...
+ ```
-执行成功后，nodes 将更新为：
-{
- "127.0.0.1:1980": 1,
- "127.0.0.1:1981": 10
-}
+4. 删除 Upstream 中的一个节点：
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/upstreams/100 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
+ {
+ "nodes": {
+ "127.0.0.1:1980": null
+ }
+ }'
+ ```
-# 给 Upstream 删除一个 node
-$ curl http://127.0.0.1:9180/apisix/admin/upstreams/100 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
-{
- "nodes": {
- "127.0.0.1:1980": null
+ ```
+ HTTP/1.1 200 OK
+ ...
+ ```
+
+ 执行成功后，`nodes` 将更新为：
+
+ ```
+ {
+ "127.0.0.1:1981": 10
}
-}'
-HTTP/1.1 200 OK
-...
+ ```
-执行成功后，nodes 将更新为：
-{
- "127.0.0.1:1981": 10
-}
+5. 更新 Upstream 的 `nodes`：
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/upstreams/100/nodes \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
+ {
+ "127.0.0.1:1982": 1
+ }'
+ ```
-# 替换 Upstream 的 nodes
-$ curl http://127.0.0.1:9180/apisix/admin/upstreams/100/nodes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
-{
- "127.0.0.1:1982": 1
-}'
-HTTP/1.1 200 OK
-...
+ ```
+ HTTP/1.1 200 OK
+ ...
+ ```
-执行成功后，nodes 将不保留原来的数据，整个更新为：
-{
- "127.0.0.1:1982": 1
-}
+ 执行成功后，`nodes` 将不再保留原来的数据：
-```
+ ```
+ {
+ "127.0.0.1:1982": 1
+ }
+ ```
-示例二：将客户端请求代理到上游 `https` 服务
+#### 将客户端请求代理到上游 `https` 服务 {#proxy-https}
-1、创建 route 并配置 upstream 的 scheme 为 `https`。
+1. 创建 Route 并配置 Upstream 的 Scheme 为 `https`：
-```shell
-$ curl -i http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "uri": "/get",
- "upstream": {
- "type": "roundrobin",
- "scheme": "https",
- "nodes": {
- "httpbin.org:443": 1
+ ```shell
+ curl -i http://127.0.0.1:9180/apisix/admin/routes/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "uri": "/get",
+ "upstream": {
+ "type": "roundrobin",
+ "scheme": "https",
+ "nodes": {
+ "httpbin.org:443": 1
+ }
}
- }
-}'
-```
+ }'
+ ```
-执行成功后，请求与上游通信时的 scheme 将为 `https`。
+ 执行成功后，请求与上游通信时的 Scheme 将为 `https`。
-2、 发送请求进行测试。
+2. 发送请求进行测试：
-```shell
-$ curl http://127.0.0.1:9080/get
-{
- "args": {},
- "headers": {
- "Accept": "*/*",
- "Host": "127.0.0.1",
- "User-Agent": "curl/7.29.0",
- "X-Amzn-Trace-Id": "Root=1-6058324a-0e898a7f04a5e95b526bb183",
- "X-Forwarded-Host": "127.0.0.1"
- },
- "origin": "127.0.0.1",
- "url": "https://127.0.0.1/get"
-}
-```
+ ```shell
+ curl http://127.0.0.1:9080/get
+ ```
+
+ ```shell
+ {
+ "args": {},
+ "headers": {
+ "Accept": "*/*",
+ "Host": "127.0.0.1",
+ "User-Agent": "curl/7.29.0",
+ "X-Amzn-Trace-Id": "Root=1-6058324a-0e898a7f04a5e95b526bb183",
+ "X-Forwarded-Host": "127.0.0.1"
+ },
+ "origin": "127.0.0.1",
+ "url": "https://127.0.0.1/get"
+ }
+ ```
-请求成功，表示代理上游 `https` 生效了。
+ 请求成功，表示代理上游 `https` 生效了。
-**注意：**
+ :::tip 提示
-节点可以配置自己的优先级。只有在高优先级的节点不可用或者尝试过，才会访问一个低优先级的节点。
+ 每个节点均可以配置优先级，只有在高优先级的节点不可用或者尝试过，才会访问一个低优先级的节点。
-由于默认的优先级是 0，我们可以给一些节点配置负数的优先级来作为备份。
-举个例子：
+ :::
-```json
-{
- "uri": "/hello",
- "upstream": {
- "type": "roundrobin",
- "nodes": [
- {"host": "127.0.0.1", "port": 1980, "weight": 2000},
- {"host": "127.0.0.1", "port": 1981, "weight": 1, "priority": -1}
- ],
- "checks": {
- "active": {
- "http_path": "/status",
- "healthy": {
- "interval": 1,
- "successes": 1
- },
- "unhealthy": {
- "interval": 1,
- "http_failures": 1
+ 由于上游节点的默认优先级是 `0`，你可以将一些节点的优先级设置为负数，让其作为备份节点。例如：
+
+ ```JSON
+ {
+ "uri": "/hello",
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": [
+ {"host": "127.0.0.1", "port": 1980, "weight": 2000},
+ {"host": "127.0.0.1", "port": 1981, "weight": 1, "priority": -1}
+ ],
+ "checks": {
+ "active": {
+ "http_path": "/status",
+ "healthy": {
+ "interval": 1,
+ "successes": 1
+ },
+ "unhealthy": {
+ "interval": 1,
+ "http_failures": 1
+ }
}
}
}
}
-}
-```
+ ```
-节点 `127.0.0.2` 只有在 `127.0.0.1` 不可用或者尝试过之后才会被访问。
-所以它是 `127.0.0.1` 的备份。
+ 节点 `127.0.0.2` 只有在 `127.0.0.1` 不可用或者尝试过之后才会被访问，因此它是 `127.0.0.1` 的备份。
-### 应答参数
+### 应答参数 {#upstream-response-parameters}
目前是直接返回与 etcd 交互后的结果。
-[Back to TOC](#目录)
-
## SSL
-*地址*：/apisix/admin/ssls/{id}
+你可以使用该资源创建 SSL 证书。
-*说明*：SSL.
+### 请求地址 {#ssl-uri}
-### 请求方法
+SSL 资源请求地址：/apisix/admin/ssls/{id}
-| 名字 | 请求 uri | 请求 body | 说明 |
-| ------ | ---------------------- | --------- | ------------------------------- |
-| GET | /apisix/admin/ssls | 无 | 获取资源列表 |
-| GET | /apisix/admin/ssls/{id} | 无 | 获取资源 |
-| PUT | /apisix/admin/ssls/{id} | {...} | 根据 id 创建资源 |
-| POST | /apisix/admin/ssls | {...} | 创建资源，id 由后台服务自动生成 |
-| DELETE | /apisix/admin/ssls/{id} | 无 | 删除资源 |
+### 请求方法 {#ssl-request-methods}
-### body 请求参数
+| 名称 | 请求 URI | 请求 body | 描述 |
+| ------ | ----------------------- | --------- | ------------------------------- |
+| GET | /apisix/admin/ssls | 无 | 获取资源列表。 |
+| GET | /apisix/admin/ssls/{id} | 无 | 获取资源。 |
+| PUT | /apisix/admin/ssls/{id} | {...} | 创建指定 id 的资源。 |
+| POST | /apisix/admin/ssls | {...} | 创建资源，id 由后台服务自动生成。 |
+| DELETE | /apisix/admin/ssls/{id} | 无 | 删除资源。 |
-| 名字 | 可选项 | 类型 | 说明 | 示例 |
+### body 请求参数 {#ssl-body-request-methods}
+
+| 名称 | 必选项 | 类型 | 描述 | 示例 |
| ----------- | ------ | -------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
-| cert | 必需 | 证书 | https 证书 | |
-| key | 必需 | 私钥 | https 证书私钥 | |
-| certs | 可选 | 证书字符串数组 | 当你想给同一个域名配置多个证书时，除了第一个证书需要通过 cert 传递外，剩下的证书可以通过该参数传递上来 | |
-| keys | 可选 | 私钥字符串数组 | certs 对应的证书私钥，注意要跟 certs 一一对应 | |
-| client.ca | 可选 | 证书 | 设置将用于客户端证书校验的 CA 证书。该特性需要 OpenResty 1.19+ | |
-| client.depth | 可选 | 辅助 | 设置客户端证书校验的深度，默认为 1。该特性需要 OpenResty 1.19+ | |
-| snis | 必需 | 匹配规则 | 非空数组形式，可以匹配多个 SNI | |
-| labels | 可选 | 匹配规则 | 标识附加属性的键值对 | {"version":"v2","build":"16","env":"production"} |
-| create_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 |
-| update_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 |
-| type | 可选 | 辅助 | 标识证书的类型，缺省为 `server`。 | `client` 表示证书是客户端证书，APISIX 访问上游时使用；`server` 表示证书是服务端证书，APISIX 验证客户端请求时使用 |
-| status | 可选 | 辅助 | 是否启用此 SSL，缺省 `1`。 | `1` 表示启用，`0` 表示禁用 |
-
-ssl 对象 json 配置内容：
+| cert | 是 | 证书 | HTTP 证书。 | |
+| key | 是 | 私钥 | HTTPS 证书私钥 | |
+| certs | 否 | 证书字符串数组 | 当你想给同一个域名配置多个证书时，除了第一个证书需要通过 `cert` 传递外，剩下的证书可以通过该参数传递上来。 | |
+| keys | 否 | 私钥字符串数组 | `certs` 对应的证书私钥，需要与 `certs` 一一对应。 | |
+| client.ca | 否 | 证书 | 设置将用于客户端证书校验的 `CA` 证书。该特性需要 OpenResty 为 1.19 及以上版本。 | |
+| client.depth | 否 | 辅助 | 设置客户端证书校验的深度，默认为 1。该特性需要 OpenResty 为 1.19 及以上版本。 | |
+| snis | 是 | 匹配规则 | 非空数组形式，可以匹配多个 SNI。 | |
+| labels | 否 | 匹配规则 | 标识附加属性的键值对。 | {"version":"v2","build":"16","env":"production"} |
+| create_time | 否 | 辅助 | epoch 时间戳，单位为秒。如果不指定则自动创建。 | 1602883670 |
+| update_time | 否 | 辅助 | epoch 时间戳，单位为秒。如果不指定则自动创建。 | 1602883670 |
+| type | 否 | 辅助 | 标识证书的类型，默认值为 `server`。 | `client` 表示证书是客户端证书，APISIX 访问上游时使用；`server` 表示证书是服务端证书，APISIX 验证客户端请求时使用。 |
+| status | 否 | 辅助 | 当设置为 `1` 时，启用此 SSL，默认值为 `1`。 | `1` 表示启用，`0` 表示禁用 |
+
+SSL 对象 JSON 配置示例：
```shell
{
@@ -937,205 +1146,210 @@ ssl 对象 json 配置内容：
}
```
-更多的配置示例见 [证书](./certificate.md)。
+更多的配置示例，请参考[证书](./certificate.md)。
-[Back to TOC](#目录)
+## Global Rules
-## Global Rule
+Global Rule 可以设置全局运行的插件，设置为全局规则的插件将在所有路由级别的插件之前优先运行。
-*地址*：/apisix/admin/global_rules/{id}
+### 请求地址 {#global-rule-uri}
-*说明*：设置全局运行的插件。这一类插件在所有路由级别的插件之前优先运行。
+Global Rule 资源请求地址：/apisix/admin/global_rules/{id}
-### 请求方法
+### 请求方法 {#global-rule-request-methods}
-| 名字 | 请求 uri | 请求 body | 说明 |
+| 名称 | 请求 URI | 请求 body | 描述 |
| ------ | -------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| GET | /apisix/admin/global_rules | 无 | 获取资源列表 |
-| GET | /apisix/admin/global_rules/{id} | 无 | 获取资源 |
-| PUT | /apisix/admin/global_rules/{id} | {...} | 根据 id 创建资源 |
-| DELETE | /apisix/admin/global_rules/{id} | 无 | 删除资源 |
-| PATCH | /apisix/admin/global_rules/{id} | {...} | 标准 PATCH ，修改已有 Global Rule 的部分属性，其他不涉及的属性会原样保留；如果你要删除某个属性，将该属性的值设置为 null 即可删除；特别地，当需要修改属性的值为数组时，该属性将全量更新 |
-| PATCH | /apisix/admin/global_rules/{id}/{path} | {...} | SubPath PATCH，通过 {path} 指定 Global Rule 要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。 |
-
-### body 请求参数
+| GET | /apisix/admin/global_rules | 无 | 获取资源列表。 |
+| GET | /apisix/admin/global_rules/{id} | 无 | 获取资源。 |
+| PUT | /apisix/admin/global_rules/{id} | {...} | 将创建指定 id 的资源。 |
+| DELETE | /apisix/admin/global_rules/{id} | 无 | 删除资源。 |
+| PATCH | /apisix/admin/global_rules/{id} | {...} | 标准 PATCH ，修改已有 Global Rule 的部分属性，其他不涉及的属性会原样保留；如果你要删除某个属性，将该属性的值设置为 null 即可删除；**注意**：当需要修改属性的值为数组时，该属性将全量更新。 |
+| PATCH | /apisix/admin/global_rules/{id}/{path} | {...} | SubPath PATCH，通过 `{path}` 指定 Global Rule 要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。 |
-| 名字 | 可选项 | 类型 | 说明 | 示例 |
-| ----------- | ------ | ------ | --------------------------------------------- | ---------- |
-| plugins | 必需 | Plugin | 详见 [Plugin](terminology/plugin.md) | |
-| create_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 |
-| update_time | 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 | 1602883670 |
+### body 请求参数 {#global-rule-body-request-parameters}
-[Back to TOC](#目录)
+| 名称 | 必选项 | 类型 | 描述 | 示例值 |
+| ----------- | ------ | ------ | ------------------------------------------------- | ---------- |
+| plugins | 是 | Plugin | 插件配置。详细信息请参考 [Plugin](terminology/plugin.md)。 | |
+| create_time | 否 | 辅助 | epoch 时间戳，单位为秒，如果不指定则自动创建。 | 1602883670 |
+| update_time | 否 | 辅助 | epoch 时间戳，单位为秒，如果不指定则自动创建。 | 1602883670 |
## Consumer Group
-*地址*：/apisix/admin/consumer_groups/{id}
+你可以使用该资源配置一组可以在 Consumer 间复用的插件。
-*说明*：配置一组可以在 Consumer 间复用的插件。
+### 请求地址 {#consumer-group-uri}
-### 请求方法
+Consumer Group 资源请求地址：/apisix/admin/consumer_groups/{id}
-| 名字 | 请求 uri | 请求 body | 说明 |
-| ------ | ---------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| GET | /apisix/admin/consumer_groups | 无 | 获取资源列表 |
-| GET | /apisix/admin/consumer_groups/{id} | 无 | 获取资源 |
-| PUT | /apisix/admin/consumer_groups/{id} | {...} | 根据 id 创建资源 |
-| DELETE | /apisix/admin/consumer_groups/{id} | 无 | 删除资源 |
-| PATCH | /apisix/admin/consumer_groups/{id} | {...} | 标准 PATCH ，修改已有 Consumer Group 的部分属性，其他不涉及的属性会原样保留；如果你要删除某个属性，将该属性的值设置为 null 即可删除；特别地，当需要修改属性的值为数组时，该属性将全量更新 |
-| PATCH | /apisix/admin/consumer_groups/{id}/{path} | {...} | SubPath PATCH，通过 {path} 指定 Consumer Group 要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。 |
+### 请求方法 {#consumer-group-request-methods}
-### body 请求参数
+| 名称 | 请求 URI | 请求 body | 描述 |
+| ------ | ----------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| GET | /apisix/admin/consumer_groups | 无 | 获取资源列表。 |
+| GET | /apisix/admin/consumer_groups/{id} | 无 | 获取资源。 |
+| PUT | /apisix/admin/consumer_groups/{id} | {...} | 将创建指定 id 的资源。 |
+| DELETE | /apisix/admin/consumer_groups/{id} | 无 | 删除资源。 |
+| PATCH | /apisix/admin/consumer_groups/{id} | {...} | 标准 PATCH，修改已有 Consumer Group 的部分属性，其他不涉及的属性会原样保留；如果你要删除某个属性，将该属性的值设置为 null 即可删除；**注意**：当需要修改属性的值为数组时，该属性将全量更新。 |
+| PATCH | /apisix/admin/consumer_groups/{id}/{path} | {...} | SubPath PATCH，通过 `{path}` 指定 Consumer Group 要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。 |
-| 名字 | 可选项 | 类型 | 说明 | 示例 |
-|---------|---------|----|-----------|----|
-|plugins | 必需 |Plugin| 详见 [Plugin](terminology/plugin.md) ||
-|desc | 可选 | 辅助 | 标识描述、使用场景等 |customer xxxx|
-|labels | 可选 | 辅助 | 标识附加属性的键值对 |{"version":"v2","build":"16","env":"production"}|
-|create_time| 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 |1602883670|
-|update_time| 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 |1602883670|
+### body 请求参数 {#consumer-group-body-request-parameters}
-[Back to TOC](#目录)
+| 名称 | 必选项 | 类型 | 描述 | 示例值 |
+|--------- |--------- |------|----------------------------------------------- |------|
+|plugins | 是 |Plugin| 插件配置。详细信息请参考 [Plugin](terminology/plugin.md)。 | |
+|desc | 否 | 辅助 | 标识描述、使用场景等。 | Consumer 测试。|
+|labels | 否 | 辅助 | 标识附加属性的键值对。 |{"version":"v2","build":"16","env":"production"}|
+|create_time| 否 | 辅助 | epoch 时间戳，单位为秒，如果不指定则自动创建。 |1602883670|
+|update_time| 否 | 辅助 | epoch 时间戳，单位为秒，如果不指定则自动创建。 |1602883670|
## Plugin Config
-*地址*：/apisix/admin/plugin_configs/{id}
+你可以使用 Plugin Config 资源创建一组可以在路由间复用的插件。
-*说明*：配置一组可以在路由间复用的插件。
+### 请求地址 {#plugin-config-uri}
-### 请求方法
+Plugin Config 资源请求地址：/apisix/admin/plugin_configs/{id}
-| 名字 | 请求 uri | 请求 body | 说明 |
+### 请求方法 {#plugin-config-request-methods}
+
+| 名称 | 请求 URI | 请求 body | 描述 |
| ------ | ---------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| GET | /apisix/admin/plugin_configs | 无 | 获取资源列表 |
-| GET | /apisix/admin/plugin_configs/{id} | 无 | 获取资源 |
-| PUT | /apisix/admin/plugin_configs/{id} | {...} | 根据 id 创建资源 |
-| DELETE | /apisix/admin/plugin_configs/{id} | 无 | 删除资源 |
-| PATCH | /apisix/admin/plugin_configs/{id} | {...} | 标准 PATCH ，修改已有 Plugin Config 的部分属性，其他不涉及的属性会原样保留；如果你要删除某个属性，将该属性的值设置为 null 即可删除；特别地，当需要修改属性的值为数组时，该属性将全量更新 |
+| GET | /apisix/admin/plugin_configs | 无 | 获取资源列表。 |
+| GET | /apisix/admin/plugin_configs/{id} | 无 | 获取资源。 |
+| PUT | /apisix/admin/plugin_configs/{id} | {...} | 根据 id 创建资源。 |
+| DELETE | /apisix/admin/plugin_configs/{id} | 无 | 删除资源。 |
+| PATCH | /apisix/admin/plugin_configs/{id} | {...} | 标准 PATCH ，修改已有 Plugin Config 的部分属性，其他不涉及的属性会原样保留；如果你要删除某个属性，将该属性的值设置为 null 即可删除；**注意**：当需要修改属性的值为数组时，该属性将全量更新。 |
| PATCH | /apisix/admin/plugin_configs/{id}/{path} | {...} | SubPath PATCH，通过 {path} 指定 Plugin Config 要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。 |
-### body 请求参数
-
-| 名字 | 可选项 | 类型 | 说明 | 示例 |
-|---------|---------|----|-----------|----|
-|plugins | 必需 |Plugin| 详见 [Plugin](terminology/plugin.md) ||
-|desc | 可选 | 辅助 | 标识描述、使用场景等 |customer xxxx|
-|labels | 可选 | 辅助 | 标识附加属性的键值对 |{"version":"v2","build":"16","env":"production"}|
-|create_time| 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 |1602883670|
-|update_time| 可选 | 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建 |1602883670|
+### body 请求参数 {#plugin-config-body-request-parameters}
-[Back to TOC](#目录)
+| 名称 | 必选项 | 类型 | 描述 | 示例值 |
+|--------- |---------|----|-----------|----|
+|plugins | 是 |Plugin| 更多信息请参考 [Plugin](terminology/plugin.md)。||
+|desc | 否 | 辅助 | 标识描述、使用场景等。 |customer xxxx|
+|labels | 否 | 辅助 | 标识附加属性的键值对。 |{"version":"v2","build":"16","env":"production"}|
+|create_time| 否 | 辅助 | epoch 时间戳，单位为秒，如果不指定则自动创建。 |1602883670|
+|update_time| 否 | 辅助 | epoch 时间戳，单位为秒，如果不指定则自动创建。 |1602883670|
## Plugin Metadata
-*地址*：/apisix/admin/plugin_metadata/{plugin_name}
+你可以使用 Plugin Metadata 资源配置插件元数据。
-*说明*: 插件元数据。
+### 请求地址 {#plugin-metadata-uri}
-### 请求方法
+Plugin Config 资源请求地址：/apisix/admin/plugin_metadata/{plugin_name}
-| Method | 请求 URI | 请求 body | 说明 |
+### 请求方法 {#plugin-metadata-request-methods}
+
+| Method | 请求 URI | 请求 body | 描述 |
| ------ | ------------------------------------------- | --------- | ------------------------- |
-| GET | /apisix/admin/plugin_metadata/{plugin_name} | 无 | 获取资源 |
-| PUT | /apisix/admin/plugin_metadata/{plugin_name} | {...} | 根据 plugin name 创建资源 |
-| DELETE | /apisix/admin/plugin_metadata/{plugin_name} | 无 | 删除资源 |
+| GET | /apisix/admin/plugin_metadata/{plugin_name} | 无 | 获取资源。 |
+| PUT | /apisix/admin/plugin_metadata/{plugin_name} | {...} | 根据 `plugin name` 创建资源。 |
+| DELETE | /apisix/admin/plugin_metadata/{plugin_name} | 无 | 删除资源。 |
-### body 请求参数
+### body 请求参数 {#plugin-metadata-body-request-parameters}
-一个根据插件 ({plugin_name}) 的 `metadata_schema` 定义的数据结构的 json object 。
+根据插件 (`{plugin_name}`) 的 `metadata_schema` 定义的数据结构的 JSON 对象。
-例子：
+### 使用示例 {#plugin-metadata-example}
```shell
-$ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/example-plugin -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -i -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/example-plugin \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -i -X PUT -d '
{
"skey": "val",
"ikey": 1
}'
+```
+
+```
HTTP/1.1 201 Created
Date: Thu, 26 Dec 2019 04:19:34 GMT
Content-Type: text/plain
```
-[Back to TOC](#目录)
-
## Plugin
-*地址*：/apisix/admin/plugins/{plugin_name}
+你可以通过该资源获取插件列表。
-*说明*: 插件
+### 请求地址 {#plugin-uri}
-### 请求方法
+Plugin 资源请求地址：/apisix/admin/plugins/{plugin_name}
-| 名字 | 请求 uri | 请求 body | 说明 |
-| ----------- | ----------------------------------- | ---------- | ------------- |
-| GET | /apisix/admin/plugins/list | 无 | 获取资源列表 |
-| GET | /apisix/admin/plugins/{plugin_name} | 无 | 获取资源 |
-| GET | /apisix/admin/plugins?all=true | 无 | 获取所有插件的所有属性 |
+### 请求方法 {#plugin-request-methods}
-### body 请求参数
+| 名称 | 请求 URI | 请求 body | 描述 |
+| ----------- | ----------------------------------- | ---------- | ------------- |
+| GET | /apisix/admin/plugins/list | 无 | 获取资源列表。 |
+| GET | /apisix/admin/plugins/{plugin_name} | 无 | 获取资源。 |
+| GET | /apisix/admin/plugins?all=true | 无 | 获取所有插件的所有属性。 |
+| GET | /apisix/admin/plugins?all=true&subsystem=stream| 无 | 获取所有 Stream 插件的属性。|
-获取插件 ({plugin_name}) 数据结构的 json object 。
+### 使用示例 {#plugin-example}
-例子：
+获取插件 (`{plugin_name}`) 数据结构的 JSON 对象。
-```shell
-$ curl "http://127.0.0.1:9180/apisix/admin/plugins/list" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
-["zipkin","request-id",...]
+- 获取插件列表
-$ curl "http://127.0.0.1:9180/apisix/admin/plugins/key-auth" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
-{"$comment":"this is a mark for our injected plugin schema","properties":{"header":{"default":"apikey","type":"string"},"hide_credentials":{"default":false,"type":"boolean"},"_meta":{"properties":{"filter":{"type":"array","description":"filter determines whether the plugin needs to be executed at runtime"},"disable":{"type":"boolean"},"error_response":{"oneOf":[{"type":"string"},{"type":"object"}]},"priority":{"type":"integer","description":"priority of plugins by customized order"}},"ty [...]
-```
+ ```shell
+ curl "http://127.0.0.1:9180/apisix/admin/plugins/list" \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
+ ```
-*地址*：/apisix/admin/plugins?all=true
+ ```shell
+ ["zipkin","request-id",...]
+ ```
-*说明*: 所有插件的所有属性，每个插件包括 `name`, `priority`, `type`, `schema`, `consumer_schema` 和 `version`。
+- 获取指定插件的属性
-默认情况下，这个接口只返回 http 插件。如果你需要 stream 插件，需要用 `/apisix/admin/plugins?all=true&subsystem=stream`。
+ ```shell
+ curl "http://127.0.0.1:9180/apisix/admin/plugins/key-auth" \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
+ ```
-### 请求方法
+ ```json
+ {"$comment":"this is a mark for our injected plugin schema","properties":{"header":{"default":"apikey","type":"string"},"hide_credentials":{"default":false,"type":"boolean"},"_meta":{"properties":{"filter":{"type":"array","description":"filter determines whether the plugin needs to be executed at runtime"},"disable":{"type":"boolean"},"error_response":{"oneOf":[{"type":"string"},{"type":"object"}]},"priority":{"type":"integer","description":"priority of plugins by customized order"}} [...]
+ ```
-| Method | 请求 URI | 请求 body | 说明 |
-| ------ | ------------------------------ | --------- | -------- |
-| GET | /apisix/admin/plugins?all=true | 无 | 获取资源 |
+:::tip
-### 请求参数
+你可以使用 `/apisix/admin/plugins?all=true` 接口获取所有插件的所有属性，每个插件包括 `name`，`priority`，`type`，`schema`，`consumer_schema` 和 `version`。
-| 名称 | 说明 | 默认 |
-| ---- | ----------------------- | -----|
-| subsystem | 插件所属的子系统 | http |
+默认情况下，该接口只返回 HTTP 插件。如果你需要获取 Stream 插件，需要使用 `/apisix/admin/plugins?all=true&subsystem=stream`。
-[Back to TOC](#目录)
+:::
## Stream Route
-*API*：/apisix/admin/stream_routes/{id}
+Stream Route 是用于 TCP/UDP 动态代理的路由。详细信息请参考 [TCP/UDP 动态代理](./stream-proxy.md)。
-*Description*：Stream Route 是用于 TCP/UDP 动态代理的路由。参见 [TCP/UDP 动态代理](./stream-proxy.md) 一节。
+### 请求地址 {#stream-route-uri}
-### 请求方法
+Plugin 资源请求地址：/apisix/admin/stream_routes/{id}
-| 名字 | 请求 uri | 请求 body | 说明 |
-| ------ | -------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| GET | /apisix/admin/stream_routes | 无 | 获取资源列表 |
-| GET | /apisix/admin/stream_routes/{id} | 无 | 获取资源 |
-| PUT | /apisix/admin/stream_routes/{id} | {...} | 根据 id 创建资源 |
-| POST | /apisix/admin/stream_routes | {...} | 创建资源，id 由后台服务自动生成 |
-| DELETE | /apisix/admin/stream_routes/{id} | 无 | 删除资源 |
+### 请求方法 {#stream-route-request-methods}
-### body 请求参数
+| 名称 | 请求 URI | 请求 body | 描述 |
+| ------ | --------------------------------- | --------- | -------------------------------------------------- |
+| GET | /apisix/admin/stream_routes | 无 | 获取资源列表。 |
+| GET | /apisix/admin/stream_routes/{id} | 无 | 获取资源。 |
+| PUT | /apisix/admin/stream_routes/{id} | {...} | 创建指定 id 的资源。 |
+| POST | /apisix/admin/stream_routes | {...} | 创建资源，id 由后台服务自动生成。 |
+| DELETE | /apisix/admin/stream_routes/{id} | 无 | 删除资源。 |
-| 名字 | 可选项 | 类型 | 说明 | 示例 |
-| ---------------- | ------| -------- | ------| -----|
-| upstream | 可选 | Upstream | 启用的 Upstream 配置，详见 [Upstream](terminology/upstream.md) | |
-| upstream_id | 可选 | Upstream | 启用的 upstream id，详见 [Upstream](terminology/upstream.md) | |
-| remote_addr | 可选 | IP/CIDR | 过滤选项：如果客户端 IP 匹配，则转发到上游 | "127.0.0.1/32" 或 "127.0.0.1" |
-| server_addr | 可选 | IP/CIDR | 过滤选项：如果 APISIX 服务器 IP 与 server_addr 匹配，则转发到上游 | "127.0.0.1/32" 或 "127.0.0.1" |
-| server_port | 可选 | 整数 | 过滤选项：如果 APISIX 服务器 port 与 server_port 匹配，则转发到上游 | 9090 |
-| sni | 可选 | Host | 服务器名称指示 | "test.com" |
-| protocol.name | 可选 | 字符串 | xRPC 框架代理的协议的名称 | "redis" |
-| protocol.conf | 可选 | 配置 | 协议特定的配置 | |
+### body 请求参数{#stream-route-body-request-parameters}
-点击 [此处](./stream-proxy.md#more-route-match-options)，了解更多有关过滤器如何工作的信息。
+| 名称 | 必选项 | 类型 | 描述 | 示例值 |
+| ---------------- | ------| -------- | ------------------------------------------------------------------------------| ------ |
+| upstream | 否 | Upstream | Upstream 配置，详细信息请参考 [Upstream](terminology/upstream.md)。 | |
+| upstream_id | 否 | Upstream | 需要使用的 Upstream id，详细信息请 [Upstream](terminology/upstream.md)。 | |
+| remote_addr | 否 | IP/CIDR | 过滤选项：如果客户端 IP 匹配，则转发到上游 | "127.0.0.1/32" 或 "127.0.0.1" |
+| server_addr | 否 | IP/CIDR | 过滤选项：如果 APISIX 服务器的 IP 与 `server_addr` 匹配，则转发到上游。 | "127.0.0.1/32" 或 "127.0.0.1" |
+| server_port | 否 | 整数 | 过滤选项：如果 APISIX 服务器的端口 与 `server_port` 匹配，则转发到上游。 | 9090 |
+| sni | 否 | Host | 服务器名称。 | "test.com" |
+| protocol.name | 否 | 字符串 | xRPC 框架代理的协议的名称。 | "redis" |
+| protocol.conf | 否 | 配置 | 协议特定的配置。 | |
-[Back to TOC](#目录)
+你可以查看 [Stream Proxy](./stream-proxy.md#更多-route-匹配选项) 了解更多过滤器的信息。