插件

本文原文链接：https://docs.konghq.com/1.1.x/admin-api/#plugin-object

插件实体表示将在HTTP请求/响应生命周期期间执行的插件配置。它是如何为在Kong后面运行的服务添加功能的，例如 Authentication 或 Rate Limiting 。您可以访问Kong Hub，获取有关如何安装以及每个插件所需值的更多信息。

将插件配置添加到服务时，客户端向该服务发出的每个请求都将运行所述插件。如果某个特定消费者需要将插件调整为不同的值，您可以通过创建一个单独的插件实例来实现，该实例通过service 和 consumer这两个字段指定服务和消费者。

插件可以通过标签进行标记和过滤。

  1. {
  2.     "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27",
  3.     "name": "rate-limiting",
  4.     "created_at": 1422386534,
  5.     "route": null,
  6.     "service": null,
  7.     "consumer": null,
  8.     "config": {"hour":500, "minute":20},
  9.     "run_on": "first",
  10.     "protocols": ["http", "https"],
  11.     "enabled": true,
  12.     "tags": ["user-level", "low-priority"]
  13. }

有关详细信息，请参阅下面的优先级部分。

优先级

插件将始终运行一次，每次请求只运行一次。它运行的配置取决于它所针对的实体。

可以为各种实体，实体组合甚至全局配置插件。这很有用，例如，当您希望为大多数请求以某种方式配置插件，但是要使经过身份验证的请求的行为略有不同时。

因此，当插件应用于具有不同配置的不同实体时，存在一个优先顺序来运行插件。经验法则是：插件关于配置的实体数量越多，其优先级越高。

多次配置插件时的完整优先顺序是：

  1. 在以下组合上配置的插件：Route，Service 和 Consumer。（Consumer意味着必须对请求进行身份验证）。
  2. 在 Route 和 Consumer 的组合上配置的插件。（Consumer意味着必须对请求进行身份验证）。
  3. 在 Service 和 Consumer 的组合上配置的插件。（Consumer意味着必须对请求进行身份验证）。
  4. 在 Route 和 Service 的组合上配置的插件。
  5. 在 Consumer 上配置的插件。（Consumer 意味着必须对请求进行身份验证）。
  6. 在 Route 上配置的插件。
  7. 在 Service 上配置的插件。
  8. 配置为全局运行的插件。

例如：如果rate-limiting速率限制插件应用了两次（且都具有不同的配置）：对于一个 Service（插件配置A）和 Consumer（插件配置B），然后请求验证此消费者将运行插件配置B并忽略A。但是，不对此Consumer进行身份验证的请求将回退到运行Plugin配置A。请注意，如果禁用配置B（其启用标志设置为false），配置A将应用于本来匹配配置B的请求。

添加插件

创建一个插件

  1. POST /plugins

创建与特定 Route 关联的插件

  1. POST /routes/{route id}/plugins
参数 描述
route id
required		 应与新创建的插件关联的 Route 的唯一标识符。

创建与特定 Service 关联的插件

  1. POST /services/{service id}/plugins
参数 描述
service id
required		 应与新创建的插件关联的 Service 的唯一标识符。

创建与特定 Consumer 关联的插件

  1. POST /consumers/{consumer id}/plugins
参数 描述
consumer id
required		 应与新创建的插件关联的 consumer 的唯一标识符。

请求体

