12.18 Kong API Gateway 管理API詳解

一、前言

安裝好了Kong,那麼如何使用和管理它呢?Kong附帶了一個管理的API接口,我們通過這個API接口來管理所有的API以及其他的資源,這個接口具有最高的權限,所以在生產環境中我們要特別注意這個接口的權限,通常我們不會將這個接口暴露在外網中。

如果Kong是以集群的狀態的運行的,那麼你只需要將管理API的請求發送到其中的一個節點中,Kong會自動同步信息到其他的節點。Kong默認監聽8001和8444兩個端口用接受管理API的請求,8001為http端口,8444為https端口

Kong支持application/x-www-form-urlencoded和application/json兩種類型,POST的數據我們需要以json的格式發送。

Kong大概有以下幾個管理對象:

  • 節點信息
  • 服務
  • 路由
  • 用戶
  • 插件
  • 證書
  • SNI
  • 上游信息
  • 目標

在Kong0.13.0版本以前,有API對象,但是從0.13.0之後開始逐步拋棄API對象,使用路由和服務組合來取代API對象,這提高了Kong的靈活性。基於此本文也將不介紹有關API對象的操作

本文約定:

  • 我使用的是Kong_0.14.1版本
  • 節點管理地址為 http://192.168.0.184:8001
  • 使用curl請求接口,並且將得到的結果通過管道送給python進行格式化

例如:

<code>linuxops@deepin:~$curl -s http://192.168.0.184:8001/status | python -m json.tool
{
"database": {
"reachable": true
},
"server": {
"connections_accepted": 112,
"connections_active": 1,
"connections_handled": 112,
"connections_reading": 0,
"connections_waiting": 0,
"connections_writing": 1,
"total_requests": 65
}
}/<code>

在以上的示例中,-s參數表示靜默模式,curl將不輸入信息,這樣我們就可以不打印我們不需要關注的信息。

然後將得到的結果通過管道送給python進行格式化,這樣打印出來的就是格式化的json,方便我們查看。

下面我們一起看一下每一種對象的操作


二、節點信息

1、查看節點信息

接口信息:

接口名稱查看節點詳細信息請求端點/請求方法GET返回狀態HTTP 200 OK

請求參數:

請求示例:

<code>curl -s http://192.168.0.184:8001 | python -m json.tool/<code>

返回值:

查詢節點詳細信息返回的信息非常多,這裡就顯示了。

2、查看節點狀態

這個接口查詢節點的狀態,主要是顯示nginx進程處理連接的情況,以及數據庫連接的情況。

如果Kong是以集群的方式運行,那麼如果要查看其他節點的情況,必須要要一個一個訪問節點的此接口。

因為Kong是基於nginx的,你也可以直接使用Nginx的監控工具。

接口信息:

接口名稱查看節點狀態請求端點/status請求方法GET返回狀態HTTP 200 OK

請求參數:

請求示例:

<code>curl -s http://192.168.0.184:8001/status | python -m json.tool/<code>

返回值:

<code>{
"database": {
"reachable": true
},
"server": {
"connections_accepted": 111,
"connections_active": 1,
"connections_handled": 111,
"connections_reading": 0,
"connections_waiting": 0,
"connections_writing": 1,
"total_requests": 64
}
}/<code>

在返回的數據中,各個值的含義如下::

  • total_requests:客戶端請求的總數。
  • connections_active:當前活動客戶端連接數,包括等待連接。
  • connections_accepted:已接受的客戶端連接總數。
  • connections_handled:已處理連接的總數。通常,參數值與accept相同,除非已達到某些資源限制。
  • connections_reading:Kong正在讀取請求標頭的當前連接數。
  • connections_writing:nginx將響應寫回客戶端的當前連接數。
  • connections_waiting:等待請求的當前空閒客戶端連接數。

三、服務

服務是每一個後端真實接口的抽象,它與路由關聯,客戶端發起請求,如果路由匹配到了,那麼會將這個請求代理到與匹配路由相關聯的服務中。

1、添加服務

接口信息:

接口名稱添加服務

請求端點/services/請求方法POST返回狀態HTTP 201 Created

請求參數:

參數名類型默認值是否必須說明namestring否服務名稱,全局唯一protocolstringhttp是和上游通訊的協議取值http或httpshoststring是上游服務器的主機portint80是上游服務器的端口pathstring否上游服務器請求中的路徑,必須以/開頭retriesint5否代理失敗時要執行的重試次數connect_timeoutint60000否與上游連接的超時時間,單位毫秒write_timeoutint60000否向上遊發送請求兩次連續寫操作的超時時間 ,單位毫秒read_timeoutint60000否用於向上遊服務器發送請求的兩次連續讀取操作之間的超時 ,單位毫秒

請求示例:

<code>curl -s -X POST --url http://192.168.0.184:8001/services/ \\
-d 'name=linuxops_server' \\
-d 'protocol=http' \\
-d 'host=www.baidu.com'\\
| python -m json.tool/<code>

返回值:

