网关服务KONG(二)：admin-api使用指南

部署好kong之后，想要进行kong的配置管理，kong提供了比较全面的restful api，每个版本会有所不同，下面的记录基于kong v0.13.x。我们可以使用界面进行如下想要实现的动作，但这里主要讲解下常用的接口api命令方式如何操作

---

1. Information Routes

获取kong节点的通用详细信息

• 查询节点信息

  curl  http://localhost:8001
  

  部分返回字段含义：

  node_id : 正在运行的kong节点的uuid，当kong启动时随机生成，每次kong重启时这个uuid都会变

  availabel_on_server : kong节点上安装的plugins的名称

  enabled_in_cluster : kong节点中启用的插件，即在数据库中生成了对应存储表

• 查询节点状态

  curl  http://localhost:8001/status
  

  total_requests : 客户端请求总数

  connections_active : 包括等待连接的活动客户端连接的当前数量

  connections_accepted : 接受的客户端连接的总数

  connections_handled : 处理连接的总数。一般来说，除非达到一定的资源限制，否则参数值与接受值相同

  connections_reading : 当前Kong正在读取请求头的连接数

  connections_writing : NGINX将响应写入客户端的连接的当前数量

  connections_waiting : 等待请求的空闲客户端连接的当前数量

  reachable : 反映数据库连接状态的布尔值。注意，此标志不反映数据库本身的健康状况

2. Service Object

属性	约束	描述
name	optional	服务名称
protocol	required,default:http	用于与上游接口通信的协议。是http或https
host	required	上游服务的host
port	required,default:80	上游服务的端口
path	optional,default:null	请求上游服务器使用的路径，默认为空
retries	optional,default:5	代理失败时重试的次数
connect_timeout	optional,default:60000ms	建立与上游服务器连接的超时时间(ms)
write_timeout	optional,default:60000ms	在向上游服务器发送请求的两个连续写入操作之间的超时时间(ms)
read_timeout	optional,default:60000ms	在向上游服务器发送请求的两个连续读取操作之间的超时时间(ms)
url	shorthand-attribute	一次性设置protocol、host、port和path的缩写。此属性是只读的（管理API不会返回“URL”）
name	optional	服务名称

• 创建一个service

  POST /services/

  curl -i -X POST --url http://localhost:8001/services/ \
   --data 'name=example-service' \
   --data 'url=http://localhost:8762/test1/'
  

• 为service创建路由

  curl -i -X POST --url http://localhost:8001/services/example-service/routes \
  --data 'hosts[]=example.com'
  

• 访问kong，测试是否转发

  curl -i -X GET --url http://localhost:8000/hello \
  --header "Host:example.com"
  

• 查看某个service

  GET /services/{name or id}

  curl -i -X GET --url  http://localhost:8001/services/example-service
  

• 更新某个service

  PATCH /services/{name or id}

  curl -i -X PATCH --url  http://localhost:8001/services/example-service \ 
  --data 	'name=example-service-bak' \
  --data 'retries=6'
  

• 删除某个service

  DELETE /services/{name or id}

  curl -i -X DELETE --url  http://localhost:8001/services/example-service 
  

3. Route Object

路由定义匹配客户端请求的规则，每个路由与服务相关联，并且一个服务可关联多个路由。匹配给定路由的每个请求将被代理到与其关联的服务。路由和服务的组合和分离提供了一种强大的路由机制，通过它可以在Kong定义细粒度的入口点，从而访问基础设施的不同上游服务

属性	约束	描述
protocols	required,default:[“http”, “https”]	此路由应允许的协议列表。 当设置为[ HTTPS ]时，HTTP请求将被请求升级到HTTPS。使用form-encoded，符号是protocols[]=http&protocols[]=https。 使用数组
methods	semi-optional	与此路由匹配的HTTP方法列表。例如[“GET”, “POST”]。必须设置hosts、paths或methods中的至少一个。使用form-encode，符号是methods[]=GET和methods[]=OPTIONS。使用数组。
hosts	semi-optional	与此路由匹配的域名列表。例如：example.com。使用form-encode，符号是hosts[]= Foo.com和hosts[]= BAR.com。使用数组
paths	semi-optional	与此路由匹配的路径列表。例如：/my-path。使用form-encode，符号是paths[]＝/foo&paths[]＝/bar。使用数组。
strip_path	optional,default:true	当通过路径之一匹配路由时，从上游请求URL中去除匹配的前缀
preserve_host	optional,default:false	当通过主机域名中的一个匹配路由时，在上游请求报头中使用请求主机头。默认情况下设置为false，上游主机头将设置为服务的主机。
service	required	此路由关联的服务。这是路由代理流量的地方。使用form-encode，符号是service.id=。使用JSON则是"service":{“id”:""}

• 创建一个route

  POST /routes/

  curl -i -X POST \
  --url  http://localhost:8001/routes/ \
  --data 'protocols[]=http&protocols[]=https' \
  --data 'hosts[]=xxx' \
  --data 'service.id=233c7ae0-b7bb-460d-af19-8d6c815d49ee'
  
  

• 根据route_id查询路由

  GET /routes/{id}

  curl -i -X GET \
   --url  http://localhost:8001/routes/73de4e14-7dfb-4c9e-95ce-bc297ad9b479
  

• 查询所有路由列表

  GET /routes

  curl -i -X GET   --url  http://localhost:8001/routes/
  

  性	约束	描述
  offset	optional	用于分页的游标。偏移量是定义列表中某个位置的对象标识符
  size	optional,default: 100, max:1000	每页返回数量的限制

• 查询一个服务关联的所有路由

  GET /services/{service name or id}/routes

  curl -i -X GET \
    --url  http://localhost:8001/services/example-serviceA/routes
  

• 更新某个路由

  PATCH /routes/{id}

  curl -i -X PATCH \
    --url  http://localhost:8001/routes/3eed8a25-3b3a-44e3-999f-5e679c379972 \
    --data 'strip_path=true'
  

• 删除某个路由

  DELETE /routes/{id}

  curl -i -X DELETE \
    --url  http://localhost:8001/routes/3eed8a25-3b3a-44e3-999f-5e679c379972 
  

3. Consumer Object

消费对象表示服务的消费者或用户。可以依赖Kong作为主要数据存储，也可以将用户自己管理的列表映射到该数据库consumer表，以保持Kong与现有主数据存储的一致性。权限控制也会依赖这个表。

属性	约束	描述
username	semi-optional	消费者的唯一用户名，和custom_id至少有一个必须指定
custom_id	semi-optional	用户存储的唯一id, 用来和现有数据库中的用户一一映射，若需要权限管理，必须将此字段或用户名与请求一起发送

• 创建一个消费者

  POST /consumers/

  curl -i -X POST \
  --url  http://localhost:8001/consumers/ \
  --data 'username=smqi' \
  --data 'custom_id=10007' 
  

• 查询消费者列表

  GET /consumers/{username or id}

  属性	约束	描述
  id	optional
  custom_id	optional
  username	optional
  size	optional,default:100	每页返回数量
  offset	optional	用于分页的游标。偏移量是定义列表中某个位置的对象标识符

• 更新指定消费者

  PATCH /consumers/{username or id}

• 删除指定消费者

  DELETE /consumers/{username or id}

---

参考文档：
1.https://www.cnblogs.com/zhoujie/p/kong2.html
2.https://www.jianshu.com/p/a68e45bcadb6/