Admin API

描述

Admin API 是为 Apache APISIX 服务的一组 API，我们可以将参数传递给 Admin API 以控制 APISIX 节点。更好地了解其工作原理，请参阅 Architecture Design 中的文档。

启动 Apache APISIX 时，默认情况下 Admin API 将监听 9180 端口。您可以通过修改 conf/config.yaml 文件来改变默认监听的端口。

在下面出现的 X-API-KEY 指的是 conf/config.yaml 文件中的 deployment.admin.admin_key.key，它是 Admin API 的访问 token。

V3

Admin API 在 V3 版本中做了一些不向下兼容的调整，以及支持更多特性。

支持新的响应体格式

1. 移除响应体中的 action 字段；
2. 调整获取资源列表时的响应体结构，新的响应体结构示例如下：

返回单个资源：

{
  "modifiedIndex": 2685183,
  "value": {
    "id": "1",
    ...
  },
  "key": "/apisix/routes/1",
  "createdIndex": 2684956
}

返回多个资源：

{
  "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
}

支持分页查询

获取资源列表时支持分页查询，分页参数包括：

参数	默认值	范围	说明
page	1	[1, ...]	页数
page_size		[10, 500]	每页资源数量

示例如下：

$ curl "http://127.0.0.1:9180/apisix/admin/routes?page=1&page_size=10" \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X GET

{
  "total": 1,
  "list": [
    {
      ...
    }
  ]
}

目前支持分页查询的资源如下：

• Consumer
• Consumer Group
• Global Rules
• Plugin Config
• Proto
• Route
• Service
• SSL
• Stream Route
• Upstream

支持过滤资源

获取资源列表时支持根据 name, label, uri 过滤资源。

参数	说明
name	根据资源的 name 属性进行查询，如果资源本身没有 name 属性则不会出现在查询结果中。
label	根据资源的 label 属性进行查询，如果资源本身没有 label 属性则不会出现在查询结果中。
uri	仅在 Route 资源上支持。如果 Route 的 uri 等于查询的 uri 或 uris 包含查询的 uri，则该 Route 资源出现在查询结果中。

当启用了多个过滤参数时，对不同过滤参数的查询结果取交集。 下述示例将返回一个路由列表，该路由列表中的所有路由满足以下条件：路由的 name 包含字符串 "test"；uri 包含字符串 "foo"；对路由的 label 没有限制，因为查询的 label 是空字符串。

$ curl 'http://127.0.0.1:9180/apisix/admin/routes?name=test&uri=foo&label=' \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X GET

{
  "total": 1,
  "list": [
    {
      ...
    }
  ]
}

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 还允许更高级匹配，更多见 Router。	"/hello"
uris	必选，不能与 uri 一起使用	匹配规则	非空数组形式，可以匹配多个 uri	["/hello", "/world"]
plugins	可选	Plugin	详见 Plugin
script	可选	Script	详见 Script
upstream	可选	Upstream	启用的 Upstream 配置，详见 Upstream
upstream_id	可选	Upstream	启用的 upstream id，详见 Upstream
service_id	可选	Service	绑定的 Service 配置，详见 Service
plugin_config_id	可选，无法跟 script 一起配置	Plugin	绑定的 Plugin config 配置，详见 Plugin config
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	[["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 选项	{"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 配置内容：

{
    "id": "1",                            # id，非必填
    "uris": ["/a","/b"],                  # 一组 URL 路径
    "methods": ["GET","POST"],            # 可以填多个方法
    "hosts": ["a.com","b.com"],           # 一组 host 域名
    "plugins": {},                        # 指定 route 绑定的插件
    "priority": 0,                        # apisix 支持多种匹配方式，可能会在一次匹配中同时匹配到多条路由，此时优先级高的优先匹配中
    "name": "路由 xxx",
    "desc": "hello world",
    "remote_addrs": ["127.0.0.1"],        # 一组客户端请求 IP 地址
    "vars": [["http_user", "==", "ios"]], # 由一个或多个 [var, operator, val] 元素组成的列表
    "upstream_id": "1",                   # upstream 对象在 etcd 中的 id ，建议使用此值
    "upstream": {},                       # upstream 信息对象，建议尽量不要使用
    "timeout": {                          # 为 route 设置 upstream 的连接、发送消息、接收消息的超时时间。
        "connect": 3,
        "send": 3,
        "read": 3
    },
    "filter_func": ""                     # 用户自定义的过滤函数，非必填
}

具体示例：

# 创建一个路由
$ 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
...

# 创建一个有效期为 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
        }
    }
}'

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
        }
    }
}'
HTTP/1.1 200 OK
...