参数 描述
name 要添加的插件的名称。目前，插件必须分别安装在每个Kong实例中。
route
optional		 如果设置，插件将仅在通过指定路由接收请求时激活。不管使用什么路由，都不要设置插件来激活它。 默认值为null。使用form-encoded时候，用route.id=<route_id>；使用JSON的时候，用"route":{"id":"<route_id>"}。
service
optional		 如果设置，插件将仅在通过属于指定服务的路由之一接收请求时激活。无论服务是否匹配，都不要设置插件激活。 默认值为null。使用form-encoded时候，用service.id=<service_id>；使用JSON的时候，用"service":{"id":"<service_id>"}。
consumer
optional		 如果设置，则插件仅对指定已经过身份验证的请求激活。（请注意，某些插件不能以这种方式限制在消费者身上。）无论经过身份验证的使用者是什么，都不要设置插件激活。默认值为null。使用form-encoded时候，用consumer.id=<consumer_id>；使用JSON的时候，用"consumer":{"id":"<consumer_id>"}。
config
optional		 插件的配置属性，可以在Kong Hub的插件文档页面找到。
run_on
optional		 在给定Service Mesh场景的情况下，控制此插件将运行的Kong节点。可接受的值为：* first，表示“在请求遇到的第一个Kong节点上运行”。 在API Getaway场景中，这是常用操作，因为源和目标之间只有一个Kong节点。在sidecar-to-sidecar Service Mesh场景中，这意味着仅在出站连接的Kong边车上运行插件。* second，意思是“在请求遇到的第二个节点上运行”。此选项仅适用于sidecar-to-sidecar Service Mesh场景：这意味着仅在入站连接的Kong sidecar 上运行插件。* all，意味着“在所有节点上运行”，这意味着 sidecar-to-sidecar 场景中的所有 sidecars。这对 tracing/logging 插件很有用。默认为“first”。
protocols
optional		 将触发此插件的请求协议列表。可能的值为“http”，“https”，“tcp”和“tls”。默认值以及此字段上允许的可能值可能会根据插件类型而更改。例如，仅在流模式下工作的插件可能只支持“tcp”和“tls”。默认为[“http”，“https”]。
enabled
optional		 是否启用插件。默认为true
tags
optional		 与插件关联的一组可选字符串，用于分组和过滤。

响应

  1. HTTP 201 Created
  1. {
  2.     "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27",
  3.     "name": "rate-limiting",
  4.     "created_at": 1422386534,
  5.     "route": null,
  6.     "service": null,
  7.     "consumer": null,
  8.     "config": {"hour":500, "minute":20},
  9.     "run_on": "first",
  10.     "protocols": ["http", "https"],
  11.     "enabled": true,
  12.     "tags": ["user-level", "low-priority"]
  13. }

插件列表

列出所有插件

  1. GET /plugins

列出与特定 Route 关联的插件

  1. GET /routes/{route id}/plugins
参数 描述
route id
required		 要检索其插件的Route的唯一标识符。使用此端点时，仅列出与指定Route关联的插件。

列出与特定 Service 关联的插件

  1. GET /service/{service id}/plugins
参数 描述
service id
required		 要检索其插件的Service的唯一标识符。使用此端点时，仅列出与指定Service关联的插件。

列出与特定 Consumer 关联的插件

  1. GET /consumer/{consumer id}/plugins
参数 描述
consumer id
required		 要检索其插件的Consumer的唯一标识符。使用此端点时，仅列出与指定Consumer关联的插件。

响应

  1. HTTP 200 OK
  1. {
  2. "data": [{
  3.     "id": "a4407883-c166-43fd-80ca-3ca035b0cdb7",
  4.     "name": "rate-limiting",
  5.     "created_at": 1422386534,
  6.     "route": null,
  7.     "service": null,
  8.     "consumer": null,
  9.     "config": {"hour":500, "minute":20},
  10.     "run_on": "first",
  11.     "protocols": ["http", "https"],
  12.     "enabled": true,
  13.     "tags": ["user-level", "low-priority"]
  14. }, {
  15.     "id": "01c23299-839c-49a5-a6d5-8864c09184af",
  16.     "name": "rate-limiting",
  17.     "created_at": 1422386534,
  18.     "route": null,
  19.     "service": null,
  20.     "consumer": null,
  21.     "config": {"hour":500, "minute":20},
  22.     "run_on": "first",
  23.     "protocols": ["tcp", "tls"],
  24.     "enabled": true,
  25.     "tags": ["admin", "high-priority", "critical"]
  26. }],
  28.     "next": "http://localhost:8001/plugins?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
  29. }

查询插件

查询插件

  1. GET /plugins/{plugin id}
参数 描述
plugin id
required		 要检索的插件的唯一标识符。

