網關服務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=<service_id>。使用JSON則是"service":{“id”:"<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/