<code>{
"connect_timeout": 60000,
"created_at": 1537924532,
"host": "www.baidu.com",
"id": "27f30248-fef1-4ddc-9fdc-4ca73f354c64",
"name": "linuxops_server",
"path": null,
"port": 80,

"protocol": "http",
"read_timeout": 60000,
"retries": 5,
"updated_at": 1537924532,
"write_timeout": 60000
}/<code>

如果在創建服務的時候沒有指定name,那麼Kong並不會自動創建name,但是會創建UUID形式的ID,Kong在調用、匹配等等的操作都是可以基於這個ID,所以這個ID絕對是全局唯一的。

在其他的對象管理中,name字段可能是必須的,通常這個name資源也是全局唯一的,即便如此,Kong也會創建ID字段,也可以通過這個ID字段來匹配。

在服務對象中,能組合起來成為上游服務也是唯一的,也就是說,在一個服務中無法同時存在 http和https,如果上游提供http和https服務,同時也需要Kong代理它們的話,那必須要設置兩個服務。

2、查詢服務

接口信息:

接口名稱查詢服務請求端點/services/{name or id}請求方法GET返回狀態HTTP 200 OK

請求參數:

請求示例:

<code>curl -s --url http://192.168.0.184:8001/services/27f30248-fef1-4ddc-9fdc-4ca73f354c64 | python -m json.tool/<code>

返回值:

<code>{
"connect_timeout": 60000,
"created_at": 1537986798,
"host": "www.baidu.com",
"id": "27f30248-fef1-4ddc-9fdc-4ca73f354c64",
"name": "linuxops_server",
"port": 80,
"protocol": "http",
"read_timeout": 60000,
"retries": 5,
"updated_at": 1537986798,
"write_timeout": 60000
}/<code>

查詢服務的接口我們可以通過id來查詢,也可以通過name來查詢,在創建服務的時候可以不指定name字段,在系統中顯示為null,這種服務就無法通過指定name來查詢了,必須要使用id來查詢,所以,強烈建議在創建服務的時候指定name,這是一個好習慣。

3、查詢所有服務

接口信息:

接口名稱查詢所有服務請求端點/services/請求方法GET返回狀態HTTP 200 OK

請求參數:

參數名類型默認值是否必須說明offsetstring否分頁偏移,用於定義列表中的唯一sizeint100否每頁返回的對象的數量

請求示例:

<code>curl -s --url http://192.168.0.184:8001/services/?size=1 | python -m json.tool/<code>

返回值:

<code>{
"data": [
{
"connect_timeout": 60000,
"created_at": 1537986798,
"host": "www.baidu.com",
"id": "27f30248-fef1-4ddc-9fdc-4ca73f354c64",
"name": "linuxops_server",
"path": null,
"port": 80,
"protocol": "http",
"read_timeout": 60000,
"retries": 5,
"updated_at": 1537986798,
"write_timeout": 60000
}
],
"next": "/services?offset=WyIyN2YzMDI0OC1mZWYxLTRkZGMtOWZkYy00Y2E3M2YzNTRjNjQiXQ",
"offset": "WyIyN2YzMDI0OC1mZWYxLTRkZGMtOWZkYy00Y2E3M2YzNTRjNjQiXQ"
}/<code>

在上面的請求示例中,我們帶了一個size的參數來限定每一頁的數量,在返回的結果中有兩個字段,next表示下一頁的端點,offset是本頁的偏移。

當然,如果你在讀取下一頁的時候還需要限定返回的數據,還是依然要使用size的參數

4、更新服務

接口信息:

接口名稱查詢所有服務請求端點/services/{name or id}請求方法PATCH返回狀態HTTP 200 OK

請求參數:

參數名類型默認值是否必須說明namestring否服務名稱,全局唯一protocolstringhttp是和上游通訊的協議取值http或httpshoststring是上游服務器的主機portint80是上游服務器的端口pathstring否上游服務器請求中的路徑,必須以/開頭retriesint5否代理失敗時要執行的重試次數connect_timeoutint60000否與上游連接的超時時間,單位毫秒write_timeoutint60000否向上遊發送請求兩次連續寫操作的超時時間 ,單位毫秒read_timeoutint60000否用於向上遊服務器發送請求的兩次連續讀取操作之間的超時 ,單位毫秒

請求示例:

<code>curl -s -X PATCH --url http://192.168.0.184:8001/services/linuxops_server \\
-d 'name=linuxops_server_patch' \\

-d 'protocol=http' \\
-d 'host=www.baidu.com' \\
| python -m json.tool/<code>

返回值:

<code>{
"connect_timeout": 60000,
"created_at": 1537986798,
"host": "www.baidu.com",
"id": "27f30248-fef1-4ddc-9fdc-4ca73f354c64",
"name": "linuxops_server_patch",
"path": null,
"port": 80,
"protocol": "http",
"read_timeout": 60000,
"retries": 5,
"updated_at": 1537989418,
"write_timeout": 60000
}/<code>

和查看服務的接口一樣,接入點是需要帶上id或者name的,只不過方法變成了PATCH,參數和添加的參數一樣。

在上面的示例中,我修改了一個服務的name,從返回值中可以可能出來id是不會變化的。

5、更新或者創建服務

接口信息:

