SylviaBABY commented on code in PR #8145: URL: https://github.com/apache/apisix/pull/8145#discussion_r1002621662
########## docs/zh/latest/admin-api.md: ########## @@ -23,76 +31,119 @@ title: Admin API ## 描述 -Admin API 是为 Apache APISIX 服务的一组 API，我们可以将参数传递给 Admin API 以控制 APISIX 节点。更好地了解其工作原理，请参阅 [Architecture Design](./architecture-design/apisix.md) 中的文档。 +Admid 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)。 Review Comment: ```suggestion 你可以通过 Admin API 来获取、创建、更新以及删除资源。同时得益于 APISIX 的热加载能力，资源配置完成后 APISIX 将会自动更新配置，无需重启服务。如果你想要了解其工作原理，请参考 [Architecture Design](./architecture-design/apisix.md)。 ``` ########## docs/zh/latest/admin-api.md: ########## @@ -729,204 +894,246 @@ APISIX 的 Upstream 除了基本的负载均衡算法选择外，还支持对上 } ``` -**具体示例：** +### 使用示例 -示例一：创建一个 upstream 并对 `nodes` 的数据做修改 +#### 创建一个 Upstream 并对 `nodes` 的数据做修改 Review Comment: ```suggestion #### 创建一个 Upstream 并对 `nodes` 的数据进行修改 ``` ########## docs/zh/latest/admin-api.md: ########## @@ -592,121 +755,123 @@ consumer 对象 json 配置内容： } ``` -绑定认证插件有些特别，当它需要与 consumer 联合使用时，需要提供用户名、密码等信息；另一方面，当它与 route/service 绑定时，是不需要任何参数的。因为这时候是根据用户请求数据来反向推出用户对应的是哪个 consumer +当认证插件与 Consumer 一起使用时，需要提供用户名、密码等信息；当认证插件与 Route 或 Service 绑定时，则不需要任何参数，因为此时是根据用户请求数据判断用户对应的是哪个 Consumer。 -示例： +### 使用示例 -```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" +- 创建 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":"\/apisix\/consumers\/jack","modifiedIndex":63}} -``` + ``` + HTTP/1.1 200 OK + Date: Thu, 26 Dec 2019 08:17:49 GMT + ... + + {"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}} + ``` + +:::note 注意 -从 `v2.2` 版本之后，同一个 consumer 可以绑定多个认证插件。 +自 APISIX v2.2 及以上版本，同一个 Consumer 可以绑定多个认证插件。 Review Comment: ```suggestion 从 APISIX v2.2 版本开始，同一个 Consumer 可以绑定多个认证插件。 ``` ########## docs/zh/latest/admin-api.md: ########## @@ -592,121 +755,123 @@ consumer 对象 json 配置内容： } ``` -绑定认证插件有些特别，当它需要与 consumer 联合使用时，需要提供用户名、密码等信息；另一方面，当它与 route/service 绑定时，是不需要任何参数的。因为这时候是根据用户请求数据来反向推出用户对应的是哪个 consumer +当认证插件与 Consumer 一起使用时，需要提供用户名、密码等信息；当认证插件与 Route 或 Service 绑定时，则不需要任何参数，因为此时是根据用户请求数据判断用户对应的是哪个 Consumer。 -示例： +### 使用示例 -```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" +- 创建 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":"\/apisix\/consumers\/jack","modifiedIndex":63}} -``` + ``` + HTTP/1.1 200 OK + Date: Thu, 26 Dec 2019 08:17:49 GMT + ... + + {"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}} + ``` + +:::note 注意 -从 `v2.2` 版本之后，同一个 consumer 可以绑定多个认证插件。 +自 APISIX v2.2 及以上版本，同一个 Consumer 可以绑定多个认证插件。 + +::: ### 应答参数 目前是直接返回与 etcd 交互后的结果。 -[Back to TOC](#目录) - ## Upstream -*地址*：/apisix/admin/upstreams/{id} +### 请求地址 -*说明*：Upstream 是虚拟主机抽象，对给定的多个服务节点按照配置规则进行负载均衡。Upstream 的地址信息可以直接配置到 `Route`（或 `Service`) 上，当 Upstream 有重复时，就需要用“引用”方式避免重复了。 +Upstream 资源请求地址：/apisix/admin/upstreams/{id} + +Upstream 是虚拟主机抽象，对给定的多个服务节点按照配置规则进行负载均衡。Upstream 的地址信息可以直接配置到 `Route`（或 `Service`) 上，当 Upstream 有重复时，需要用“引用”方式避免重复。 ### 请求方法 -| 名字 | 请求 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 需要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。 | +| 名称 | 请求 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 需要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。 | ### body 请求参数 -APISIX 的 Upstream 除了基本的负载均衡算法选择外，还支持对上游做主被动健康检查、重试等逻辑，具体看下面表格。 +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](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` 一样。 - -`tls.client_cert_id` 可以用来指定引用的 SSL 对象。只有当 SSL 对象的 `type` 字段为 client 时才能被引用，否则请求会被 APISIX 拒绝。另外，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` 会被使用。 Review Comment: ```suggestion - `tls.client_cert_id` 可以用来指定引用的 SSL 对象。只有当 SSL 对象的 `type` 字段为 client 时才能被引用，否则请求会被 APISIX 拒绝。另外，SSL 对象中只有 `cert` 和 `key` 会被使用。 ``` ########## docs/zh/latest/admin-api.md: ########## @@ -592,121 +755,123 @@ consumer 对象 json 配置内容： } ``` -绑定认证插件有些特别，当它需要与 consumer 联合使用时，需要提供用户名、密码等信息；另一方面，当它与 route/service 绑定时，是不需要任何参数的。因为这时候是根据用户请求数据来反向推出用户对应的是哪个 consumer +当认证插件与 Consumer 一起使用时，需要提供用户名、密码等信息；当认证插件与 Route 或 Service 绑定时，则不需要任何参数，因为此时是根据用户请求数据判断用户对应的是哪个 Consumer。 -示例： +### 使用示例 -```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" +- 创建 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":"\/apisix\/consumers\/jack","modifiedIndex":63}} -``` + ``` + HTTP/1.1 200 OK + Date: Thu, 26 Dec 2019 08:17:49 GMT + ... + + {"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}} + ``` + +:::note 注意 -从 `v2.2` 版本之后，同一个 consumer 可以绑定多个认证插件。 +自 APISIX v2.2 及以上版本，同一个 Consumer 可以绑定多个认证插件。 + +::: ### 应答参数 目前是直接返回与 etcd 交互后的结果。 -[Back to TOC](#目录) - ## Upstream -*地址*：/apisix/admin/upstreams/{id} +### 请求地址 -*说明*：Upstream 是虚拟主机抽象，对给定的多个服务节点按照配置规则进行负载均衡。Upstream 的地址信息可以直接配置到 `Route`（或 `Service`) 上，当 Upstream 有重复时，就需要用“引用”方式避免重复了。 +Upstream 资源请求地址：/apisix/admin/upstreams/{id} + +Upstream 是虚拟主机抽象，对给定的多个服务节点按照配置规则进行负载均衡。Upstream 的地址信息可以直接配置到 `Route`（或 `Service`) 上，当 Upstream 有重复时，需要用“引用”方式避免重复。 ### 请求方法 -| 名字 | 请求 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 需要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。 | +| 名称 | 请求 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 需要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。 | ### body 请求参数 -APISIX 的 Upstream 除了基本的负载均衡算法选择外，还支持对上游做主被动健康检查、重试等逻辑，具体看下面表格。 +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](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` 一样。 - -`tls.client_cert_id` 可以用来指定引用的 SSL 对象。只有当 SSL 对象的 `type` 字段为 client 时才能被引用，否则请求会被 APISIX 拒绝。另外，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-环境)。 Review Comment: ```suggestion - `keepalive_pool` 允许 Upstream 有自己单独的连接池。它下属的字段，比如 `requests`，可以用于配置上游连接保持的参数。该特性需要 APISIX 运行于 [APISIX-Base](./FAQ.md#如何构建-apisix-base-环境) 中。 ``` ########## docs/zh/latest/admin-api.md: ########## @@ -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。 +路由资源请求地址：/apisix/admin/routes/{id}?ttl=0 -注意：在启用 `Admin API` 时，它会占用前缀为 `/apisix/admin` 的 API。因此，为了避免您设计 API 与 `/apisix/admin` 冲突，建议为 Admin API 使用其他端口，您可以在 `conf/config.yaml` 中通过 `admin_listen` 进行自定义 Admin API 端口。 +Route 也称之为路由，可以通过定义一些规则来匹配客户端的请求，然后根据匹配结果加载并执行相应的插件，并把请求转发给到指定 Upstream（上游）。 ### 请求方法 -| 名字 | 请求 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 | 请求 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 | +| 名称 | 必选项 | 类型 | 描述 | 示例 | +| ---- | ------ | ---- | -------------------------------------------- | ----- | +| ttl | 否 | 辅助 | 路由的有效期。超过定义的时间，APISIX 将会自动删除路由，单位为秒。 | 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 配置内容： +| 名称 | 必选项 | 类型 | 描述 | 示例值 | +| ---------------- | -------------------------------- | -------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ---------------------------------------------------- | +| 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 配置，请参考 [Service](terminology/service.md)。 | | +| plugin_config_id | 否，不能与 Script 共同使用。 | Plugin | 绑定的 Plugin Config 配置，请参考 [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`。 Review Comment: Maybe use code example format to show it will be better. I think the use of `等于` is a little bit confused. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