执行成功后，upstream nodes 将更新为：
{
    "127.0.0.1:1980": 1,
    "127.0.0.1:1981": 1
}


# 给路由更新一个 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
        }
    }
}'
HTTP/1.1 200 OK
...

执行成功后，upstream nodes 将更新为：
{
    "127.0.0.1:1980": 1,
    "127.0.0.1:1981": 10
}


# 给路由删除一个 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
        }
    }
}'
HTTP/1.1 200 OK
...

执行成功后，upstream nodes 将更新为：
{
    "127.0.0.1:1981": 10
}


# 替换路由的 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
...

执行成功后，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
...

执行成功后，nodes 将不保留原来的数据，整个更新为：
{
    "127.0.0.1:1982": 1
}


# 替换路由的 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
...

执行成功后，methods 将不保留原来的数据，整个更新为：
["POST", "DELETE", "PATCH"]


# 禁用路由
$ 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 将更新为：
{
    "status": 0
}


# 启用路由
$ 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
}

应答参数

目前是直接返回与 etcd 交互后的结果。

Back to TOC

Service

地址：/apisix/admin/services/{id}

说明：Service 是某类 API 的抽象（也可以理解为一组 Route 的抽象）。它通常与上游服务抽象是一一对应的，Route 与 Service 之间，通常是 N:1 的关系。

请求方法

名字	请求 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 需要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留

body 请求参数

名字	可选项	类型	说明	示例
plugins	可选	Plugin	详见 Plugin
upstream	upstream 或 upstream_id 两个选一个	Upstream	启用的 Upstream 配置，详见 Upstream
upstream_id	upstream 或 upstream_id 两个选一个	Upstream	启用的 upstream id，详见 Upstream
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 配置内容：

{
    "id": "1",                # id
    "plugins": {},            # 指定 service 绑定的插件
    "upstream_id": "1",       # upstream 对象在 etcd 中的 id ，建议使用此值
    "upstream": {},           # upstream 信息对象，不建议使用
    "name": "test svc",       # service 名称
    "desc": "hello world",    # service 描述
    "enable_websocket": true, # 启动 websocket 功能
    "hosts": ["foo.com"]
}

具体示例：

# 创建一个 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"
        }
    },
    "enable_websocket": true,
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    }
}'

# 返回结果

HTTP/1.1 201 Created
...


# 给 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
        }
    }
}'
HTTP/1.1 200 OK
...

执行成功后，upstream nodes 将更新为：
{
    "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": 10
        }
    }
}'
HTTP/1.1 200 OK
...

执行成功后，upstream nodes 将更新为：
{
    "127.0.0.1:1980": 1,
    "127.0.0.1:1981": 10
}


# 给 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
        }
    }
}'
HTTP/1.1 200 OK
...

执行成功后，upstream nodes 将更新为：
{
    "127.0.0.1:1981": 10
}


# 替换 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
...

执行成功后，upstream nodes 将不保留原来的数据，整个更新为：
{
    "127.0.0.1:1982": 1
}

应答参数

目前是直接返回与 etcd 交互后的结果。

Back to TOC

Consumer

地址：/apisix/admin/consumers/{username}

说明：Consumer 是某类服务的消费者，需与用户认证体系配合才能使用。Consumer 使用 username 作为唯一标识，只支持使用 HTTP PUT 方法创建 Consumer。

请求方法

名字	请求 uri	请求 body	说明
GET	/apisix/admin/consumers	无	获取资源列表
GET	/apisix/admin/consumers/{id}	无	获取资源
PUT	/apisix/admin/consumers	{...}	创建资源
DELETE	/apisix/admin/consumers/{id}	无	删除资源

body 请求参数