接口名稱更新或者創建服務請求端點/services/{name or id}請求方法PUT返回狀態HTTP 201 Created or HTTP 200 OK

請求參數:

參數名類型默認值是否必須說明namestring否服務名稱,全局唯一protocolstringhttp是和上游通訊的協議取值http或httpshoststring是上游服務器的主機portint80是上游服務器的端口pathstring否上游服務器請求中的路徑,必須以/開頭retriesint5否代理失敗時要執行的重試次數connect_timeoutint60000否與上游連接的超時時間,單位毫秒write_timeoutint60000否向上遊發送請求兩次連續寫操作的超時時間 ,單位毫秒read_timeoutint60000否用於向上遊服務器發送請求的兩次連續讀取操作之間的超時 ,單位毫秒

請求示例:

<code>curl -s -X PUT --url http://192.168.0.184:8001/services/linuxops_server_put \\
-d 'name=linuxops_server_patch' \\
-d 'protocol=http' \\
-d 'host=www.baidu.com' \\
| python -m json.tool/<code>

返回值:

<code>{
"connect_timeout": 60000,
"created_at": 1537991524,
"host": "www.baidu.com",
"id": "7242306f-3a55-46b5-9cda-cfb6c25a421c",
"name": "linuxops_server_put",
"path": null,
"port": 80,
"protocol": "http",
"read_timeout": 60000,
"retries": 5,
"updated_at": 1537991524,

"write_timeout": 60000
}/<code>

這個接口是更新或者創建一個服務,接入點和查詢、更新是一樣的,不一樣的是用了PUT的方法。

此接口帶了{name or id},Kong會根據{name or id}的信息查詢數據庫,如果對應的數據存在,那麼更新,如果對於的數據不存在,那麼就新增。

在更新服務的接口中,我們也是可以帶{name or id},無論是帶了id還是name,服務中的name字段都是能被更新到的,但是這個接口就有點不一樣了。

有以下幾種情況:

1.如果這個接口帶的是name,例如/services/linuxops_server Kong會判斷name為”linuxops_server“的服務存不存在,如果存在,則更新,這個時候POST到Kong的數據中name字段無效,Kong並不會修改。 如果不存在”linuxops_server“這個服務存,那麼會創建name為"linuxops_server"的服務,並且Kong會生成UUID形式的id,此時POST上來的數據中的name字段依然無效。

2.如果這個接口帶的是id,例如/services/ca4f16bc-1562-4ab8-b201-131c7ac393f0 Kong會判斷id為"ca4f16bc-1562-4ab8-b201-131c7ac393f0"的服務是否存在,如果存在,那麼更新它,這個時候如果POST上來的數據中有name字段,那麼Kong會更新name。 如果id為"ca4f16bc-1562-4ab8-b201-131c7ac393f0"的服務不存在,那麼Kong會創建name為"ca4f16bc-1562-4ab8-b201-131c7ac393f0"的服務,並且Kong會生成UUID形式的id,這個時候POST上來的數據中如果有name字段,那麼這個字段無效。

6、刪除服務

接口信息:

接口名稱刪除服務請求端點/services/{name or id}請求方法DELETE返回狀態HTTP 204 No Content

請求參數:

請求示例:

<code>curl -i  -X DELETE --url http://192.168.0.184:8001/services/b6094754-07da-4c31-bb95-0a7caf5e6c0b/<code>

返回值:

此接口沒有返回值


四、路由

路由用來匹配客戶端請求的規則,每一個路由都要與一個服務相關聯,當一個請求到達Kong的時候,會先給路由匹配,如果匹配成功,那麼會將請求轉發給服務,服務再去後端請求數據。所以路由是Kong的入口。

在Kong0.13.0之前的版本有API實體,因為API實體使用用起來並不方便,所以將API實體拆分成路由和服務,這樣提供了最大的自由度。

Kong的一個API實體必須是路由和服務的組合。

1、添加路由

接口信息:

接口名稱添加路由請求端點/routes/請求方法POST返回狀態HTTP 201 Created

請求參數:

參數名類型默認值是否必須說明protocolsstring or list["http", "https"]否此路由允許的協議,取值http或httpsmethodsstring or listnull*否此路由允許的方法hostsstring or listnull*否此路由允許的域名pathsstring or listnull*否此路由匹配的pathstrip_pathbooltrue否匹配到path時,是否刪除匹配到的前綴preserve_hostboolfalse否匹配到hosts時,使用請求頭部的值為域名向後端發起請求,請求的頭部為"host",例如"host:api.abc.com"servicestring是關聯的服務id。
這裡需要特別注意,如果是以表達的形式發送的,需要以 service.id=<service>形式發送,如果是json,需要以"service":{"id":"<service>"}形式發送/<service>/<service>

請求示例:

<code>curl -s -X POST --url http://192.168.0.184:8001/routes \\
-d 'protocols=http' \\
-d 'methods=GET' \\
-d 'paths=/weather' \\
-d 'service.id=43921b23-65fc-4722-a4e0-99bf84e26593' \\
| python -m json.tool
/<code>

返回值:

