部署好kong之後,則需要将我們自己的接口加入到kong中管理,kong提供了比較全面的restful api,每個版本會有所不同,下面的記錄基于kong v0.13.x
kong的8001端口是resful admin api,服務、路由、配置都是通過這個端口進行管理,是以部署好之後頁面可以直接通路localhost:8001
下面針對每個子產品的API進行簡介,每個對象子產品對應資料庫中的一張存儲表。
Information Routes
擷取kong節點的通用詳細資訊
管理API的請求日志路徑
/usr/local/opt/kong/logs
.
├── access.log
├── admin_access.log #admin-api請求日志
└── error.log
查詢節點資訊
Example
curl http://localhost:8001
Endpoint
GET /
Response
{
"plugins": {
"enabled_in_cluster": [],
"available_on_server": {
"response-transformer": true,
"correlation-id": true,
"statsd": true,
"jwt": true,
"cors": true,
"basic-auth": true,
"key-auth": true,
"ldap-auth": true,
"http-log": true,
"oauth2": true,
"hmac-auth": true,
"acl": true,
"datadog": true,
"tcp-log": true,
"ip-restriction": true,
"request-transformer": true,
"file-log": true,
"bot-detection": true,
"loggly": true,
"request-size-limiting": true,
"syslog": true,
"udp-log": true,
"response-ratelimiting": true,
"aws-lambda": true,
"runscope": true,
"rate-limiting": true,
"request-termination": true
}
},
"tagline": "Welcome to kong",
"configuration": {
"error_default_type": "text/plain",
"admin_listen": [
"0.0.0.0:8001"
],
"proxy_access_log": "logs/access.log",
"trusted_ips": {},
"prefix": "/usr/local/opt/kong",
"nginx_conf": "/usr/local/opt/kong/nginx.conf",
"cassandra_username": "kong",
"admin_ssl_cert_csr_default": "/usr/local/opt/kong/ssl/admin-kong-default.csr",
"dns_resolver": {},
"pg_user": "kong",
"mem_cache_size": "128m",
"server_tokens": true,
"custom_plugins": {},
"pg_host": "127.0.0.1",
"nginx_acc_logs": "/usr/local/opt/kong/logs/access.log",
"proxy_listen": [
"0.0.0.0:8000"
],
"client_ssl_cert_default": "/usr/local/opt/kong/ssl/kong-default.crt",
"ssl_cert_key_default": "/usr/local/opt/kong/ssl/kong-default.key",
"db_update_frequency": 5,
"db_update_propagation": 0,
"nginx_err_logs": "/usr/local/opt/kong/logs/error.log",
"cassandra_port": 9042,
"dns_order": [
"LAST",
"SRV",
"A",
"CNAME"
],
"dns_error_ttl": 1,
"cassandra_lb_policy": "RoundRobin",
"nginx_optimizations": true,
"database": "postgres",
"pg_database": "kong",
"nginx_worker_processes": "auto",
"lua_package_cpath": "",
"lua_package_path": "./?.lua;./?/init.lua;",
"nginx_pid": "/usr/local/opt/kong/pids/nginx.pid",
"upstream_keepalive": 60,
"admin_access_log": "logs/admin_access.log",
"client_ssl_cert_csr_default": "/usr/local/opt/kong/ssl/kong-default.csr",
"proxy_listeners": [{
"ssl": false,
"ip": "0.0.0.0",
"proxy_protocol": false,
"port": 8000,
"http2": false,
"listener": "0.0.0.0:8000"
}],
"proxy_ssl_enabled": false,
"lua_socket_pool_size": 30,
"plugins": {
"response-transformer": true,
"correlation-id": true,
"statsd": true,
"jwt": true,
"cors": true,
"basic-auth": true,
"key-auth": true,
"ldap-auth": true,
"http-log": true,
"request-termination": true,
"hmac-auth": true,
"rate-limiting": true,
"datadog": true,
"tcp-log": true,
"runscope": true,
"aws-lambda": true,
"response-ratelimiting": true,
"acl": true,
"loggly": true,
"syslog": true,
"request-size-limiting": true,
"udp-log": true,
"file-log": true,
"request-transformer": true,
"bot-detection": true,
"ip-restriction": true,
"oauth2": true
},
"lua_ssl_verify_depth": 1,
"cassandra_consistency": "ONE",
"client_max_body_size": "0",
"admin_error_log": "logs/error.log",
"admin_ssl_cert_default": "/usr/local/opt/kong/ssl/admin-kong-default.crt",
"dns_not_found_ttl": 30,
"pg_ssl": false,
"admin_ssl_enabled": false,
"cassandra_ssl": false,
"cassandra_repl_strategy": "SimpleStrategy",
"latency_tokens": true,
"dns_stale_ttl": 4,
"cassandra_repl_factor": 1,
"cassandra_data_centers": [
"dc1:2",
"dc2:3"
],
"kong_env": "/usr/local/opt/kong/.kong_env",
"cassandra_schema_consensus_timeout": 10000,
"dns_hostsfile": "/etc/hosts",
"log_level": "notice",
"admin_ssl_cert_key_default": "/usr/local/opt/kong/ssl/admin-kong-default.key",
"real_ip_header": "X-Real-IP",
"db_cache_ttl": 3600,
"cassandra_timeout": 5000,
"cassandra_ssl_verify": false,
"dns_no_sync": false,
"cassandra_contact_points": [
"127.0.0.1"
],
"real_ip_recursive": "off",
"proxy_error_log": "logs/error.log",
"client_ssl_cert_key_default": "/usr/local/opt/kong/ssl/kong-default.key",
"nginx_daemon": "on",
"anonymous_reports": true,
"ssl_cipher_suite": "modern",
"nginx_kong_conf": "/usr/local/opt/kong/nginx-kong.conf",
"pg_port": 5432,
"pg_ssl_verify": false,
"client_body_buffer_size": "8k",
"nginx_admin_acc_logs": "/usr/local/opt/kong/logs/admin_access.log",
"ssl_cert_csr_default": "/usr/local/opt/kong/ssl/kong-default.csr",
"admin_listeners": [{
"ssl": false,
"ip": "0.0.0.0",
"proxy_protocol": false,
"port": 8001,
"http2": false,
"listener": "0.0.0.0:8001"
}],
"cassandra_keyspace": "kong",
"ssl_cert_default": "/usr/local/opt/kong/ssl/kong-default.crt",
"client_ssl": false,
"ssl_ciphers": "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256"
},
"version": "0.13.1",
"node_id": "e9ca18fb-a82c-4730-83a1-621ceadc3c38",
"lua_version": "LuaJIT 2.1.0-beta3",
"prng_seeds": {
"pid: 752": 149231181689,
"pid: 751": 159113818774,
"pid: 750": 702104292191,
"pid: 753": 191164118531
},
"timers": {
"pending": 5,
"running": 0
},
"hostname": "jeandeMacBook-Pro.local"
}
View Code
部分傳回字段含義:
node_id : 正在運作的kong節點的uuid,當kong啟動時随機生成,每次kong重新開機時這個uuid都會變
availabel_on_server : kong節點上安裝的plugins的名稱
enabled_in_cluster : kong節點中啟用的插件,即在資料庫中生成了對應存儲表
查詢節點狀态
curl http://localhost:8001/status
GET /status
{
"database": {
"reachable": true
},
"server": {
"connections_writing": 1,
"total_requests": 29,
"connections_handled": 32,
"connections_accepted": 32,
"connections_reading": 0,
"connections_active": 3,
"connections_waiting": 2
}
}
total_requests : 用戶端請求總數
connections_active : 包括等待連接配接的活動用戶端連接配接的目前數量
connections_accepted : 接受的用戶端連接配接的總數
connections_handled : 處理連接配接的總數。一般來說,除非達到一定的資源限制,否則參數值與接受值相同
connections_reading : 目前Kong正在讀取請求頭的連接配接數
connections_writing : NGINX将響應寫入用戶端的連接配接的目前數量
connections_waiting : 等待請求的空閑用戶端連接配接的目前數量
reachable : 反映資料庫連接配接狀态的布爾值。注意,此标志不反映資料庫本身的健康狀況。
API Object
kong v0.13.x之前的版本是通過這個接口來管理使用者接入的API,但是v0.13.x版本之後,官方不建議使用API來管理使用者接口,而是用Service和Route子產品來替代,管理的更精細。
KONG API子產品管理的是接入kong的上遊API,每個接入的api必須至少指定hosts/uris/methods其中一個參數,kong将會代理所有指定upstream url的請求。
新增一個接入的API
curl -i -X POST \
--url http://localhost:8001/apis/ \
--data 'name=weather-api' \
--data 'hosts=www.sojson.com' \
--data 'uris=/weather' \
--data 'upstream_url=https://www.sojson.com/open/api/weather/json.shtml'
POST /apis/
Request Body
屬性 | 限制 | 描述 |
name | required | 接入的API名稱 |
hosts | semi-optional | 逗号分割的接入API的域名清單 |
uris | 逗号分割的接入API的字首path,即指定uri使用者通過kong剛問要加上這個path | |
methods | 逗号分割的接入API的HTTP method,如get /post/ put/delete/.. | |
upstream_url | 代理的上遊API Server | |
strip_uri | optional,default:true | 當比對到uris字首時,去掉請求的upstream_url中比對的uris;即uris是挂載在kong的路徑下,不是上遊接口的path |
preserve_host | optional,default:false | Kong預設将上遊請求的Host頭設定為從API的upstream_url中提取的主機名,當通過hosts來比對API時,確定hosts能轉發到上遊服務 |
retries | optional,default:5 | 代理失敗時重試的次數 |
upstream_connect_timeout | optional,default:60000ms | 建立與上遊連接配接的逾時時間(ms) |
upstream_send_timeout | 在發送請求到上遊服務的兩個連續寫入操作之間的逾時時間(ms) | |
upstream_read_timeout | 在發送請求到上遊服務的兩個連續讀取操作之間的逾時時間(ms) | |
https_only | 如果希望僅通過HTTPS轉發API(預設8443端口),則啟用 | |
http_if_terminated | 僅在https限流時才考慮設定X-Forwarded-Proto頭部 |
Response
HTTP/1.1 201 Created
Date: Sat, 26 May 2018 07:54:34 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Access-Control-Allow-Origin: *
Server: kong/0.13.1
{
"created_at": 1527350074050,
"strip_uri": true,
"id": "c347a69e-d81e-402b-87b0-c8cf25a771e5",
"hosts": ["www.sojson.com"],
"name": "weather-api",
"uris": ["\/weather"],
"http_if_terminated": false,
"preserve_host": false,
"upstream_url": "https://www.sojson.com/open/api/weather/json.shtml",
"upstream_connect_timeout": 60000,
"upstream_send_timeout": 60000,
"upstream_read_timeout": 60000,
"retries": 5,
"https_only": false
}
上面接口到意思是:這個API注冊的名字叫weather-api。它被挂載在網關的
/weather
路徑下,上遊轉發到
http://localhost:8000
去處理,轉發的時候把前面的
/weather
字首給去掉。
注意uris必須加slash /,預設是/ strip_uri到作用也很明顯,就是在代理下面劃分虛拟路徑便于管理
新增好API後則可以通過kong代理來通路代理的服務
# 原接口
curl https://www.sojson.com/open/api/weather/json.shtml?city=上海
#通過kong代理通路
curl -i -X GET \
--header 'host:www.sojson.com' \
--url http://localhost:8000/weather?city=上海
根據name或id擷取一個API
curl -i -X GET \
--url http://localhost:8001/apis/weather-api
或
curl -i -X GET \
--url http://localhost:8001/apis/c347a69e-d81e-402b-87b0-c8cf25a771e5
GET /apis/{name or id}
Request Params
name or id | 接入API到唯一辨別符,name或者id |
HTTP/1.1 200 OK
Date: Sat, 26 May 2018 08:18:43 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Access-Control-Allow-Origin: *
Server: kong/0.13.1
{
"created_at": 1527350074050,
"strip_uri": true,
"id": "c347a69e-d81e-402b-87b0-c8cf25a771e5",
"hosts": ["www.sojson.com"],
"name": "weather-api",
"uris": ["\/weather"],
"http_if_terminated": false,
"preserve_host": false,
"upstream_url": "https://www.sojson.com/open/api/weather/json.shtml",
"upstream_connect_timeout": 60000,
"upstream_send_timeout": 60000,
"upstream_read_timeout": 60000,
"retries": 5,
"https_only": false
}
查詢所有接入到API清單
curl -i -X GET --url http://localhost:8001/apis/
GET /apis/
Request Querystring
id | optional | 同post描述 |
size | limit,查詢的記錄條數 | |
offset | cursor位置,用于分頁 |
HTTP/1.1 200 OK
Date: Sat, 26 May 2018 08:25:33 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Access-Control-Allow-Origin: *
Server: kong/0.13.1
{
"total": 1,
"data": [{
"created_at": 1527350717171,
"strip_uri": true,
"id": "b93fcbe7-5dba-4888-bf8c-f4c8f798b53a",
"hosts": ["www.sojson.com"],
"name": "weather-api",
"http_if_terminated": false,
"https_only": false,
"retries": 5,
"uris": ["\/weather"],
"preserve_host": false,
"upstream_connect_timeout": 60000,
"upstream_read_timeout": 60000,
"upstream_send_timeout": 60000,
"upstream_url": "https://www.sojson.com/open/api/weather/json.shtml"
}]
}
根據name或id更新一個API
curl -i -X PATCH \
--url http://localhost:8001/apis/weather-api \
--data 'name=weather-api-1' \
--data 'retries=6'
或
curl -i -X PATCH \
--url 'http://localhost:8001/apis/b93fcbe7-5dba-4888-bf8c-f4c8f798b53a' \
--data 'name=weather-api-1' \
--data 'retries=6'
PATCH /apis/{name or id}
Request Param
同GET /apis/{name or id}
同POST /apis/
同GET /apis/{name or id},傳回的是更新後的資料
更新或新增一個API
#更新一個存在的API
curl -i -X PUT \
--url http://localhost:8001/apis/ \
--data 'id=b93fcbe7-5dba-4888-bf8c-f4c8f798b53a' \
--data 'hosts=www.sojson.com' \
--data 'uris=/weather' \
--data 'upstream_url=https://www.sojson.com/open/api/weather/json.shtml'
#更新一個不存在的API
curl -i -X PUT \
--url http://localhost:8001/apis/ \
--data 'name=test' \
--data 'hosts=www.sojson.com' \
--data 'uris=/weather' \
--data 'upstream_url=https://www.sojson.com/open/api/weather/json.shtml'
#新增
curl -i -X PUT \
--url http://localhost:8001/apis/ \
--data 'hosts=www.sojson.com' \
--data 'upstream_url=https://www.sojson.com/open/api/weather/json.shtml'
PUT接口的含義是:
如果request body中包含已有的API的主鍵(name or id),則會根據name or id 執行更新操作,同PATCH /apis/{name or id};
如果指定了name or id但是沒有查詢到該記錄,則傳回404 NOT FOUND;
如果沒有指定主鍵,則會新增一個API,同POST /apis/。
PUT /apis/
同 POST /apis/
HTTP 201 Created or HTTP 200 OK
傳回資料同POST or PATCH reponses
根據name或id删除一個API
curl -i -X DELETE \
--url http://localhost:8001/apis/weather-api
或
curl -i -X DELETE \
--url http://localhost:8001/apis/b93fcbe7-5dba-4888-bf8c-f4c8f798b53a
DELETE /apis/{name or id}
同 GET /apis/{name or id}
HTTP/1.1 204 No Content
Date: Sat, 26 May 2018 08:52:15 GMT
Connection: keep-alive
Access-Control-Allow-Origin: *
Server: kong/0.13.1
Service Object
服務是上遊服務中的每一個抽象,服務的主要屬性是url,它可以被設定為單個字元串或單獨指定它的 protocol、host、port and path。服務與路由相關(一個服務可以關聯多個路由),路由是Kong中的入口點,并定義與用戶端請求比對的規則。一旦路由比對,Kong将請求委托給其關聯的服務。
新增一個Service
curl -i -X POST \
--url http://localhost:8001/services/ \
--data 'name=service-stock' \
--data 'url=http://hq.sinajs.cn'
或
curl -i -X POST \
--url http://localhost:8001/services/ \
--data 'name=service-stock' \
--data 'protocal=http' \
--data 'host=hq.sinajs.cn' \
--data 'port=80'
POST /services/
服務名稱 | ||
protocol | required,default:http | 用于與上遊接口通信的協定。是http或https |
host | 上遊服務的host | |
port | required,default:80 | 上遊服務的端口 |
path | optional,default:null | 請求上遊伺服器使用的路徑,預設為空 |
connect_timeout | 建立與上遊伺服器連接配接的逾時時間(ms) | |
write_timeout | 在向上遊伺服器發送請求的兩個連續寫入操作之間的逾時時間(ms) | |
read_timeout | 在向上遊伺服器發送請求的兩個連續讀取操作之間的逾時時間(ms) | |
url | shorthand-attribute | 一次性設定protocol、host、port和path的縮寫。此屬性是隻讀的(管理API不會傳回“URL”) |
注:可用url來代替同時指定protocal/host/port/path,但url不會出現在傳回字段中。
HTTP/1.1 201 Created
Date: Sat, 26 May 2018 16:44:39 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Access-Control-Allow-Origin: *
Server: kong/0.13.1
{
"host": "hq.sinajs.cn",
"created_at": 1527324279,
"connect_timeout": 60000,
"id": "9ec3c166-f29a-4b04-a33e-c17ac42a3429",
"protocol": "http",
"name": "service-stock",
"read_timeout": 60000,
"port": 80,
"path": null,
"updated_at": 1527324279,
"retries": 5,
"write_timeout": 60000
}
根據name或id查詢一個Service
curl -i -X GET \
--url http://localhost:8001/services/service-stock
GET /services/{name or id}
name or id | 服務的唯一辨別符 |
HTTP/1.1 200 OK
Date: Sat, 26 May 2018 16:50:41 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Access-Control-Allow-Origin: *
Server: kong/0.13.1
{
"host": "hq.sinajs.cn",
"created_at": 1527324279,
"connect_timeout": 60000,
"id": "9ec3c166-f29a-4b04-a33e-c17ac42a3429",
"protocol": "http",
"name": "service-stock",
"read_timeout": 60000,
"port": 80,
"path": null,
"updated_at": 1527324279,
"retries": 5,
"write_timeout": 60000
}
根據route_id擷取一個服務
curl -i -X GET \
--url http://localhost:8001/routes/{ROUTE_ID}/service
GET /routes/{route id}/service
route id | 屬于要檢索的服務的路由的唯一辨別符 |
同 GET/services/{name or id}傳回結果
查詢所有服務清單
curl -i -X GET \
--url http://localhost:8001/services/
GET /services/
Request QueryString
分頁的遊标。offset是定義清單中某個位置的對象辨別符 | ||
optional,default :100, max:1000 | 每頁傳回的記錄數量 |
HTTP/1.1 200 OK
Date: Sat, 26 May 2018 17:05:39 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Access-Control-Allow-Origin: *
Server: kong/0.13.1
{
"next": "http://localhost:8001/services?offset=6378122c-a0a1-438d-a5c6-efabae9fb969",
"data": [{
"host": "hq.sinajs.cn",
"created_at": 1527324279,
"connect_timeout": 60000,
"id": "9ec3c166-f29a-4b04-a33e-c17ac42a3429",
"protocol": "http",
"name": "service-stock",
"read_timeout": 60000,
"port": 80,
"path": null,
"updated_at": 1527324279,
"retries": 5,
"write_timeout": 60000
}]
}
根據name或id更新服務
curl -i -X PATCH \
--url http://localhost:8001/services/service-stock \
--data 'name=service-stock-1' \
--data 'retries=6'
或
curl -i -X PATCH \
--url 'http://localhost:8001/apis/9ec3c166-f29a-4b04-a33e-c17ac42a3429' \
--data 'name=service-stock-1' \
--data 'retries=6'
PATCH /services/{name or id}
Requst Body
同POST /services/ Request Body
同 PATCH /apis/{name or id} 傳回結構
根據route_id更新服務
PATCH /routes/{route id}/service
其它同PATCH /services/{name or id}
根據name或id删除服務
DELETE /services/{name or id}
Route Object
路由定義比對用戶端請求的規則,每個路由與服務相關聯,并且一個服務可關聯多個路由。比對給定路由的每個請求将被代理到與其關聯的服務。路由和服務的組合和分離提供了一種強大的路由機制,通過它可以在Kong定義細粒度的入口點,進而通路基礎設施的不同上遊服務。
新增一個路由
curl -i -X POST \
--url http://localhost:8001/routes/ \
--data 'protocols[]=http&protocols[]=https' \
--data 'hosts[]=hq.sinajs.cn' \
--data 'service.id=9ec3c166-f29a-4b04-a33e-c17ac42a3429'
POST /routes/
protocols | required,default:["http", "https"] | 此路由應允許的協定清單。 當設定為[ HTTPS ]時,HTTP請求将被請求更新到HTTPS。使用form-encoded,符号是protocols[]=http&protocols[]=https。 使用數組 |
與此路由比對的HTTP方法清單。例如["GET", "POST"]。必須設定hosts、paths或methods中的至少一個。使用form-encode,符号是methods[]=GET和methods[]=OPTIONS。使用數組。 | ||
與此路由比對的域名清單。例如:example.com。使用form-encode,符号是hosts[]= Foo.com和hosts[]= BAR.com。使用數組 | ||
paths | 與此路由比對的路徑清單。例如:/my-path。使用form-encode,符号是paths[]=/foo&paths[]=/bar。使用數組。 | |
strip_path | 當通過路徑之一比對路由時,從上遊請求URL中去除比對的字首。 | |
當通過主機域名中的一個比對路由時,在上遊請求報頭中使用請求主機頭。預設情況下設定為false,上遊主機頭将設定為服務的主機。 | ||
service | 此路由關聯的服務。這是路由代理流量的地方。使用form-encode,符号是service.id=<service_id>。使用JSON則是"service":{"id":"<service_id>"} |
HTTP/1.1 201 Created
Date: Sun, 27 May 2018 07:29:32 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Access-Control-Allow-Origin: *
Server: kong/0.13.1
{
"created_at": 1527377372,
"strip_path": true,
"hosts": ["hq.sinajs.cn"],
"preserve_host": false,
"regex_priority": 0,
"updated_at": 1527377372,
"paths": null,
"service": {
"id": "9ec3c166-f29a-4b04-a33e-c17ac42a3429"
},
"methods": null,
"protocols": ["http", "https"],
"id": "9e9ff7b8-776f-4e65-ad2b-ed977e3fe4ea"
}
這裡添加了一個路由,也關聯了服務,則可以通過kong 代理來通路原服務-擷取股票資訊
#原接口
curl http://hq.sinajs.cn/list=sh601006
#通過kong代理通路
curl 127.0.0.1:8000/list=sh601006 --header 'host:hq.sinajs.cn'
傳回的結果都是
var hq_str_sh601006="大秦鐵路,8.440,8.440,8.380,8.460,8.350,8.390,8.400,29185760,245088749.000,1900,8.390,126300,8.380,72700,8.370,119700,8.360,332000,8.350,116278,8.400,104796,8.410,126800,8.420,128500,8.430,148100,8.440,2018-05-25,15:00:00,00";
根據route_id查詢路由
curl -i -X GET \
--url http://localhost:8001/routes/9e9ff7b8-776f-4e65-ad2b-ed977e3fe4ea
GET /routes/{id}
路由的唯一辨別符 |
傳回同 GET /service/{id}傳回結構
查詢所有路由清單
curl -i -X GET --url http://localhost:8001/routes/
EndPoint
GET /routes
用于分頁的遊标。偏移量是定義清單中某個位置的對象辨別符。 | ||
optional,default: 100, max:1000 | 每頁傳回數量的限制 |
HTTP/1.1 200 OK
Date: Sun, 27 May 2018 07:57:50 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Access-Control-Allow-Origin: *
Server: kong/0.13.1
{
"next": null,
"data": [{
"created_at": 1527378066,
"strip_path": true,
"hosts": ["hq.sinajs.cn"],
"preserve_host": false,
"regex_priority": 0,
"updated_at": 1527378066,
"paths": null,
"service": {
"id": "9ec3c166-f29a-4b04-a33e-c17ac42a3429"
},
"methods": null,
"protocols": ["http", "https"],
"id": "9e9ff7b8-776f-4e65-ad2b-ed977e3fe4ea"
}]
}
查詢一個服務關聯的所有路由
curl -i -X GET \
--url http://localhost:8001/services/9ec3c166-f29a-4b04-a33e-c17ac42a3429/routes
GET /services/{service name or id}/routes
Request QueryString Param
service name or id | 路由關聯的服務的唯一ID或name |
結構同 GET /routes
根據route_id更新指定路由
PATCH /routes/{id}
同 GET /routes/{id}
同 POST /routes
根據route_id删除路由
DELETE /routes/{id}
其它同前面
Consumer Object
消費對象表示服務的消費者或使用者。可以依賴Kong作為主要資料存儲,也可以将使用者自己管理的清單映射到該資料庫consumer表,以保持Kong與現有主資料存儲的一緻性。權限控制也會依賴這個表。
建立一個消費者
curl -i -X POST \
--url http://localhost:8001/consumers/ \
--data 'username=zhou' \
--data 'custom_id=000150'
POST /consumers/
username | 消費者的唯一使用者名,和custom_id至少有一個必須指定 | |
custom_id | 使用者存儲的唯一id, 用來和現有資料庫中的使用者一一映射,若需要權限管理,必須将此字段或使用者名與請求一起發送。 |
HTTP/1.1 201 Created
Date: Sun, 27 May 2018 08:31:20 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Access-Control-Allow-Origin: *
Server: kong/0.13.1
{
"custom_id": "000150",
"created_at": 1527409880000,
"username": "zhou",
"id": "a1866101-c718-421d-ace3-911042661eca"
}
查詢消費者清單
curl -i -X GET \
--url http://localhost:8001/consumers/zhou
或
curl -i -X GET \
--url http://localhost:8001/consumers/a1866101-c718-421d-ace3-911042661eca
GET /consumers/{username or id}
查詢所有消費者
GET /consumers/
optional,default:100 | 每頁傳回數量 | |
用于分頁的遊标。偏移量是定義清單中某個位置的對象辨別符 |
HTTP/1.1 200 OK
Date: Sun, 27 May 2018 08:39:40 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Access-Control-Allow-Origin: *
Server: kong/0.13.1
{
"total": 1,
"data": [{
"custom_id": "000150",
"created_at": 1527409880000,
"username": "zhou",
"id": "a1866101-c718-421d-ace3-911042661eca"
}]
}
更新指定消費者
PATCH /consumers/{username or id}
username or id |
同POST body說明 | ||
custome_id |
更新或建立消費者
PUT /consumers/
同上 Request Body
其它說明 同 PUT /services/
HTTP 201 Created or HTTP 200 OK
删除指定消費者
DELETE /consumers/{username or id}
Plugin Object
插件表示将在HTTP請求/響應生命周期期間執行的插件配置。可以将功能添加到kong後面運作的服務,例如身份驗證或速率限制。可以通過通路插件庫找到更多關于安裝的資訊和每個插件所需的值。當向服務添加插件配置時,用戶端對該服務所做的每一個請求都将運作添加的插件。如果插件需要針對特定的消費者調整到不同的值,可以通過指定consumer_id值來實作,如:
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"service_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
"consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
"name": "rate-limiting",
"config": {
"minute": 20,
"hour": 500
},
"enabled": true,
"created_at": 1422386534
}
一個插件對于一個請求隻運作一次,但是它将運作的配置取決于它所配置的插件實體。可以為各種實體,實體組合,甚至全局配置插件。例如,當希望以某種方式為大多數請求配置插件,但與已認證的請求行為略有不同時,這很有用。是以,當插件應用于具有不同配置的不同實體時,存在運作插件的優先順序。經驗法則是:一個插件對于配置的實體更具體更詳細,其優先級越高。
當多次配置插件時,優先級的完整順序是:
1、在以下組合上配置插件:a Route, a Service, and a Consumer。 (消費者意味着請求必須被認證)。
2、在Route和Consumer組合上配置的插件。 (消費者意味着請求必須被認證)。
3、插件配置在Service和Consumer的組合上。 (消費者意味着請求必須被認證)。
4、插件配置在Route和Service的組合上。
5、在Consumer上配置的插件。 (消費者意味着請求必須被認證)。
6、在Route上配置的插件。
7、在Service上配置的插件。
8、插件配置為全局運作。
示例:如果rate-limiting插件應用兩次(具有不同的配置):對于Service(插件配置A)和Consumer(插件配置B),則認證此消費者的請求将運作插件配置B并忽略A.但是,不驗證此Consumer的請求将回退運作Plugin config A.請注意,如果禁用了配置B(其啟用标志設定為false),則配置A将應用于會以其他方式比對配置B的請求。
新增一個插件
可以通過五種不同的方式添加插件:
- 對于每個Service/Route and 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
curl -i -X POST \
--url http://localhost:8001/plugins/ \
--data 'name=rate-limiting' \
--data 'config.minute=20&config.hour=500' \
--data 'consumer_id=a1866101-c718-421d-ace3-911042661eca'
POST /plugins/
将要添加的插件的名稱。目前該插件必須分别安裝在每個Kong執行個體中 | ||
consumer_id | 消費者的唯一辨別符,用于在傳入請求上覆寫此特定消費者的現有設定 | |
config.{property} | 插件的配置屬性 | |
enabled | requred,default:true | 插件是否被啟用 |
HTTP/1.1 201 Created
Date: Sun, 27 May 2018 09:20:37 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Access-Control-Allow-Origin: *
Server: kong/0.13.1
{
"created_at": 1527412838000,
"config": {
"minute": 20,
"policy": "cluster",
"redis_timeout": 2000,
"hide_client_headers": false,
"hour": 500,
"limit_by": "consumer",
"redis_port": 6379,
"redis_database": 0,
"fault_tolerant": true
},
"id": "d688bd43-e43b-4e24-a0dc-c2d482bc1a01",
"name": "rate-limiting",
"enabled": true,
"consumer_id": "a1866101-c718-421d-ace3-911042661eca"
}
查詢指定插件
GET /plugins/{id}
插件的唯一辨別符 |
查詢所有插件清單
GET /plugins/
同POST Body | ||
service_id | ||
route_id | ||
更新指定插件
PATCH /plugins/{plugin id}
同 GET /plugins/{id}
同POST /plugins/ Request Body
更新或建立插件
PUT /plugins/
同 POST /plugins/ Request Body
其它說明同 PUT /services
删除指定插件
DELETE /plugins/{plugin_id}
其它同DELETE /services/{service_id}
查詢kong節點已安裝的插件
curl -i -X GET --url http://localhost:8001/plugins/enabled
GET /plugins/enabled
{
"enabled_plugins": [
"jwt",
"acl",
"cors",
"oauth2",
"tcp-log",
"udp-log",
"file-log",
"http-log",
"key-auth",
"hmac-auth",
"basic-auth",
"ip-restriction",
"request-transformer",
"response-transformer",
"request-size-limiting",
"rate-limiting",
"response-ratelimiting",
"aws-lambda",
"bot-detection",
"correlation-id",
"datadog",
"galileo",
"ldap-auth",
"loggly",
"runscope",
"statsd",
"syslog"
]
}
查詢插件schema
檢索插件定義的schema,這對了解插件接受哪些字段非常有用,并且可以用于建構Kong插件系統的第三方內建
curl -i -X GET \
--url http://localhost:8001/plugins/schema/key-auth
GET /plugins/schema/{plugin name}
{
"no_consumer": true,
"fields": {
"key_in_body": {
"default": false,
"type": "boolean"
},
"key_names": {
"type": "array",
"default": "function",
"func": "function",
"required": true
},
"anonymous": {
"default": "",
"func": "function",
"type": "string"
},
"hide_credentials": {
"default": false,
"type": "boolean"
},
"run_on_preflight": {
"default": true,
"type": "boolean"
}
}
}
Certificate Object
證書表示SSL證書的公用證書/私鑰對,這些對象由Kong用來處理加密請求的SSL / TLS。證書可以(可選的)與SNI對象相關聯以将證書/密鑰對與一個或多個主機名相關聯查詢插件配置的schema。這對了解插件接受哪些字段非常有用,并且可以用于建構Kong插件系統的第三方內建。
新增證書
POST /certificates/
屬性 | 限制 | |
cert | PEM編碼的SSL密鑰對的公共證書 | |
key | SSL密鑰對的PEM編碼私鑰 | |
snis | 與此證書關聯的一個或多個主機名作為SNI。這是一個糖參數,它将在引擎蓋下建立一個SNI對象,并将其與此證書關聯友善管理 |
{
"id": "21b69eab-09d9-40f9-a55e-c4ee47fada68",
"cert": "-----BEGIN CERTIFICATE-----...",
"key": "-----BEGIN RSA PRIVATE KEY-----...",
"snis": [
"example.com"
],
"created_at": 1485521710265
}
查詢指定證書
GET /certificates/{sni_name or id}
屬性 | 限制 | |
sni or id | 與此證書關聯的唯一辨別符或SNI名稱 |
查詢所有證書清單
GET /certificates/
更新指定證書
PATCH /certificates/{sni or id}
同GET /certificates/{sni or id}
同POST /certificates/
更新或建立證書
PUT /certificates/
同 POST /certificates/
其它說明同 PUT /servies/
删除指定證書
DELETE /certificates/{sni or id}
同其它DELETE 操作說明
SNI Objects
SNI對象(Server Name Indication)表示主機名與證書的多對一映射。也就是說,證書對象可以有許多與之關聯的主機名;當Kong收到SSL請求時,它使用Client Hello中的SNI字段根據與證書關聯的SNI查找證書對象。
新增SNI
Endpoit
POST /snis/
屬性 | 限制 | |
與給定證書關聯的SNI名稱 | ||
ssl_certificate_id | 與SNI主機名關聯的證書的id(UUID) |
{
"name": "example.com",
"ssl_certificate_id": "21b69eab-09d9-40f9-a55e-c4ee47fada68",
"created_at": 1485521710265
}
查詢指定SNI
GET /snis/{name}
sni 名稱 |
查詢所有SNIs
GET /snis/
更新指定SNI
PATCH /snis/{name}
更新或建立SNI
PUT /snis/
同 POST /snis/
删除指定SNI
DELETE /snis/{name}
Upstream Objects
上遊對象表示一個虛拟主機名,可用于負載平衡多個services(targets)上的傳入請求。例如,對于主機名為service.v1.xyz的Service對象,上遊名為service.v1.xyz。此服務的請求将代理上遊定義的目标。
上遊還包括一個健康檢查器,該檢查器能夠根據其能力或無法為請求提供服務來啟用和禁用target。運作狀況檢查程式的配置存儲在upstream中,并适用于其所有target
新增一個上遊
Endpoint
POST /upstreams/
Target Object
target是具有識别後端服務執行個體的端口的IP位址/主機名。每個upstream可以有很多target,并且可以動态添加target。即時更改即時生效。由于upstream保留了target更改的曆史記錄,是以target無法删除或修改。要禁用目标,使用weight=0釋出新target,或者使用DELETE便捷方法來完成相同的操作。 目前的目标對象定義是最新的created_at
新增一個目标
POST /upstreams/{name or id}/targets
要添加目标的upstream的唯一辨別符或名稱 |
屬性 | 限制 | |
target | 目标位址(ip或主機名)和端口。如果省略,則端口預設為8000.如果主機名解析為SRV記錄,端口值将被dns記錄的值覆寫。 | |
weight | 此目标在上遊負載均衡器中的權重(0-1000,預設為100)。如果主機名解析為SRV記錄,則權重值将被來自dns記錄的值覆寫 |
{
"id": "4661f55e-95c2-4011-8fd6-c5c56df1c9db",
"target": "1.2.3.4:80",
"weight": 15,
"upstream_id": "ee3310c1-6789-40ac-9386-f79c0cb58432",
"created_at": 1485523507446
}
列出目前在上遊負載平衡輪上處于活動狀态的所有目标
注意:此接口在0.12.0版本中已從更改屬于上遊的所有目标更改為僅目前激活的目标。傳回整個目标曆史記錄的端點已移至[列出所有目标](#list-all-targets)
GET /upstreams/{name or id}/targets
同 上
每頁顯示數量 | ||
列出上遊的所有目标
列出上遊的所有目标,可以傳回同一目标的多個目标對象,顯示特定目标的更改曆史記錄。具有最新created_at的目标對象是目前定義
注意:此接口隻适用于Kong v0.12.0+
GET /upstreams/{name or id}/targets/all/
删除指定目标
在負載平衡器中禁用目标。在引擎蓋下,這個方法為給定的目标定義建立一個新的條目,權重為0
注意:該接口僅适用于Kong v0.10.1+
DELETE /upstreams/{upstream name or id}/targets/{target or id}
upstream name or id | 上遊唯一辨別符 | |
target or id | 目标唯一辨別符 |
設定目标為健康
将負載平衡器中目标的目前健康狀況設定為整個Kong群集中的“健康”狀态。
此接口可用于手動重新啟用之前由上遊運作狀況檢查程式禁用的目标,上遊隻向健康節點轉發請求,是以這個調用告訴Kong再次開始使用這個目标。這會重置在Kong節點的所有workers中運作的健康檢查器的健康計數器,并且廣播全叢集消息,以便将“健康”狀态傳播到整個Kong群集。
POST /upstreams/{upstream name or id}/targets/{target or id}/healthy
同上
HTTP 204 No Content
設定目标為不健康
将整個Kong群集中負載均衡器中目标的目前運作狀況設定為“不健康”。
此接口可用于手動禁用目标并使其停止響應請求。上行僅向健康節點轉發請求,是以該呼叫告訴Kong開始在環平衡器算法中跳過此目标。該調用重置在Kong節點的所有從業人員中運作的運作狀況檢查器的運作狀況計數器,并廣播全叢集消息,以便将“不健康”狀态傳播到整個Kong群集。
Active health checks繼續執行不健康的目标。請注意,如果啟用了運作狀況檢查并且探針檢測到目标實際上是健康的,它将自動重新啟用它。要從環平衡器中永久移除目标,您應該删除目标。
POST /upstreams/{upstream name or id}/targets/{target or id}/unhealthy
其它同上
reference:
https://m.aliyun.com/yunqi/articles/63180 https://getkong.org/docs/0.13.x/admin-api/ https://www.jianshu.com/p/5400bf1aceda作者:
zhoujie出處:
http://www.cnblogs.com/zhoujie/本文版權歸作者和部落格園共有,歡迎轉載,但未經作者同意必須保留此段聲明,且在文章頁面明顯位置給出原文連接配接,不然我擔心部落格園找你算賬
如果您覺得本文對你有幫助,請豎起您的大拇指右下角點推薦,也可以關注我