版本：3.10.x

教程：通过插件代理和管理 API 请求

本教程以快速开始为基础，带你完成一个贴近实际的场景：通过 API7 网关代理 API 请求，并使用插件实施身份认证和限流。

你将学到：

为后端 API 创建服务和路由
添加 key-auth 插件以要求 API Key（API 密钥）身份认证
创建带有凭证的消费者
添加 limit-count 插件以实施限流
测试完整配置

预计用时：约 15 分钟

前置条件：已运行的 API7 网关实例。如果尚未设置，请先完成快速开始。如果要跟随 Admin API 示例，请在开始前从控制台获取 Token。

第 1 步：创建服务和路由

创建一个将请求代理到 httpbin.org 的服务。你可以手动添加，也可以导入 OpenAPI 规范来创建服务及其路由。

控制台
Admin API
ADC

在控制台侧边栏中进入 default 网关组，然后点击服务。
点击 新增服务，再点击 手动新增。
配置服务：

字段	值
名称	`demo-api`
服务类型	HTTP（七层）
上游协议	`HTTP`
如何找到上游	使用节点

点击 新增节点，并进行如下配置：

字段	值
主机	`httpbin.org`
端口	`80`
权重	`100`

点击新增创建服务。
点击 demo-api 服务，然后点击 新增路由。
配置路由：

字段	值
名称	`get-request`
路径	`/get`
方法	`GET`

点击新增。

# 创建包含上游的服务
curl -k "https://localhost:7443/apisix/admin/services/demo-api?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "demo-api",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        { "host": "httpbin.org", "port": 80, "weight": 100 }
      ]
    }
  }'

# 在该服务下创建路由
curl -k "https://localhost:7443/apisix/admin/routes/get-request?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get-request",
    "service_id": "demo-api",
    "paths": ["/get"],
    "methods": ["GET"]
  }'

如果不是在本地运行，请将 localhost 替换为你的 Admin API 主机。若 Admin API 使用自签名 TLS 证书，则必须使用 -k 标志。将 {gateway_group_id} 替换为网关组 ID：对于快速开始创建的网关组，请使用 default；也可从控制台的 网关组 页面复制该 ID。

adc.yaml
services:
  - name: demo-api
    upstream:
      name: default
      scheme: http
      nodes:
        - host: httpbin.org
          port: 80
          weight: 100
    routes:
      - name: get-request
        uris:
          - /get
        methods:
          - GET
    labels:
      docs-example: demo-api

预览本示例管理的资源变更，确认没有非预期的更新或删除：

adc diff -f adc.yaml \
  --include-resource-type service \
  --label-selector docs-example=demo-api

审查变更后同步配置：

adc sync -f adc.yaml \
  --include-resource-type service \
  --label-selector docs-example=demo-api

导入 OpenAPI 规范

控制台支持通过 OpenAPI 3.0 或 3.1 规范创建服务及其路由。例如，将以下内容保存为 openapi.yaml：

openapi.yaml
openapi: 3.0.0
info:
  title: demo-api
  version: 1.0.0
paths:
  /get:
    get:
      operationId: get-request
      responses:
        "200":
          description: Successful response

在控制台中：

在 default 网关组中，进入服务并点击 新增服务。
选择 导入 OpenAPI，在 OpenAPI 规范 字段中上传 openapi.yaml。
将 服务类型 保持为 HTTP（七层），将 上游协议 设为 HTTP，并在 如何找到上游 中选择 使用节点。
点击 新增节点，填写上游主机、端口和权重。本教程使用 httpbin.org、80 和 100。
点击 下一步，检查根据规范生成的服务和路由，然后点击新增。

规范中的路径会生成该服务下的路由。接着按照第 2 步验证 /get 路由，再为导入的服务配置插件。

第 2 步：验证代理

在添加插件前，测试路由以验证基本配置：

curl -i "http://localhost:9080/get"

你应收到包含 HTTPBin 响应正文的 200 OK 响应，这表示代理工作正常。

第 3 步：启用 `key-auth` 插件

key-auth 插件要求消费者提供有效的 API Key。

控制台
Admin API
ADC

在 default 网关组中，进入服务并点击 demo-api 服务。
点击插件，再点击 新增插件。
搜索 key-auth 并启用它。
使用默认配置并点击新增。

# 替换服务定义并启用 key-auth
curl -k "https://localhost:7443/apisix/admin/services/demo-api?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "demo-api",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        { "host": "httpbin.org", "port": 80, "weight": 100 }
      ]
    },
    "plugins": {
      "key-auth": {}
    }
  }'

adc.yaml
services:
  - name: demo-api
    upstream:
      name: default
      scheme: http
      nodes:
        - host: httpbin.org
          port: 80
          weight: 100
    routes:
      - name: get-request
        uris:
          - /get
        methods:
          - GET
    plugins:
      key-auth: {}
    labels:
      docs-example: demo-api

本次同步只更新带有本示例标签的服务。请在文件中保留前面步骤的上游和路由，并添加新的 plugins 块。其他服务保持不变。

预览本示例管理的资源变更，确认没有非预期的更新或删除：

adc diff -f adc.yaml \
  --include-resource-type service \
  --label-selector docs-example=demo-api