<code>{
"created_at": 1538089234,
"hosts": null,
"id": "cce1a279-d05a-4faa-8c10-1f9d27b881c9",
"methods": [
"GET"
],
"paths": [
"/weather"
],
"preserve_host": false,
"protocols": [
"http"
],
"regex_priority": 0,
"service": {
"id": "43921b23-65fc-4722-a4e0-99bf84e26593"
},
"strip_path": true,
"updated_at": 1538089234
}
/<code>

在上面的示例中,我們創建了一個路由並且關聯了一個服務,在創建路由的時候並沒有指定hosts,路由匹配到host的時候會允許所有,因為默認值為null。當然如果不指定其他的也是一樣的。

值得注意的是,methods,hosts,paths這三個參數必須要指定一個,否則無法創建路由。

路由和服務組合的規則相對比較複雜,我們將會重新開一篇文章來專門講解這個,本文僅僅關注管理API的使用。

2、查看路由

接口信息:

接口名稱查看路由請求端點/routes/{id}請求方法GET返回狀態HTTP 200 OK

請求參數:

請求示例:

<code>curl -s http://192.168.0.184:8001/routes/6c6b7863-9a05-4d51-bf7e-8e4e5866a131 | python -m json.tool/<code>

返回值:

<code>{
"created_at": 1538089668,
"id": "6c6b7863-9a05-4d51-bf7e-8e4e5866a131",
"paths": [
"/weather"
],
"preserve_host": false,
"protocols": [
"http",
"https"
],
"regex_priority": 0,

"service": {
"id": "43921b23-65fc-4722-a4e0-99bf84e26593"
},
"strip_path": true,
"updated_at": 1538089668
}/<code>

路由中沒有name字段,所以只能通過ID來查看。

3、查詢所有路由

接口信息:

接口名稱查詢所有路由請求端點/routes請求方法GET返回狀態HTTP 200 OK

請求參數:

參數名類型默認值是否必須說明offsetstring否分頁偏移,用於定義列表中的唯一sizeint100否每頁返回的對象的數量

請求示例:

<code>curl -s --url http://192.168.0.184:8001/routes/?size=1 | python -m json.tool/<code>

返回值:

<code>{
"data": [
{

"created_at": 1538004899,
"hosts": [],
"id": "19377681-ba1c-43dc-9eb6-ff117467ce96",
"methods": [
"GET",
"POST"
],
"paths": [],
"preserve_host": false,
"protocols": [
"http",
"https"
],
"regex_priority": 0,
"service": {
"id": "43921b23-65fc-4722-a4e0-99bf84e26593"
},
"strip_path": true,
"updated_at": 1538071225
}
],
"next": "/routes?offset=WyIxOTM3NzY4MS1iYTFjLTQzZGMtOWViNi1mZjExNzQ2N2NlOTYiXQ",
"offset": "WyIxOTM3NzY4MS1iYTFjLTQzZGMtOWViNi1mZjExNzQ2N2NlOTYiXQ"
}
/<code>

在上面的請求示例中,我們帶了一個size的參數來限定每一頁的數量,在返回的結果中有兩個字段,next表示下一頁的端點,offset是本頁的偏移。

當然,如果你在讀取下一頁的時候還需要限定返回的數據,還是依然要使用size的參數

4、更新路由

接口信息:

接口名稱更新路由請求端點/routes/{id}請求方法PATCH返回狀態HTTP 200 OK

請求參數:

參數名類型默認值是否必須說明protocolsstring or list["http", "https"]否此路由允許的協議,取值http或httpsmethodsstring or listnull*否此路由允許的方法hostsstring or listnull*否此路由允許的域名pathsstring or listnull*否此路由匹配的pathstrip_pathbooltrue否匹配到path時,是否刪除匹配到的前綴preserve_hostboolfalse否匹配到hosts時,使用請求頭部的值為域名向後端發起請求,請求的頭部為"host",例如"host:api.abc.com"servicestring是關聯的服務id。
這裡需要特別注意,如果是以表達的形式發送的,需要以 service.id=<service>形式發送,如果是json,需要以"service":{"id":"<service>"}形式發送/<service>/<service>

請求示例:

<code>curl -s -X PATCH --url http://192.168.0.184:8001/routes/6c6b7863-9a05-4d51-bf7e-8e4e5866a131 \\
-d 'protocols=http' \\
-d 'methods=GET' \\
-d 'paths=/weather' \\
-d 'service.id=43921b23-65fc-4722-a4e0-99bf84e26593' \\
| python -m json.tool
/<code>

返回值:

<code>{
"created_at": 1538089668,
"hosts": null,
"id": "6c6b7863-9a05-4d51-bf7e-8e4e5866a131",
"methods": [
"GET"
],
"paths": [

"/weather"
],
"preserve_host": false,
"protocols": [
"http"
],
"regex_priority": 0,
"service": {
"id": "43921b23-65fc-4722-a4e0-99bf84e26593"
},
"strip_path": true,
"updated_at": 1538090658
}/<code>

此接口的參數和添加路由的參數一樣,接入點帶了路由的id,路由沒有name字段,所有的匹配都是以ID匹配的。

5、更新或者添加路由

接口信息:

