失眠网 > 高性能微服务网关APISIX - API文档

高性能微服务网关APISIX - API文档

时间：2023-01-10 10:36:50

Admin API

Description

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

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

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

Route

地址：/apisix/admin/routes/{id}?ttl=0

说明：Route 字面意思就是路由，通过定义一些规则来匹配客户端的请求，然后根据匹配结果加载并执行相应的插件，并把请求转发给到指定 Upstream。

注意：在启用Admin API时，它会占用前缀为/apisix/admin的 API。因此，为了避免您设计 API 与/apisix/admin冲突，建议为 Admin API 使用其他端口，您可以在conf/config.yaml中通过port_admin进行自定义 Admin API 端口。

请求方法

URL 请求参数

body 请求参数

有两点需要特别注意：

对于同一类参数比如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": ["",""], # 一组 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:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '{"uri": "/index.html","hosts": ["", "*."],"remote_addrs": ["127.0.0.0/8"],"methods": ["PUT", "GET"],"enable_websocket": true,"upstream": {"type": "roundrobin","nodes": {"39.97.63.215:80": 1}}}'HTTP/1.1 201 CreatedDate: Sat, 31 Aug 01:17:15 GMT...# 创建一个有效期为 60 秒的路由，过期后自动删除$ curl http://127.0.0.1:9080/apisix/admin/routes/2?ttl=60 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '{"uri": "/aa/index.html","upstream": {"type": "roundrobin","nodes": {"39.97.63.215:80": 1}}}'HTTP/1.1 201 CreatedDate: Sat, 31 Aug 01:17:15 GMT...# 给路由增加一个 upstream node$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '{"upstream": {"nodes": {"39.97.63.216:80": 1}}}'HTTP/1.1 200 OK...执行成功后，upstream nodes 将更新为：{"39.97.63.215:80": 1,"39.97.63.216:80": 1}# 给路由更新一个 upstream node 的权重$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '{"upstream": {"nodes": {"39.97.63.216:80": 10}}}'HTTP/1.1 200 OK...执行成功后，upstream nodes 将更新为：{"39.97.63.215:80": 1,"39.97.63.216:80": 10}# 给路由删除一个 upstream node$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '{"upstream": {"nodes": {"39.97.63.215:80": null}}}'HTTP/1.1 200 OK...执行成功后，upstream nodes 将更新为：{"39.97.63.216:80": 10}# 替换路由的 methods -- 数组$ curl http://127.0.0.1:9080/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:9080/apisix/admin/routes/1/upstream/nodes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '{"39.97.63.200:80": 1}'HTTP/1.1 200 OK...执行成功后，nodes 将不保留原来的数据，整个更新为：{"39.97.63.200:80": 1}# 替换路由的 methods -- sub path$ curl http://127.0.0.1:9080/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:9080/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:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '{"status": 1}'HTTP/1.1 200 OK...执行成功后，status 将更新为：{"status": 1}

应答参数

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

Service

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

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

请求方法

body 请求参数

service 对象 json 配置内容：

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

具体示例：

# 创建一个Service$ curl http://127.0.0.1:9080/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": {"39.97.63.215:80": 1}}}'# 返回结果HTTP/1.1 201 Created...# 给 Service 增加一个 upstream node$ curl http://127.0.0.1:9080/apisix/admin/services/201 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '{"upstream": {"nodes": {"39.97.63.216:80": 1}}}'HTTP/1.1 200 OK...执行成功后，upstream nodes 将更新为：{"39.97.63.215:80": 1,"39.97.63.216:80": 1}# 给 Service 更新一个 upstream node 的权重$ curl http://127.0.0.1:9080/apisix/admin/services/201 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '{"upstream": {"nodes": {"39.97.63.216:80": 10}}}'HTTP/1.1 200 OK...执行成功后，upstream nodes 将更新为：{"39.97.63.215:80": 1,"39.97.63.216:80": 10}# 给 Service 删除一个 upstream node$ curl http://127.0.0.1:9080/apisix/admin/services/201 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '{"upstream": {"nodes": {"39.97.63.215:80": null}}}'HTTP/1.1 200 OK...执行成功后，upstream nodes 将更新为：{"39.97.63.216:80": 10}# 替换 Service 的 upstream nodes$ curl http://127.0.0.1:9080/apisix/admin/services/201/upstream/nodes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '{"39.97.63.200:80": 1}'HTTP/1.1 200 OK...执行成功后，upstream nodes 将不保留原来的数据，整个更新为：{"39.97.63.200:80": 1}