名字	可选项	类型	说明	示例
username	必需	辅助	Consumer 名称。
group_id	可选	辅助	Consumer Group 名称。
plugins	可选	Plugin	该 Consumer 对应的插件配置，它的优先级是最高的：Consumer > Route > Service。对于具体插件配置，可以参考 Plugins 章节。
desc	可选	辅助	consumer 描述
labels	可选	匹配规则	标识附加属性的键值对	{"version":"v2","build":"16","env":"production"}
create_time	可选	辅助	单位为秒的 epoch 时间戳，如果不指定则自动创建	1602883670
update_time	可选	辅助	单位为秒的 epoch 时间戳，如果不指定则自动创建	1602883670

consumer 对象 json 配置内容：

{
    "plugins": {},          # 指定 consumer 绑定的插件
    "username": "name",     # 必填
    "desc": "hello world"   # consumer 描述
}

绑定认证插件有些特别，当它需要与 consumer 联合使用时，需要提供用户名、密码等信息；另一方面，当它与 route/service 绑定时，是不需要任何参数的。因为这时候是根据用户请求数据来反向推出用户对应的是哪个 consumer

示例：

# 创建 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"
        }
    }
}'
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}}

从 v2.2 版本之后，同一个 consumer 可以绑定多个认证插件。

应答参数

目前是直接返回与 etcd 交互后的结果。

Back to TOC

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 需要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。

body 请求参数

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	服务发现时使用的服务名，见集成服务发现注册中心	a-bootiful-client
discovery_type	必需，如果设置了 service_name	string	服务发现类型，见 集成服务发现注册中心	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 变量列表
checks	可选	health_checker	配置健康检查的参数，详细可参考health-check
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
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 的相同：它是当前正在被请求使用的连接。
• 用户自定义的 balancer，需要可以通过 require("apisix.balancer.your_balancer") 来加载。

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 变量列表
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。

以下特性需要 APISIX 运行于 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 会被使用。

keepalive_pool 允许 upstream 对象有自己单独的连接池。 它下属的字段，比如 requests，可以用了配置上游连接保持的参数。 这个特性需要 APISIX 运行于 APISIX-Base。

upstream 对象 json 配置内容：

{
    "id": "1",                  # id
    "retries": 1,               # 请求重试次数
    "timeout": {                # 设置连接、发送消息、接收消息的超时时间，每项都为 15 秒
        "connect":15,
        "send":15,
        "read":15
    },
    "nodes": {"host:80": 100},  # 上游机器地址列表，格式为`地址 + 端口`
                                # 等价于 "nodes": [ {"host":"host", "port":80, "weight": 100} ],
    "type":"roundrobin",
    "checks": {},               # 配置健康检查的参数
    "hash_on": "",
    "key": "",
    "name": "upstream-xxx",     # upstream 名称
    "desc": "hello world",      # upstream 描述
    "scheme": "http"            # 跟上游通信时使用的 scheme，默认是 `http`
}

具体示例：

示例一：创建一个 upstream 并对 nodes 的数据做修改

# 创建一个 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
...


# 给 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:1981": 1
    }
}'
HTTP/1.1 200 OK
...

执行成功后，nodes 将更新为：
{
    "127.0.0.1:1980": 1,
    "127.0.0.1:1981": 1
}


# 给 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:1981": 10
    }
}'
HTTP/1.1 200 OK
...

执行成功后，nodes 将更新为：
{
    "127.0.0.1:1980": 1,
    "127.0.0.1:1981": 10
}


# 给 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
}


# 替换 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
...

执行成功后，nodes 将不保留原来的数据，整个更新为：
{
    "127.0.0.1:1982": 1
}

示例二：将客户端请求代理到上游 https 服务

1、创建 route 并配置 upstream 的 scheme 为 https。

$ 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。

2、 发送请求进行测试。

$ 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"
}

请求成功，表示代理上游 https 生效了。

注意：

节点可以配置自己的优先级。只有在高优先级的节点不可用或者尝试过，才会访问一个低优先级的节点。

由于默认的优先级是 0，我们可以给一些节点配置负数的优先级来作为备份。 举个例子：

