单曲荨环 阅读(35) 评论(0)

 

部署好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节点中启用的插件,即在数据库中生成了对应存储表

查询节点状态

Example

curl  http://localhost:8001/status

Endpoint

GET /status

Response

{
    "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

Example

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'

Endpoint

POST  /apis/

Request Body

属性 约束 描述
name required 接入的API名称
hosts semi-optional 逗号分割的接入API的域名列表
uris semi-optional 逗号分割的接入API的前缀path,即指定uri用户通过kong刚问要加上这个path
methods semi-optional 逗号分割的接入API的HTTP method,如get /post/ put/delete/..
upstream_url required 代理的上游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 optional,default:60000ms 在发送请求到上游服务的两个连续写入操作之间的超时时间(ms)
upstream_read_timeout optional,default:60000ms 在发送请求到上游服务的两个连续读取操作之间的超时时间(ms)
https_only optional,default:false 如果希望仅通过HTTPS转发API(默认8443端口),则启用
http_if_terminated optional,default:false 仅在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

Example

  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

Endpoint

GET /apis/{name or id}

Request Params

属性 约束 描述
name or id required 接入API到唯一标识符,name或者id

 

 

Response

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列表

Example

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

Endpoint

GET /apis/

Request Querystring

属性 约束 描述
id optional 同post描述
name optional
upstream_url optional
retries optional
size optional limit,查询的记录条数
offset optional cursor位置,用于分页

 

 

 

 

 

 

Response

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

Example

 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'

Endpoint

PATCH /apis/{name or id}

Request Param

同GET /apis/{name or id}

Request Body

同POST /apis/

Response

同GET /apis/{name or id},返回的是更新后的数据

更新或新增一个API

Example

#更新一个存在的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/。

Endpoint

PUT /apis/

Request Body

同 POST /apis/

Response

HTTP 201 Created or HTTP 200 OK
返回数据同POST or PATCH reponses

根据name或id删除一个API

Example

  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

Endpoint

DELETE /apis/{name or id}

Request Param

同 GET /apis/{name or id}

Response

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

Example

  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'

Endpoint

POST /services/

Request Body

属性 约束 描述
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”)

 

 

 

 

 

 

 

 

 

注:可用url来代替同时指定protocal/host/port/path,但url不会出现在返回字段中。

Response

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

Example

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

Endpoint

GET /services/{name or id}

Request Param

属性 约束 描述
name or id  required 服务的唯一标识符

 

 

Response

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获取一个服务

Example

 curl -i -X GET \
  --url  http://localhost:8001/routes/{ROUTE_ID}/service 

Endpoint

GET /routes/{route id}/service

Request Param

属性 约束 描述
route id required 属于要检索的服务的路由的唯一标识符

 

 

Response

同 GET/services/{name or id}返回结果

查询所有服务列表

Example

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

Endpoint

GET /services/

Request QueryString

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

 

 

 

Response

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更新服务

Example

 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'

Endpoint

PATCH /services/{name or id}

Request Param

name or id

Requst Body

同POST /services/  Request Body

Response

同 PATCH /apis/{name or id} 返回结构

根据route_id更新服务

Endpoint

PATCH /routes/{route id}/service

其它同PATCH /services/{name or id}

根据name或id删除服务

Endpoint

DELETE /services/{name or id}

Route Object

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

新增一个路由

Example

  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'

Endpoint

POST /routes/

Request Body

属性 约束 描述
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>"}

 

 

 

 

 

 

Response

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查询路由

Example

curl -i -X GET \
  --url  http://localhost:8001/routes/9e9ff7b8-776f-4e65-ad2b-ed977e3fe4ea

Endpoint

GET /routes/{id}

Request Param

属性 约束 描述
id required 路由的唯一标识符

 

 

Response

返回同 GET /service/{id}返回结构

查询所有路由列表

Example

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

EndPoint

GET /routes

Request QueryString

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

 

 

 

Response

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"
    }]
}

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

Example

curl -i -X GET \
  --url  http://localhost:8001/services/9ec3c166-f29a-4b04-a33e-c17ac42a3429/routes

Endpoint

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

Request QueryString Param

属性 约束 描述
service name or id required 路由关联的服务的唯一ID或name

 

 

Response

结构同 GET /routes

根据route_id更新指定路由

EndPoint

PATCH /routes/{id}

Request Param

同 GET /routes/{id}

Request Body

同 POST /routes

根据route_id删除路由

Endpoint

DELETE /routes/{id}

其它同前面

Consumer Object

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

创建一个消费者

Example

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

Endpoint

POST /consumers/

Requst Body

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

 

 

 

Response

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"
}

查询消费者列表

Example

 curl -i -X GET \
  --url  http://localhost:8001/consumers/zhou
  或
  curl -i -X GET \
  --url  http://localhost:8001/consumers/a1866101-c718-421d-ace3-911042661eca

Endpoint

GET /consumers/{username or id}

查询所有消费者

Endpoint

GET  /consumers/

Request QueryString

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

 

 

 

 

 

Response

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"
    }]
}

更新指定消费者

Endpoint

PATCH /consumers/{username or id}

Request Param

属性 约束 描述
username or id  required  

 

 

Request Body

属性 约束 描述
username semi-optional 同POST body说明
custome_id semi-optional

 

 

 

更新或创建消费者

Endpoint

PUT /consumers/

Request Body

同上 Request Body

其它说明 同 PUT /services/

Response

HTTP 201 Created or HTTP 200 OK

删除指定消费者

Endpoint

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

Example

  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'

Endpoint

POST /plugins/

Request Body

属性 约束 描述
name required 将要添加的插件的名称。目前该插件必须分别安装在每个Kong实例中
consumer_id optional 消费者的唯一标识符,用于在传入请求上覆盖此特定消费者的现有设置
config.{property} required 插件的配置属性
enabled requred,default:true 插件是否被启用

 

 

 

 

Response

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"
}

查询指定插件

Endpoint

GET /plugins/{id}

Request Param

属性 约束 描述
id required 插件的唯一标识符

 

 

查询所有插件列表

Endpoint

GET /plugins/

Request Querystring

属性 约束 描述
id optional 同POST Body
name
service_id
route_id
consumer_id
size
offset

 

 

 

 

 

更新指定插件

Endpoint

PATCH /plugins/{plugin id}

Request Param

同 GET /plugins/{id}

Request Body

同POST /plugins/ Request Body

更新或创建插件

Endpoint

PUT /plugins/

Request Body

同 POST /plugins/ Request Body

其它说明同 PUT /services

 

 

Certificate Object、SNI Objects、Upstream Objects、Target Object 未完待续...