接口名稱更新或者添加路由請求端點/routes/{id}請求方法PUT返回狀態HTTP 201 Created or HTTP 200 OK

請求參數:

參數名類型默認值是否必須說明protocolsstring or list["http", "https"]否此路由允許的協議,取值http或httpsmethodsstring or listnull*否此路由允許的方法hostsstring or listnull*否此路由允許的域名pathsstring or listnull*否此路由匹配的pathstrip_pathbooltrue否匹配到path時,是否刪除匹配到的前綴preserve_hostboolfalse否匹配到hosts時,使用請求頭部的值為域名向後端發起請求,請求的頭部為"host",例如"host:api.abc.com"servicestring是關聯的服務id。


這裡需要特別注意,如果是以表達的形式發送的,需要以 service.id=<service>形式發送,如果是json,需要以"service":{"id":"<service>"}形式發送/<service>/<service>

請求示例:

<code>curl -s -X PUT --url http://192.168.0.184:8001/routes/6c6b7863-9a05-4d51-bf7e-2962c1d6b0e6 \\
-d 'protocols=http' \\
-d 'methods=GET' \\
-d 'paths=/weather' \\
-d 'service.id=43921b23-65fc-4722-a4e0-99bf84e26593' \\
| python -m json.tool/<code>

返回值:

<code>{
"created_at": 1538091038,
"hosts": null,
"id": "6c6b7863-9a05-4d51-bf7e-2962c1d6b0e6",
"methods": [
"GET"
],
"paths": [
"/weather"
],
"preserve_host": false,
"protocols": [
"http"
],
"regex_priority": 0,
"service": {
"id": "43921b23-65fc-4722-a4e0-99bf84e26593"
},
"strip_path": true,
"updated_at": 1538091038
}
/<code>

此接口的參數和添加路由的參數一樣,接入點帶了路由的id,路由沒有name字段,所有的匹配都是以ID匹配的。

和服務的更新創建接口差不多,只不過路由沒有name的字段,所以匹配均是按照id來匹配,所以規則比較簡單:如果id存在則更新,如果id不存在則添加。

但是,此處的ID必須是UUID形式的ID,否則添加不成功。

6、查看和服務關聯的路由

接口信息:

接口名稱查看和服務關聯的路由請求端點/services/{service name or id}/routes請求方法GET返回狀態HTTP 200 OK

請求參數:

請求示例:

<code>curl -s http://192.168.0.184:8001/services/wechat/routes | python -m json.tool/<code>

返回值:

<code>{
"data": [
{
"created_at": 1538089623,
"id": "cdfee2bc-a5eb-4f80-96f5-64bfe3b85507",

"methods": [
"GET"
],
"preserve_host": false,
"protocols": [
"http",
"https"
],
"regex_priority": 0,
"service": {
"id": "43921b23-65fc-4722-a4e0-99bf84e26593"
},
"strip_path": true,
"updated_at": 1538089623
},
{
"created_at": 1538089397,
"id": "f8ef8876-9681-4629-a2ee-d7fac8a8094a",
"methods": [
"GET"
],
"paths": [
"/weather"
],
"preserve_host": false,
"protocols": [
"http",
"https"
],
"regex_priority": 0,
"service": {
"id": "43921b23-65fc-4722-a4e0-99bf84e26593"
},
"strip_path": true,
"updated_at": 1538089397
}
],
"next": null
}/<code>

7、查看和路由關聯的服務

接口信息:

接口名稱查看和路由關聯的服務

請求端點/routes/{route id}/service請求方法GET返回狀態HTTP 200 OK

請求參數:

請求示例:

<code>curl -s http://192.168.0.184:8001/routes/f8ef8876-9681-4629-a2ee-d7fac8a8094a/service | python -m json.tool/<code>

返回值:

<code>{
"connect_timeout": 60000,
"created_at": 1538000258,
"host": "t.weather.sojson.com",
"id": "43921b23-65fc-4722-a4e0-99bf84e26593",
"name": "wechat",
"path": "/api/weather/city/",
"port": 80,
"protocol": "http",
"read_timeout": 60000,
"retries": 5,
"updated_at": 1538005796,
"write_timeout": 60000
}/<code>

8、刪除路由

接口信息:

接口名稱刪除路由請求端點/routes/{id}請求方法DELETE返回狀態HTTP 204 No Content

請求參數:

請求示例:

<code>curl -s http://192.168.0.184:8001/routes/f8ef8876-9681-4629-a2ee-d7fac8a8094a/service | python -m json.tool/<code>

返回值:

此接口沒有返回值


五、用戶

1、添加用戶

接口信息:

接口名稱添加用戶請求端點/consumers/請求方法POST返回狀態HTTP 201 Created

請求參數:

參數名類型默認值是否必須說明usernamestringnull*否全局唯一的用戶名custom_idstringnull*否全局唯一的用戶ID

請求示例:

<code>curl -s -X POST --url http://192.168.0.184:8001/consumers  -d 'username=linuxops' | python -m json.tool/<code>

返回值:

<code>{
"created_at": 1538126090,
"custom_id": null,
"id": "376a9ccf-7d10-45a7-a956-77eb129d8ff0",
"username": "linuxops"
}/<code>