应答参数

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

Consumer

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

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

请求方法

body 请求参数

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:9080/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 OKDate: Thu, 26 Dec 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},"action":"set"}

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

应答参数

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

Upstream

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

说明：Upstream 是虚拟主机抽象，对给定的多个服务节点按照配置规则进行负载均衡。Upstream 的地址信息可以直接配置到Route（或Service) 上，当 Upstream 有重复时，就需要用“引用”方式避免重复了。

请求方法

body 请求参数

APISIX 的 Upstream 除了基本的负载均衡算法选择外，还支持对上游做主被动健康检查、重试等逻辑，具体看下面表格。

type可以是以下的一种：

roundrobin: 带权重的 roundrobinchash: 一致性哈希ewma: 选择延迟最小的节点，计算细节参考 /wiki/EWMA_chartleast_conn: 选择(active_conn + 1) / weight最小的节点。注意这里的active connection概念跟 Nginx 的相同：它是当前正在被请求使用的连接。用户自定义的 balancer，需要可以通过require("apisix.balancer.your_balancer")来加载。

hash_on比较复杂，这里专门说明下：

设为vars时，key为必传参数，目前支持的 Nginx 内置变量有uri, server_name, server_addr, request_uri, remote_port, remote_addr, query_string, host, hostname, arg_***，其中arg_***是来自 URL 的请求参数，Nginx 变量列表设为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。

tls.client_cert/key可以用来跟上游进行 mTLS 通信。他们的格式和 SSL 对象的cert和key一样。这个特性需要 APISIX 运行于 APISIX-OpenResty。

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

upstream 对象 json 配置内容：

