This is an automated email from the ASF dual-hosted git repository. tokers 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 c260b28 docs(admin-api): increase the introduction of the use of
cookies (#4016)
c260b28 is described below
commit c260b2800a03c89d7f6236110de46cff568120bf
Author: Yuelin Zheng <[email protected]>
AuthorDate: Mon Apr 12 09:07:17 2021 +0800
docs(admin-api): increase the introduction of the use of cookies (#4016)
---
docs/en/latest/admin-api.md | 15 ++++++++-----
docs/zh/latest/admin-api.md | 54 ++++++++++++++++++++++-----------------------
2 files changed, 36 insertions(+), 33 deletions(-)
diff --git a/docs/en/latest/admin-api.md b/docs/en/latest/admin-api.md
index c0500c6..d48079b 100644
--- a/docs/en/latest/admin-api.md
+++ b/docs/en/latest/admin-api.md
@@ -94,7 +94,10 @@ Note: When the `Admin API` is enabled, it will occupy the
API prefixed with `/ap
| create_time | False | Auxiliary |
epoch timestamp in second, will be created automatically if missing
[...]
| update_time | False | Auxiliary |
epoch timestamp in second, will be created automatically if missing
[...]
-For the same type of parameters, such as `host` and `hosts`, `remote_addr` and
`remote_addrs` cannot exist at the same time, only one of them can be selected.
If enabled at the same time, the API will respond with an error.
+There are two points that need special attention:
+
+- For the same type of parameters, such as `host` and `hosts`, `remote_addr`
and `remote_addrs` cannot exist at the same time, only one of them can be
selected. If enabled at the same time, the API will respond with an error.
+- In `vars`, when getting the cookie value, the cookie name is
**case-sensitive**. For example: `var` equals "cookie_x_foo" and `var` equals
"cookie_X_Foo" means different `cookie`.
Config Example:
@@ -555,11 +558,11 @@ In addition to the basic complex equalization algorithm
selection, APISIX's Upst
`hash_on` can be set to different types:
-1. when it is `vars`, the `key` is required. The `key` can be any [Nginx
builtin variables](http://nginx.org/en/docs/varindex.html), without the prefix
'$'.
-1. when it is `header`, the `key` is required. It is equal to "http_`key`".
-1. when it is `cookie`, the `key` is required. It is equal to "cookie_`key`".
-1. when it is `consumer`, the `key` is optional. The key is the
`consumer_name` set by authentication plugin.
-1. when it is `vars_combinations`, the `key` is required. The `key` can be any
[Nginx builtin variables](http://nginx.org/en/docs/varindex.html) combinations,
such as `$request_uri$remote_addr`.
+1. When it is `vars`, the `key` is required. The `key` can be any [Nginx
builtin variables](http://nginx.org/en/docs/varindex.html), without the prefix
'$'.
+1. When it is `header`, the `key` is required. It is equal to "http_`key`".
+1. When it is `cookie`, the `key` is required. It is equal to "cookie_`key`".
Please note that the cookie name is **case-sensitive**. For example:
"cookie_x_foo" and "cookie_X_Foo" indicate different `cookie`.
+1. When it is `consumer`, the `key` is optional. The key is the
`consumer_name` set by authentication plugin.
+1. When it is `vars_combinations`, the `key` is required. The `key` can be any
[Nginx builtin variables](http://nginx.org/en/docs/varindex.html) combinations,
such as `$request_uri$remote_addr`.
1. If there is no value for either `hash_on` or `key`, `remote_addr` will be
used as key.
`tls.client_cert/key` can be used to communicate with upstream via mTLS.
diff --git a/docs/zh/latest/admin-api.md b/docs/zh/latest/admin-api.md
index 8bffa0f..d660976 100644
--- a/docs/zh/latest/admin-api.md
+++ b/docs/zh/latest/admin-api.md
@@ -63,36 +63,36 @@ title: Admin API
> body 请求参数：
-| 名字 | 可选项
| 类型 | 说明
| 示例
|
-| ---------------- |
----------------------------------------------------------------------- |
-------- |
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| ------------------------------------- [...]
-| uri | 与 `uris` 二选一
| 匹配规则 | 除了如 `/foo/bar`、`/foo/gloo` 这种全量匹配外，使用不同
[Router](architecture-design/router.md) 还允许更高级匹配，更多见
[Router](architecture-design/router.md)。
| "/hello"
|
-| uris | 与 `uri` 二选一
| 匹配规则 | 非空数组形式，可以匹配多个 `uri`
| ["/hello", "/world"]
|
-| plugins |
`plugins`、`script`、`upstream`/`upstream_id`、`service_id`至少选择一个 | Plugin | 详见
[Plugin](architecture-design/plugin.md)
| |
-| script |
`plugins`、`script`、`upstream`/`upstream_id`、`service_id`至少选择一个 | Script | 详见
[Script](architecture-design/script.md)
| |
-| upstream |
`plugins`、`script`、`upstream`/`upstream_id`、`service_id`至少选择一个 | Upstream | 启用的
Upstream 配置，详见 [Upstream](architecture-design/upstream.md)
| |
-| upstream_id |
`plugins`、`script`、`upstream`/`upstream_id`、`service_id`至少选择一个 | Upstream | 启用的
upstream id，详见 [Upstream](architecture-design/upstream.md)
| |
-| service_id |
`plugins`、`script`、`upstream`/`upstream_id`、`service_id`至少选择一个 | Service | 绑定的
Service 配置，详见 [Service](architecture-design/service.md)
| |
-| plugin_config_id | 可选，无法跟 script 一起配置
| Plugin | 绑定的 Plugin config 配置，详见 [Plugin
config](architecture-design/plugin-config.md)
|
|
-| name | 可选
| 辅助 | 标识路由名称
| route-xxxx
|
-| desc | 可选
| 辅助 | 标识描述、使用场景等。
| 客户 xxxx
|
-| host | 可选
| 匹配规则 | 当前请求域名，比如 `foo.com`；也支持泛域名，比如 `*.foo.com`。
| "foo.com"
|
-| hosts | 可选
| 匹配规则 | 非空列表形态的 `host`，表示允许有多个不同 `host`，匹配其中任意一个即可。
| {"foo.com", "\*.bar.com"} |
-| remote_addr | 可选
| 匹配规则 | 客户端请求 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`，表示允许有多个不同 IP 地址，符合其中任意一个即可。
| {"127.0.0.1", "192.0.0.0/8", "::1"} |
-| methods | 可选
| 匹配规则 | 如果为空或没有该选项，代表没有任何 `method` 限制，也可以是一个或多个的组合：`GET`, `POST`,
`PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`，`CONNECT`，`TRACE`。
| {"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"} |
-| enable_websocket | 可选
| 辅助 | 是否启用 `websocket`(boolean), 缺省 `false`.
|
|
-| status | 可选
| 辅助 | 是否启用此路由, 缺省 `1`。
| `1` 表示启用，`0` 表示禁用
|
-| create_time | 可选
| 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建
| 1602883670
|
-| update_time | 可选
| 辅助 | 单位为秒的 epoch 时间戳，如果不指定则自动创建
| 1602883670
|
+| 名字 | 可选项 | 类型 | 说明
| 示例 |
+| ---------------- | ---------------------------------- | -------- |
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| ---------------------------------------------------- |
+| uri | 必选，不能与 `uris` 一起使用 | 匹配规则 | 除了如
`/foo/bar`、`/foo/gloo` 这种全量匹配外，使用不同 [Router](architecture-design/router.md)
还允许更高级匹配，更多见 [Router](architecture-design/router.md)。
|
"/hello" |
+| uris | 必选，不能与 `uri` 一起使用 | 匹配规则 | 非空数组形式，可以匹配多个 `uri`
|
["/hello", "/world"] |
+| plugins | 可选 | Plugin | 详见
[Plugin](architecture-design/plugin.md)
| |
+| script | 可选 | Script | 详见
[Script](architecture-design/script.md)
| |
+| upstream | 可选 | Upstream | 启用的
Upstream 配置，详见 [Upstream](architecture-design/upstream.md)
| |
+| upstream_id | 可选 | Upstream | 启用的
upstream id，详见 [Upstream](architecture-design/upstream.md)
| |
+| service_id | 可选 | Service | 绑定的 Service
配置，详见 [Service](architecture-design/service.md)
| |
+| plugin_config_id | 可选，无法跟 script 一起配置 | Plugin | 绑定的 Plugin
config 配置，详见 [Plugin config](architecture-design/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`。
|
{"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"} |
+| enable_websocket | 可选 | 辅助 | 是否启用
`websocket`(boolean), 缺省 `false`.
| |
+| status | 可选 | 辅助 | 是否启用此路由, 缺省
`1`。
| `1` 表示启用，`0` 表示禁用 |
+| create_time | 可选 | 辅助 | 单位为秒的 epoch
时间戳，如果不指定则自动创建
|
1602883670 |
+| update_time | 可选 | 辅助 | 单位为秒的 epoch
时间戳，如果不指定则自动创建
|
1602883670 |
有两点需要特别注意：
-- 除了 `uri`/`uris`
是必选的之外，`plugins`、`script`、`upstream`/`upstream_id`、`service_id` 这三类必须选择其中至少一个。
- 对于同一类参数比如 `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 配置内容：
@@ -560,7 +560,7 @@ APISIX 的 Upstream 除了基本的复杂均衡算法选择外，还支持对上
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`"
+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`。