在上面示例中,我們指定了一個username來創建一個用戶,從返回值看出,如果沒有指定參數,那麼默認值為空。

在調用這個接口,必須要指定username 和 custom_id其中一個參數,不能同時不指定。

在創建用戶的時候,系統都將會生成一個UUID的形式的唯一ID。

2、查詢用戶

接口信息:

接口名稱查詢用戶請求端點/consumers/{username or id}請求方法GET返回狀態HTTP 200 OK

請求參數:

請求示例:

<code>curl -s http://192.168.0.184:8001/consumers/linuxops | python -m json.tool/<code>

返回值:

<code>{
"created_at": 1538126090,
"id": "376a9ccf-7d10-45a7-a956-77eb129d8ff0",
"username": "linuxops"
}
/<code>

查詢用戶只能通過系統ID和username來查詢,無法通過custom_id查詢

3、查詢所有用戶

接口信息:

接口名稱查詢所有用戶請求端點/consumers請求方法GET返回狀態HTTP 200 OK

請求參數:

參數名類型默認值是否必須說明offsetstring否分頁偏移,用於定義列表中的唯一sizeint100否每頁返回的對象的數量

請求示例:

<code>curl -s http://192.168.0.184:8001/consumers?size=1 | python -m json.tool/<code> 

返回值:

<code>{
"data": [
{
"created_at": 1538126090,
"custom_id": null,
"id": "376a9ccf-7d10-45a7-a956-77eb129d8ff0",
"username": "linuxops"
}
],
"next": "/consumers?offset=WyIzNzZhOWNjZi03ZDEwLTQ1YTctYTk1Ni03N2ViMTI5ZDhmZjAiXQ",
"offset": "WyIzNzZhOWNjZi03ZDEwLTQ1YTctYTk1Ni03N2ViMTI5ZDhmZjAiXQ"
}/<code>

在上面的請求示例中,我們帶了一個size的參數來限定每一頁的數量,在返回的結果中有兩個字段,next表示下一頁的端點,offset是本頁的偏移。

當然,如果你在讀取下一頁的時候還需要限定返回的數據,還是依然要使用size的參數

4、更新用戶

接口信息:

接口名稱更新用戶請求端點/consumers/{username or id}請求方法PATCH返回狀態HTTP 200 OK

請求參數:

參數名類型默認值是否必須說明usernamestringnull*否全局唯一的用戶名custom_idstringnull*否全局唯一的用戶ID

請求示例:

<code>curl -s -X PATCH --url http://192.168.0.184:8001/consumers/376a9ccf-7d10-45a7-a956-77eb129d8ff0 -d "custom_id=linuxops123456789" | python -m json.tool/<code>

返回值:

<code>{
"created_at": 1538126090,
"custom_id": "linuxops123456789",
"id": "376a9ccf-7d10-45a7-a956-77eb129d8ff0",
"username": "linuxops"
}/<code>

5、更新或者添加用戶

接口信息:

接口名稱更新或者添加用戶請求端點/consumers/{username or id}請求方法PUT返回狀態HTTP 201 Created or HTTP 200 OK

請求參數:

參數名類型默認值是否必須說明usernamestringnull*否全局唯一的用戶名custom_idstringnull*否全局唯一的用戶ID

請求示例:

<code>curl -s -X PUT --url http://192.168.0.184:8001/consumers/376a9ccf-7d10-45a7-a956-77eb129d8ff0 -d "custom_id=linuxops123456789" | python -m json.tool/<code>

返回值:

<code>{
"created_at": 1538127246,
"custom_id": "linuxops123456789",
"id": "376a9ccf-7d10-45a7-a956-77eb129d8ff0",
"username": null
}/<code>

這個接口和更新添加服務的接口類似,當{username or id}屬性具有UUID的結構時,插入/更新的Consumer將由其標識id。否則它將由它識別username。

6、刪除用戶

接口信息:

接口名稱刪除用戶請求端點/consumers/{username or id}請求方法DELETE返回狀態HTTP 204 No Content

請求參數:

請求示例:

<code>curl -i -X DELETE --url http://192.168.0.184:8001/consumers/376a9ccf-7d10-45a7-a956-77eb129d8ff0 /<code>

返回值:

此操作沒有返回值


六、插件

Kong提供了一個插件的功能,你可以通過配置指定某個服務或者路由或者用戶啟用某個插,插件始終只運行一次,所以對於不同的實體配置相同插件時就有優先級的概念。

多次配置插件的優先級如下:

  • 在以下組合上配置的插件:路由,服務和使用者。 (消費者意味著必須對請求進行身份驗證)。
  • 在Route和Consumer的組合上配置的插件。 (消費者意味著必須對請求進行身份驗證)。
  • 在服務和使用者的組合上配置的插件。 (消費者意味著必須對請求進行身份驗證)。
  • 在路由和服務的組合上配置的插件。
  • 在Consumer上配置的插件。 (消費者意味著必須對請求進行身份驗證)。
  • 在路由上配置的插件。
  • 在服務上配置的插件。
  • 配置為全局運行的插件。