{"id": "1", # id"retries": 1,# 请求重试次数"timeout": {# 设置连接、发送消息、接收消息的超时时间"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:9080/apisix/admin/upstreams/100 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -i -X PUT -d '{"type":"roundrobin","nodes":{"39.97.63.215:80": 1}}'HTTP/1.1 201 Created...# 给 Upstream 增加一个 node$ curl http://127.0.0.1:9080/apisix/admin/upstreams/100 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '{"nodes": {"39.97.63.216:80": 1}}'HTTP/1.1 200 OK...执行成功后，nodes 将更新为：{"39.97.63.215:80": 1,"39.97.63.216:80": 1}# 给 Upstream 更新一个 node 的权重$ curl http://127.0.0.1:9080/apisix/admin/upstreams/100 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '{"nodes": {"39.97.63.216:80": 10}}'HTTP/1.1 200 OK...执行成功后，nodes 将更新为：{"39.97.63.215:80": 1,"39.97.63.216:80": 10}# 给 Upstream 删除一个 node$ curl http://127.0.0.1:9080/apisix/admin/upstreams/100 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '{"nodes": {"39.97.63.215:80": null}}'HTTP/1.1 200 OK...执行成功后，nodes 将更新为：{"39.97.63.216:80": 10}# 替换 Upstream 的 nodes$ curl http://127.0.0.1:9080/apisix/admin/upstreams/100/nodes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '{"39.97.63.200:80": 1}'HTTP/1.1 200 OK...执行成功后，nodes 将不保留原来的数据，整个更新为：{"39.97.63.200:80": 1}

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

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

$ curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{"uri": "/get","upstream": {"type": "roundrobin","scheme": "https","nodes": {":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.2", "port": 1980, "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 交互后的结果。

SSL

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

说明：SSL.

请求方法

body 请求参数

ssl 对象 json 配置内容：

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

更多的配置示例见证书。

Global Rule

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

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

请求方法

body 请求参数

Plugin Config

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

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

请求方法

body 请求参数

Plugin Metadata

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

说明: 插件元数据。

请求方法

body 请求参数

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

例子:

$ curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/example-plugin -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -i -X PUT -d '{"skey": "val","ikey": 1}'HTTP/1.1 201 CreatedDate: Thu, 26 Dec 04:19:34 GMTContent-Type: text/plain

Plugin

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

说明: 插件

请求方法

body 请求参数

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

例子:

$ curl "http://127.0.0.1:9080/apisix/admin/plugins/list" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'["zipkin","request-id",...]$ curl "http://127.0.0.1:9080/apisix/admin/plugins/key-auth" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'{"properties":{"disable":{"type":"boolean"}},"additionalProperties":false,"type":"object"}

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

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

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

请求方法

请求参数

Stream Route

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

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

请求方法

body 请求参数

Control API

control API 可以被用来：

暴露 APISIX 内部状态信息控制单个 APISIX 的数据平面的行为

默认情况下，control API 是启用的，监听127.0.0.1:9090。你可以通过修改apisix/conf/config.yaml中的 control 部分来更改设置，如下：

apisix:...enable_control: truecontrol:ip: "127.0.0.1"port: 9090

注意: control API server 不应该被配置成监听公网地址。

通过插件添加的 control API

APISIX 中一些插件添加了自己的 control API。如果你对他们感兴趣，请参阅对应插件的文档。

独立于插件的 control API

以下是支持的 API:

GET /v1/schema

引入自 2.2 版本

使用以下格式返回被该 APISIX 实例使用的 json schema：

{"main": {"route": {"properties": {...}},"upstream": {"properties": {...}},...},"plugins": {"example-plugin": {"consumer_schema": {...},"metadata_schema": {...},"schema": {...},"type": ...,"priority": 0,"version": 0.1},...},"stream-plugins": {"mqtt-proxy": {...},...}}

只有启用了的插件才会被包含在返回结果中plugins部分。(返回结果中的)一些插件可能会缺失如consumer_schema或者type字段，这取决于插件的定义。

GET /v1/healthcheck

引入自 2.3 版本

使用以下格式返回当前的 health check 状态

[{"healthy_nodes": [{"host": "127.0.0.1","port": 1980,"priority": 0,"weight": 1}],"name": "upstream#/upstreams/1","nodes": [{"host": "127.0.0.1","port": 1980,"priority": 0,"weight": 1},{"host": "127.0.0.2","port": 1988,"priority": 0,"weight": 1}],"src_id": "1","src_type": "upstreams"},{"healthy_nodes": [{"host": "127.0.0.1","port": 1980,"priority": 0,"weight": 1}],"name": "upstream#/routes/1","nodes": [{"host": "127.0.0.1","port": 1980,"priority": 0,"weight": 1},{"host": "127.0.0.1","port": 1988,"priority": 0,"weight": 1}],"src_id": "1","src_type": "routes"}]

每个 entry 包含以下字段：

src_type：表示 health checker 的来源。值是[routes,services,upstreams]其中之一src_id：表示创建 health checker 的对象的id。例如，假设 id 为 1 的 Upstream 对象创建了一个 health checker，那么src_type就是upstreams，src_id就是 1name：表示 health checker 的名称nodes： health checker 的目标节点healthy_nodes：表示 health checker 检测到的健康节点

用户也可以通过/v1/healthcheck/$src_type/$src_id来获取指定 health checker 的状态。

例如，GET /v1/healthcheck/upstreams/1返回：

{"healthy_nodes": [{"host": "127.0.0.1","port": 1980,"priority": 0,"weight": 1}],"name": "upstream#/upstreams/1","nodes": [{"host": "127.0.0.1","port": 1980,"priority": 0,"weight": 1},{"host": "127.0.0.2","port": 1988,"priority": 0,"weight": 1}],"src_id": "1","src_type": "upstreams"}