响应

  1. HTTP 200 OK
  1. {
  2.     "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27",
  3.     "name": "rate-limiting",
  4.     "created_at": 1422386534,
  5.     "route": null,
  6.     "service": null,
  7.     "consumer": null,
  8.     "config": {"hour":500, "minute":20},
  9.     "run_on": "first",
  10.     "protocols": ["http", "https"],
  11.     "enabled": true,
  12.     "tags": ["user-level", "low-priority"]
  13. }

更新插件

更新插件

  1. PATCH /plugins/{plugin id}
参数 描述
plugin id
required		 要更新的插件的唯一标识符。

请求体

参数 描述
name 要添加的插件的名称。目前，插件必须分别安装在每个Kong实例中。
route
optional		 如果设置，插件将仅在通过指定路由接收请求时激活。不管使用什么路由，都不要设置插件来激活它。 默认值为null。使用form-encoded时候，用route.id=<route_id>；使用JSON的时候，用"route":{"id":"<route_id>"}。
service
optional		 如果设置，插件将仅在通过属于指定服务的路由之一接收请求时激活。无论服务是否匹配，都不要设置插件激活。 默认值为null。使用form-encoded时候，用service.id=<service_id>；使用JSON的时候，用"service":{"id":"<service_id>"}。
consumer
optional		 如果设置，则插件仅对指定已经过身份验证的请求激活。（请注意，某些插件不能以这种方式限制在消费者身上。）无论经过身份验证的使用者是什么，都不要设置插件激活。默认值为null。使用form-encoded时候，用consumer.id=<consumer_id>；使用JSON的时候，用"consumer":{"id":"<consumer_id>"}。
config
optional		 插件的配置属性，可以在Kong Hub的插件文档页面找到。
run_on
optional		 在给定Service Mesh场景的情况下，控制此插件将运行的Kong节点。可接受的值为：* first，表示“在请求遇到的第一个Kong节点上运行”。 在API Getaway场景中，这是常用操作，因为源和目标之间只有一个Kong节点。在sidecar-to-sidecar Service Mesh场景中，这意味着仅在出站连接的Kong边车上运行插件。* second，意思是“在请求遇到的第二个节点上运行”。此选项仅适用于sidecar-to-sidecar Service Mesh场景：这意味着仅在入站连接的Kong sidecar 上运行插件。* all，意味着“在所有节点上运行”，这意味着 sidecar-to-sidecar 场景中的所有 sidecars。这对 tracing/logging 插件很有用。默认为“first”。
protocols
optional		 将触发此插件的请求协议列表。可能的值为“http”，“https”，“tcp”和“tls”。默认值以及此字段上允许的可能值可能会根据插件类型而更改。例如，仅在流模式下工作的插件可能只支持“tcp”和“tls”。默认为[“http”，“https”]。
enabled
optional		 是否启用插件。默认为true
tags
optional		 与插件关联的一组可选字符串，用于分组和过滤。

响应

  1. HTTP 200 OK
  1. {
  2.     "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27",
  3.     "name": "rate-limiting",
  4.     "created_at": 1422386534,
  5.     "route": null,
  6.     "service": null,
  7.     "consumer": null,
  8.     "config": {"hour":500, "minute":20},
  9.     "run_on": "first",
  10.     "protocols": ["http", "https"],
  11.     "enabled": true,
  12.     "tags": ["user-level", "low-priority"]
  13. }

更新或创建插件

更新或创建一个插件

  1. PUT /plugins/{plugin id}
参数 描述
plugin id
required		 要更新的插件的唯一标识符。

请求体