{
    "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 的备份。

应答参数

目前是直接返回与 etcd 交互后的结果。

Back to TOC

SSL

地址：/apisix/admin/ssls/{id}

说明：SSL.

请求方法

名字	请求 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 请求参数

名字	可选项	类型	说明	示例
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 配置内容：

{
    "id": "1",          # id
    "cert": "cert",     # 证书
    "key": "key",       # 私钥
    "snis": ["t.com"]   # HTTPS 握手时客户端发送的 SNI
}

更多的配置示例见 证书。

Back to TOC

Global Rule

地址：/apisix/admin/global_rules/{id}

说明：设置全局运行的插件。这一类插件在所有路由级别的插件之前优先运行。

请求方法

名字	请求 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 请求参数

名字	可选项	类型	说明	示例
plugins	必需	Plugin	详见 Plugin
create_time	可选	辅助	单位为秒的 epoch 时间戳，如果不指定则自动创建	1602883670
update_time	可选	辅助	单位为秒的 epoch 时间戳，如果不指定则自动创建	1602883670

Back to TOC

Consumer Group

地址：/apisix/admin/consumer_groups/{id}

说明：配置一组可以在 Consumer 间复用的插件。

请求方法

名字	请求 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 要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。

body 请求参数

名字	可选项	类型	说明	示例
plugins	必需	Plugin	详见 Plugin
desc	可选	辅助	标识描述、使用场景等	customer xxxx
labels	可选	辅助	标识附加属性的键值对	{"version":"v2","build":"16","env":"production"}
create_time	可选	辅助	单位为秒的 epoch 时间戳，如果不指定则自动创建	1602883670
update_time	可选	辅助	单位为秒的 epoch 时间戳，如果不指定则自动创建	1602883670

Back to TOC

Plugin Config

地址：/apisix/admin/plugin_configs/{id}

说明：配置一组可以在路由间复用的插件。

请求方法

名字	请求 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 即可删除；特别地，当需要修改属性的值为数组时，该属性将全量更新
PATCH	/apisix/admin/plugin_configs/{id}/{path}	{...}	SubPath PATCH，通过 {path} 指定 Plugin Config 要更新的属性，全量更新该属性的数据，其他不涉及的属性会原样保留。

body 请求参数

名字	可选项	类型	说明	示例
plugins	必需	Plugin	详见 Plugin
desc	可选	辅助	标识描述、使用场景等	customer xxxx
labels	可选	辅助	标识附加属性的键值对	{"version":"v2","build":"16","env":"production"}
create_time	可选	辅助	单位为秒的 epoch 时间戳，如果不指定则自动创建	1602883670
update_time	可选	辅助	单位为秒的 epoch 时间戳，如果不指定则自动创建	1602883670

Back to TOC

Plugin Metadata

地址：/apisix/admin/plugin_metadata/{plugin_name}

说明: 插件元数据。

请求方法

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}	无	删除资源

body 请求参数

一个根据插件 ({plugin_name}) 的 metadata_schema 定义的数据结构的 json object 。

例子：

$ 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}

说明:  插件

请求方法

名字	请求  uri	请求  body	说明
GET	/apisix/admin/plugins/list	无	获取资源列表
GET	/apisix/admin/plugins/{plugin_name}	无	获取资源
GET	/apisix/admin/plugins?all=true	无	获取所有插件的所有属性

body 请求参数

获取插件  ({plugin_name})  数据结构的  json object 。

例子：

$ 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"}},"type":"object"},"query":{"default":"apikey","type":"string"}},"type":"object"}

地址：/apisix/admin/plugins?all=true

说明: 所有插件的所有属性，每个插件包括 name, priority, type, schema, consumer_schema 和 version。

默认情况下，这个接口只返回 http 插件。如果你需要 stream 插件，需要用 /apisix/admin/plugins?all=true&subsystem=stream。

请求方法

Method	请求 URI	请求 body	说明
GET	/apisix/admin/plugins?all=true	无	获取资源

请求参数

名称	说明	默认
subsystem	插件所属的子系统	http

Back to TOC

Stream Route

API：/apisix/admin/stream_routes/{id}

Description：Stream Route 是用于 TCP/UDP 动态代理的路由。参见 TCP/UDP 动态代理 一节。

请求方法

名字	请求 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}	无	删除资源

body 请求参数

名字	可选项	类型	说明	示例
upstream	可选	Upstream	启用的 Upstream 配置，详见 Upstream
upstream_id	可选	Upstream	启用的 upstream id，详见 Upstream
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	可选	配置	协议特定的配置

点击 此处，了解更多有关过滤器如何工作的信息。

Back to TOC