request-id
request-id 插件为每个通过 APISIX 代理的请求添加一个唯一 ID，可用于追踪 API 请求。如果请求在 header_name 对应的请求头中已经携带了 ID，插件将直接使用该请求头的值作为唯一 ID，而不会用自动生成的 ID 覆盖它。
如果你使用的是 API7 企业版，还可以在网关的访问日志和错误日志中找到请求 ID。
示例
以下示例展示了如何在不同场景下配置 request-id 插件。
将请求 ID 附加到默认响应头
以下示例展示了如何在路由上配置 request-id，如果请求中未传递请求 ID，则生成一个请求 ID 并将其附加到默认的 X-Request-Id 响应头中。当请求中已设置 X-Request-Id 请求头时，插件将使用请求头中的值作为请求 ID。
使用默认配置（显式定义）在路由上创建 request-id 插件：
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "request-id-route",
"uri": "/anything",
"plugins": {
"request-id": {
"header_name": "X-Request-Id",
"include_in_response": true,
"algorithm": "uuid"
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}
}'
向路由发送请求：
curl -i "http://127.0.0.1:9080/anything"
你应该收到 HTTP/1.1 200 OK 响应，并看到响应头包含带有生成 ID 的 X-Request-Id：
X-Request-Id: b9b2c0d4-d058-46fa-bafc-dd91a0ccf441
向路由发送带有自定义请求 ID 的请求：
curl -i "http://127.0.0.1:9080/anything" -H 'X-Request-Id: some-custom-request-id'
你应该收到 HTTP/1.1 200 OK 响应，并看到响应包含带有自定义请求 ID 的 X-Request-Id 头：
X-Request-Id: some-custom-request-id
将请求 ID 附加到自定义响应头
以下示例展示了如何在路由上配置 request-id，将生成的请求 ID 附加到指定的响应头。
创建带有 request-id 插件的路由：
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "request-id-route",
"uri": "/anything",
"plugins": {
"request-id": {
"header_name": "X-Req-Identifier",
"include_in_response": true
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}
}'
❶ 定义携带请求 ID 的自定义请求头。
❷ 在响应头中包含请求 ID。
向路由发送请求：
curl -i "http://127.0.0.1:9080/anything"
你应该收到 HTTP/1.1 200 OK 响应，并看到响应包含带有生成 ID 的 X-Req-Identifier 头：
X-Req-Identifier: 1c42ff59-ee4c-4103-a980-8359f4135b21
在响应头中隐藏请求 ID
以下示例展示了如何在路由上配置 request-id，将生成的请求 ID 附加到指定请求头。包含请求 ID 的请求头应转发到上游服务，但不返回在响应头中。
创建带有 request-id 插件的路由：
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "request-id-route",
"uri": "/anything",
"plugins": {
"request-id": {
"header_name": "X-Req-Identifier",
"include_in_response": false
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}
}'
❶ 定义携带请求 ID 的自定义请求头。
❷ 不在响应头中包含请求 ID。
向路由发送请求：
curl -i "http://127.0.0.1:9080/anything"
你应该收到 HTTP/1.1 200 OK 响应，并且在响应头中没有看到 X-Req-Identifier 头。在响应体中，你应该看到：
{
"args": {},
"data": "",
"files": {},
"form": {},
"headers": {
"Accept": "*/*",
"Host": "127.0.0.1",
"User-Agent": "curl/8.6.0",
"X-Amzn-Trace-Id": "Root=1-6752748c-7d364f48564508db1e8c9ea8",
"X-Forwarded-Host": "127.0.0.1",
"X-Req-Identifier": "268092bc-15e1-4461-b277-bf7775f2856f"
},
...
}
这表明请求 ID 已转发到上游服务，但未在响应头中返回。
使用 nanoid 算法
以下示例展示了如何在路由上配置 request-id 并使用 nanoid 算法生成请求 ID。
创建带有 request-id 插件的路由：
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "request-id-route",
"uri": "/anything",
"plugins": {
"request-id": {
"algorithm": "nanoid"
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}
}'
向路由发送请求：
curl -i "http://127.0.0.1:9080/anything"
你应该收到 HTTP/1.1 200 OK 响应，并看到 响应包含 X-Req-Identifier 头，其 ID 是使用 nanoid 算法生成的：
X-Request-Id: kepgHWCH2ycQ6JknQKrX2
在全局和路由上附加请求 ID
以下示例展示了如何将 request-id 配置为全局插件，并在路由上配置它以附加两个 ID。
创建一个全局规则，使用 request-id 插件将请求 ID 添加到自定义请求头：
curl -i "http://127.0.0.1:9180/apisix/admin/global_rules" -X PUT -d '{
"id": "rule-for-request-id",
"plugins": {
"request-id": {
"header_name": "Global-Request-ID"
}
}
}'
创建一个带有 request-id 插件的路由，将请求 ID 添加到另一个自定义请求头：
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "request-id-route",
"uri": "/anything",
"plugins": {
"request-id": {
"header_name": "Route-Request-ID"
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}
}'
向路由发送请求：
curl -i "http://127.0.0.1:9080/anything"
你应该收到 HTTP/1.1 200 OK 响应，并看到响应包含以下头：
Global-Request-ID: 2e9b99c1-08ed-4a74-b347-49c0891b07ad
Route-Request-ID: d755666b-732c-4f0e-a30e-a7a71ace4e26