参数 描述
name 要添加的插件的名称。目前，插件必须分别安装在每个Kong实例中。
route
optional		 如果设置，插件将仅在通过指定路由接收请求时激活。不管使用什么路由，都不要设置插件来激活它。 默认值为null。使用form-encoded时候，用route.id=<route_id>；使用JSON的时候，用"route":{"id":"<route_id>"}。
service
optional		 如果设置，插件将仅在通过属于指定服务的路由之一接收请求时激活。无论服务是否匹配，都不要设置插件激活。 默认值为null。使用form-encoded时候，用service.id=<service_id>；使用JSON的时候，用"service":{"id":"<service_id>"}。
consumer
optional		 如果设置，则插件仅对指定已经过身份验证的请求激活。（请注意，某些插件不能以这种方式限制在消费者身上。）无论经过身份验证的使用者是什么，都不要设置插件激活。默认值为null。使用form-encoded时候，用consumer.id=<consumer_id>；使用JSON的时候，用"consumer":{"id":"<consumer_id>"}。
config
optional		 插件的配置属性，可以在Kong Hub的插件文档页面找到。
run_on
optional		 在给定Service Mesh场景的情况下，控制此插件将运行的Kong节点。可接受的值为：* first，表示“在请求遇到的第一个Kong节点上运行”。 在API Getaway场景中，这是常用操作，因为源和目标之间只有一个Kong节点。在sidecar-to-sidecar Service Mesh场景中，这意味着仅在出站连接的Kong边车上运行插件。* second，意思是“在请求遇到的第二个节点上运行”。此选项仅适用于sidecar-to-sidecar Service Mesh场景：这意味着仅在入站连接的Kong sidecar 上运行插件。* all，意味着“在所有节点上运行”，这意味着 sidecar-to-sidecar 场景中的所有 sidecars。这对 tracing/logging 插件很有用。默认为“first”。
protocols
optional		 将触发此插件的请求协议列表。可能的值为“http”，“https”，“tcp”和“tls”。默认值以及此字段上允许的可能值可能会根据插件类型而更改。例如，仅在流模式下工作的插件可能只支持“tcp”和“tls”。默认为[“http”，“https”]。
enabled
optional		 是否启用插件。默认为true
tags
optional		 与插件关联的一组可选字符串，用于分组和过滤。

使用正文中指定的定义在所请求的资源下插入（或替换）插件。插件将通过name or id属性进行标识。

当name or id属性具有UUID的结构时，插入/替换的插件将由其id标识。否则将通过其名称识别。

在创建新插件而不指定id（既不在URL中也不在正文中）时，它将自动生成。

请注意，不允许在URL中指定name，也不允许在请求正文中指定其他名称。

响应

  1. HTTP 201 Created or HTTP 200 OK

请参阅POST和PATCH响应。

删除插件

删除一个插件

  1. DELETE /plugins/{plugin id}
参数 描述
plugin id
required		 要删除的插件的唯一标识符。

响应

  1. HTTP 204 No Content

查询可使用的插件

检索Kong节点上所有已安装插件的列表。

  1. GET /plugins/enabled

响应

  1. HTTP 200 OK
  1. {
  2.     "enabled_plugins": [
  3.         "jwt",
  4.         "acl",
  5.         "cors",
  6.         "oauth2",
  7.         "tcp-log",
  8.         "udp-log",
  9.         "file-log",
  10.         "http-log",
  11.         "key-auth",
  12.         "hmac-auth",
  13.         "basic-auth",
  14.         "ip-restriction",
  15.         "request-transformer",
  16.         "response-transformer",
  17.         "request-size-limiting",
  18.         "rate-limiting",
  19.         "response-ratelimiting",
  20.         "aws-lambda",
  21.         "bot-detection",
  22.         "correlation-id",
  23.         "datadog",
  24.         "galileo",
  25.         "ldap-auth",
  26.         "loggly",
  27.         "statsd",
  28.         "syslog"
  29.     ]
  30. }

查询插件schema

检索插件配置的schema。这有助于了解插件接受哪些字段，并可用于构建Kong插件系统的第三方集成。

  1. GET /plugins/schema/{plugin name}

响应

  1. HTTP 200 OK
  1. {
  2.     "fields": {
  3.         "hide_credentials": {
  4.             "default": false,
  5.             "type": "boolean"
  6.         },
  7.         "key_names": {
  8.             "default": "function",
  9.             "required": true,
  10.             "type": "array"
  11.         }
  12.     }
  13. }