從以上的優先級可以看出全局配置的插件優先級最小,而越具體的組合優先級越高。

1、添加插件

可以通過以下幾種不同的方式添加插件:

  • 對於每個Service/Route和consumer。不要設置consumer_id和設置service_id或route_id。
  • 適用於每個Service/Route和特定consumer。只有設定consumer_id。
  • 適用於每個consumer和特定Service。僅設置service_id(警告:某些插件只允許設置route_id)
  • 對於每個consumer和特定的Route。僅設置route_id(警告:某些插件只允許設置service_id)
  • 對於特定的Service/Route和consumer。設置兩個service_id/ route_id和consumer_id。

並非所有插件都允許指定consumer_id。檢查插件文檔。

接口信息:

接口名稱添加插件請求端點/plugins/請求方法POST返回狀態HTTP 201 Created

請求參數:

參數名類型默認值是否必須說明namestring是要添加的插件的名稱。目前,插件必須分別安裝在每個Kong實例中。consumer_idstringnull否使用者的唯一標識符,用於覆蓋傳入請求中此特定使用者的現有設置。service_idstringnull否服務的唯一標識符,用於覆蓋傳入請求中此特定服務的現有設置。route_idstringnull否路由的唯一標識符,它覆蓋傳入請求中此特定路由的現有設置。config.{property}stringnull否插件的配置屬性,可以在Kong Hub的插件文檔頁面找到。enabledbooltrue否是否應用插件。默認值:true。

請求示例:

<code>curl -s -X POST --url http://192.168.0.184:8001/plugins/ \\
-d 'name=basic-auth' \\
-d 'route_id=d1a10507-ea15-4c61-9d8c-7f10ebc79ecb' \\
| python -m json.tool/<code>

返回值:

<code>{
"config": {
"anonymous": "",
"hide_credentials": false
},
"created_at": 1540102452000,

"enabled": true,
"id": "900aeaa3-0a47-49a1-9fea-649e6c90ab7f",
"name": "basic-auth",
"route_id": "d1a10507-ea15-4c61-9d8c-7f10ebc79ecb"
}
/<code>

在上面的請求示例中,我們在route上添加了basic-auth插件,這個插件用於認證,通過http的頭部帶入用戶名和密碼信息進行認證。

當然,啟用插件後,我們要對user設置好basic-auth的憑證,否則訪問不了,並且返回如下信息:

<code>{
"message": "Unauthorized"
}/<code>

2、查詢插件

接口信息:

接口名稱查詢插件請求端點/plugins/{id}請求方法GET返回狀態HTTP 200 OK

請求參數:

參數名類型默認值是否必須說明idstring是要檢索的插件的唯一標識符

請求示例:

<code>curl -s  --url http://192.168.0.184:8001/plugins/900aeaa3-0a47-49a1-9fea-649e6c90ab7f  | python -m json.tool/<code>

返回值:

<code>{
"config": {
"anonymous": "",
"hide_credentials": false
},
"created_at": 1540102452000,
"enabled": true,
"id": "900aeaa3-0a47-49a1-9fea-649e6c90ab7f",
"name": "basic-auth",
"route_id": "d1a10507-ea15-4c61-9d8c-7f10ebc79ecb"
}
/<code>

3、查詢所有插件

接口信息:

接口名稱查詢所有插件請求端點/plugins/請求方法GET返回狀態HTTP 200 OK

請求參數:

參數名類型默認值是否必須說明idstring否通過id查詢namestring否通過name查service_idstring否通過service_id查route_idstring否通過iroute_id查consumer_idstring否通過consumer_id查offsetstring否分頁偏移,用於定義列表中的唯一sizeint100否每頁返回的對象的數量

請求示例:

<code>curl -s --url http://192.168.0.184:8001/plugins/?size=1 | python -m json.tool/<code>

返回值:

<code>{
"data": [
{
"config": {
"anonymous": "",
"hide_credentials": false
},
"created_at": 1540102452000,
"enabled": true,
"id": "900aeaa3-0a47-49a1-9fea-649e6c90ab7f",
"name": "basic-auth",
"route_id": "d1a10507-ea15-4c61-9d8c-7f10ebc79ecb"
}
],
"total": 1
}
/<code>

在上面的請求示例中,我們帶了一個size的參數來限定每一頁的數量,在返回的結果中有兩個字段,next表示下一頁的端點,offset是本頁的偏移。

當然,如果你在讀取下一頁的時候還需要限定返回的數據,還是依然要使用size的參數

4、更新插件

接口信息:

接口名稱更新插件

請求端點/plugins/{plugin id}請求方法PATCH返回狀態HTTP 200 OK

請求參數:

參數名類型默認值是否必須說明plugin idstring是要更新的插件配置的唯一標識符namestringnull否要添加的插件的名稱要添加的插件的名稱consumer_idstringnull否使用者的唯一標識符,用於覆蓋傳入請求中此特定使用者的現有設置。service_idstringnull否服務的唯一標識符,用於覆蓋傳入請求中此特定服務的現有設置。route_idstringnull否路由的唯一標識符,它覆蓋傳入請求中此特定路由的現有設置。config.{property}stringnull否插件的配置屬性,可以在Kong Hub的插件文檔頁面找到。enabledbooltrue否是否應用插件。