审查变更后同步配置：

adc sync -f adc.yaml \
  --include-resource-type service \
  --label-selector docs-example=demo-api

不带密钥测试

curl -i "http://localhost:9080/get"

预期响应：

HTTP/1.1 401 Unauthorized
{"message":"Missing API key in request"}

第 4 步：创建消费者

创建一个带有 API Key 凭证的消费者：

控制台
Admin API
ADC

在控制台侧边栏中进入 消费者，然后点击 新增消费者。
配置消费者：

字段	值
名称	`test-consumer`

点击新增创建消费者。
点击 test-consumer 消费者以打开它，然后选择 认证凭据 选项卡。
选择 Key Authentication，然后点击 新增 Key Authentication 凭据。
配置凭证：

字段	值
名称	`test-consumer-key`
Key	`my-secret-api-key`

点击新增。

# 创建消费者
curl -k "https://localhost:7443/apisix/admin/consumers/test-consumer?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "test-consumer"
  }'

# 为消费者添加 key-auth 凭证
curl -k "https://localhost:7443/apisix/admin/consumers/test-consumer/credentials/test-consumer-key?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test-consumer-key",
    "plugins": {
      "key-auth": {
        "key": "my-secret-api-key"
      }
    }
  }'

在 API7 企业版中，API Key 存放在附加到消费者的凭证资源中，而不是直接内联到消费者上。如果在消费者上内联配置 key-auth 插件，Admin API 会拒绝请求并返回错误 adding new key-auth plugin in consumer is not allowed, please use it in credential。

adc.yaml
consumers:
  - username: test-consumer
    credentials:
      - name: test-consumer-key
        type: key-auth
        config:
          key: my-secret-api-key
    labels:
      docs-example: test-consumer

预览本示例管理的资源变更，确认没有非预期的更新或删除：

adc diff -f adc.yaml \
  --include-resource-type consumer \
  --label-selector docs-example=test-consumer

审查变更后同步配置：

adc sync -f adc.yaml \
  --include-resource-type consumer \
  --label-selector docs-example=test-consumer

使用 API Key 测试

curl -i "http://localhost:9080/get" -H "apikey: my-secret-api-key"

预期响应：200 OK。

第 5 步：启用限流

添加 limit-count 插件，以限制消费者可以发出的请求数量。

控制台
Admin API
ADC

在 default 网关组中，进入服务并点击 demo-api 服务。
点击插件，再点击 新增插件。
搜索 limit-count 并按如下配置：

{
  "count": 5,
  "time_window": 60,
  "rejected_code": 429,
  "key_type": "var",
  "key": "consumer_name",
  "policy": "local"
}

点击新增。

# 替换服务定义并启用 key-auth 和 limit-count
curl -k "https://localhost:7443/apisix/admin/services/demo-api?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "demo-api",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        { "host": "httpbin.org", "port": 80, "weight": 100 }
      ]
    },
    "plugins": {
      "key-auth": {},
      "limit-count": {
        "count": 5,
        "time_window": 60,
        "rejected_code": 429,
        "key_type": "var",
        "key": "consumer_name",
        "policy": "local"
      }
    }
  }'

adc.yaml
services:
  - name: demo-api
    upstream:
      name: default
      scheme: http
      nodes:
        - host: httpbin.org
          port: 80
          weight: 100
    routes:
      - name: get-request
        uris:
          - /get
        methods:
          - GET
    plugins:
      key-auth: {}
      limit-count:
        count: 5
        time_window: 60
        rejected_code: 429
        key_type: var
        key: consumer_name
        policy: local
    labels:
      docs-example: demo-api

预览本示例管理的资源变更，确认没有非预期的更新或删除：

adc diff -f adc.yaml \
  --include-resource-type service \
  --label-selector docs-example=demo-api

审查变更后同步配置：

adc sync -f adc.yaml \
  --include-resource-type service \
  --label-selector docs-example=demo-api

测试限流

快速连续发送多个请求：

for i in $(seq 1 6); do
  echo "Request $i:"
  curl -s -o /dev/null -w "HTTP %{http_code}\n" \
    http://localhost:9080/get -H "apikey: my-secret-api-key"
done

预期输出：

Request 1: HTTP 200
Request 2: HTTP 200
Request 3: HTTP 200
Request 4: HTTP 200
Request 5: HTTP 200
Request 6: HTTP 429

后续步骤

深入了解 API7 产品和 APISIX：了解完整的 API7 产品生态系统。
API7 网关控制面配置参考：为生产环境微调控制面。
监控指标：监控网关流量。

第 1 步：创建服务和路由​

导入 OpenAPI 规范​

第 2 步：验证代理​

第 3 步：启用 key-auth 插件​

不带密钥测试​

第 4 步：创建消费者​

使用 API Key 测试​

第 5 步：启用限流​

测试限流​

后续步骤​

第 1 步：创建服务和路由

导入 OpenAPI 规范

第 2 步：验证代理

第 3 步：启用 `key-auth` 插件

不带密钥测试

第 4 步：创建消费者

使用 API Key 测试

第 5 步：启用限流

测试限流

后续步骤