請求示例:

<code>curl -s -X PATCH --url http://192.168.0.184:8001/plugins/900aeaa3-0a47-49a1-9fea-649e6c90ab7f -d "service_id=da4dce88-4df3-4723-b544-b11b27184e97" | python -m json.tool/<code>

返回值:

<code>{
"config": {
"anonymous": "",
"hide_credentials": false
},
"created_at": 1540102452000,
"enabled": true,
"id": "900aeaa3-0a47-49a1-9fea-649e6c90ab7f",
"name": "basic-auth",
"route_id": "d1a10507-ea15-4c61-9d8c-7f10ebc79ecb",
"service_id": "da4dce88-4df3-4723-b544-b11b27184e97"

}
/<code>

在上面的請求示例中,我更新了這個插件,原本只針對route啟用的,現在又增加了對service生效,由此看出,一個插件是可以對多個實體生效的(前提是插件本身要支持此實體生效),因為插件只會在請求的生命週期中運行一次,所以對多個實體啟用同一個插件會受到優先級的限制。

5、更新或添加插件

接口信息:

接口名稱更新或添加插件請求端點/plugins/請求方法PUT返回狀態HTTP 201 Created or HTTP 200 OK

請求參數:

參數名類型默認值是否必須說明namestringnull否要添加的插件的名稱要添加的插件的名稱consumer_idstringnull否使用者的唯一標識符,用於覆蓋傳入請求中此特定使用者的現有設置。service_idstringnull否服務的唯一標識符,用於覆蓋傳入請求中此特定服務的現有設置。route_idstringnull否路由的唯一標識符,它覆蓋傳入請求中此特定路由的現有設置。config.{property}stringnull否插件的配置屬性,可以在Kong Hub的插件文檔頁面找到。enabledbooltrue否是否應用插件。

請求示例:

<code>curl -s -X PUT --url http://192.168.0.184:8001/plugins/900aeaa3-0a47-49a1-9fea-649e6c90ab7f -d "service_id=da4dce88-4df3-4723-b544-b11b27184e97" | python -m json.tool/<code>

返回值:

<code>{
"config": {
"anonymous": "",
"hide_credentials": false
},
"created_at": 1540102452000,
"enabled": true,
"id": "900aeaa3-0a47-49a1-9fea-649e6c90ab7f",
"name": "basic-auth",
"route_id": "d1a10507-ea15-4c61-9d8c-7f10ebc79ecb",
"service_id": "da4dce88-4df3-4723-b544-b11b27184e97"
}
/<code>

這個接口是更新或者創建一個插件。

如果傳入的參數name已經存在,那麼以傳入的參數修改此插件,如果name不存在,則以傳入的參數創建此插件。

6、刪除插件

接口信息:

接口名稱刪除插件請求端點/plugins/{plugin id}請求方法DELETE返回狀態HTTP 204 No Content

請求參數:

參數名類型默認值是否必須說明plugin idstring是要刪除的插件配置的唯一標識符

請求示例:

<code>curl -s -X DELETE --url http://192.168.0.184:8001/plugins/900aeaa3-0a47-49a1-9fea-649e6c90ab7f | python -m json.tool/<code>

返回值:

此操作沒有返回值

7、查詢已啟用的插件

接口信息:

接口名稱查詢已啟用的插件請求端點/plugins/enabled請求方法GET返回狀態HTTP 200 OK

請求參數:

請求示例:

<code>curl -s -X GET --url http://192.168.0.184:8001/plugins/enabled | python -m json.tool/<code>

返回值:

<code>{
"enabled_plugins": [
"response-transformer",
"oauth2",
"acl",
"correlation-id",
"pre-function",
"jwt",
"cors",
"ip-restriction",
"basic-auth",
"key-auth",
"rate-limiting",
"request-transformer",
"http-log",
"file-log",
"hmac-auth",
"ldap-auth",
"datadog",
"tcp-log",
"zipkin",
"post-function",
"request-size-limiting",
"bot-detection",
"syslog",
"loggly",
"azure-functions",
"udp-log",
"response-ratelimiting",
"aws-lambda",
"statsd",
"prometheus",
"request-termination"
]
}/<code>

返回Kong示例啟用了那些插件,只有已經啟用的插件才能被應用在實體上,需要說明的是,在kong集群中,插件啟用的情況要一致。

8、檢索插件架構

接口信息:

接口名稱檢索插件架構請求端點/plugins/schema/{plugin name}請求方法GET返回狀態HTTP 200 OK

請求參數:

請求示例:

<code>curl -s -X GET --url http://192.168.0.184:8001/plugins/schema/basic-auth | python -m json.tool/<code>

返回值:

<code>{
"fields": {
"anonymous": {
"default": "",
"func": "function",
"type": "string"
},
"hide_credentials": {
"default": false,
"type": "boolean"
}
},
"no_consumer": true
}
/<code>

可以通過此接口瞭解插件接受哪些字段。


Kong API Gateway 管理API詳解


分享到:


相關文章: