Skip to content

Commit f9537d1

Browse files
YilialinnYilialinn
authored
docs: update proxy-rewrite plugin documentation (#13292)
1 parent aaabee1 commit f9537d1

2 files changed

Lines changed: 187 additions & 19 deletions

File tree

‎docs/en/latest/plugins/proxy-rewrite.md‎

Lines changed: 85 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ The `proxy-rewrite` Plugin offers options to rewrite requests that APISIX forwar
4141
| Name | Type | Required | Default | Valid values | Description |
4242
|-----------------------------|---------------|----------|---------|----------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
4343
| uri | string | False | | | New Upstream URI path. Value supports [NGINX variables](https://nginx.org/en/docs/http/ngx_http_core_module.html). For example, `$arg_name`. |
44-
| method | string | False | | ["GET", "POST", "PUT", "HEAD", "DELETE", "OPTIONS","MKCOL", "COPY", "MOVE", "PROPFIND", "PROPFIND","LOCK", "UNLOCK", "PATCH", "TRACE"] | HTTP method to rewrite requests to use. |
44+
| method | string | False | | ["GET", "POST", "PUT", "HEAD", "DELETE", "OPTIONS", "MKCOL", "COPY", "MOVE", "PROPFIND", "LOCK", "UNLOCK", "PATCH", "TRACE"] | HTTP method to rewrite requests to use. |
4545
| regex_uri | array[string] | False | | | Regular expressions used to match the URI path from client requests and compose a new Upstream URI path. When both `uri` and `regex_uri` are configured, `uri` has a higher priority. The array should contain one or more **key-value pairs**, with the key being the regular expression to match URI against and value being the new Upstream URI path. For example, with `["^/iresty/(. *)/(. *)", "/$1-$2", ^/theothers/*", "/theothers"]`, if a request is originally sent to `/iresty/hello/world`, the Plugin will rewrite the Upstream URI path to `/iresty/hello-world`; if a request is originally sent to `/theothers/hello/world`, the Plugin will rewrite the Upstream URI path to `/theothers`. |
4646
| host | string | False | | | Set [`Host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Host) request header. |
4747
| headers | object | False | | | Header actions to be executed. Can be set to objects of action verbs `add`, `remove`, and/or `set`; or an object consisting of headers to be `set`. When multiple action verbs are configured, actions are executed in the order of `add`, `remove`, and `set`. |
@@ -505,3 +505,87 @@ curl -i "http://127.0.0.1:9080/get"
505505
```
506506

507507
You should receive an `HTTP/1.1 403 Forbidden` response.
508+
509+
### Dynamically Forward Requests in `radixtree_uri_with_parameter` Router Mode
510+
511+
The following example demonstrates how to extract part of the URL path using the `uri_param_*` variable and forward the value to the Upstream service in a new header. This example assumes that APISIX is operating in the `radixtree_uri_with_parameter` [router mode](../router-radixtree.md).
512+
513+
Create a Route as such:
514+
515+
```shell
516+
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
517+
-H "X-API-KEY: ${admin_key}" \
518+
-d '{
519+
"id": "httpbin",
520+
"uri": "/anything/user/:user_id/profile",
521+
"plugins": {
522+
"proxy-rewrite": {
523+
"headers": {
524+
"set": {
525+
"X-User-Id": "$uri_param_user_id"
526+
}
527+
}
528+
}
529+
},
530+
"upstream": {
531+
"type": "roundrobin",
532+
"nodes": {
533+
"httpbin.org:80": 1
534+
}
535+
}
536+
}'
537+
```
538+
539+
`/anything/user/:user_id/profile` matches requests where `user_id` is a Route parameter. The Plugin is configured to assign the `user_id` parameter value to a new header `X-User-Id`.
540+
541+
Send a request to the Route:
542+
543+
```shell
544+
curl "http://127.0.0.1:9080/anything/user/123/profile"
545+
```
546+
547+
You should see a response similar to the following:
548+
549+
```text
550+
{
551+
"args": {},
552+
"data": "",
553+
"files": {},
554+
"form": {},
555+
"headers": {
556+
"Accept": "*/*",
557+
"Host": "127.0.0.1",
558+
"User-Agent": "curl/8.6.0",
559+
"X-Amzn-Trace-Id": "Root=1-68873cf5-7248f64d19d607ea50aa9735",
560+
"X-Forwarded-Host": "127.0.0.1",
561+
"X-User-Id": "123"
562+
},
563+
...
564+
}
565+
```
566+
567+
The Route parameter also accepts URL-encoded strings. For instance, if you send a request as such:
568+
569+
```shell
570+
curl -i "http://127.0.0.1:9080/anything/user/123%20456/profile"
571+
```
572+
573+
The user ID would be extracted as `123 456`:
574+
575+
```text
576+
{
577+
"args": {},
578+
"data": "",
579+
"files": {},
580+
"form": {},
581+
"headers": {
582+
"Accept": "*/*",
583+
"Host": "127.0.0.1",
584+
"User-Agent": "curl/8.6.0",
585+
"X-Amzn-Trace-Id": "Root=1-68873d37-7634825b20d05dee3a852cb9",
586+
"X-Forwarded-Host": "127.0.0.1",
587+
"X-User-Id": "123 456"
588+
},
589+
...
590+
}
591+
```

‎docs/zh/latest/plugins/proxy-rewrite.md‎

Lines changed: 102 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ keywords:
66
- Plugin
77
- Proxy Rewrite
88
- proxy-rewrite
9-
description: proxy-rewrite 插件支持重写 APISIX 转发到上游服务的请求。使用此插件，您可以修改 HTTP 方法、请求目标上游地址、请求标头等。
9+
description: proxy-rewrite 插件支持重写 APISIX 转发到上游服务的请求。使用此插件，你可以修改 HTTP 方法、请求目标上游地址、请求标头等。
1010
---
1111

1212
<!--
@@ -34,19 +34,19 @@ description: proxy-rewrite 插件支持重写 APISIX 转发到上游服务的请
3434

3535
## 描述
3636

37-
`proxy-rewrite` 插件支持重写 APISIX 转发到上游服务的请求。使用此插件，您可以修改 HTTP 方法、请求目标上游地址、请求标头等。
37+
`proxy-rewrite` 插件支持重写 APISIX 转发到上游服务的请求。使用此插件，你可以修改 HTTP 方法、请求目标上游地址、请求标头等。
3838

3939
## 属性
4040

4141
| 名称 | 类型 | 必需 | 默认值 | 有效值 | 描述 |
4242
|-----------------------------|-----------|----------|---------|------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
43-
| uri | string | 否 | | | 新的上游 URI 路径。值支持 [Nginx 变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)。例如，`$arg_name`。 |
44-
| method | string | 否 | | ["GET", "POST", "PUT", "HEAD", "DELETE", "OPTIONS","MKCOL", "COPY", "MOVE", "PROPFIND", "PROPFIND","LOCK", "UNLOCK", "PATCH", "TRACE"] | 要使用的重写请求的 HTTP 方法。 |
43+
| uri | string | 否 | | | 新的上游 URI 路径。值支持 [NGINX 变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)。例如，`$arg_name`。 |
44+
| method | string | 否 | | ["GET", "POST", "PUT", "HEAD", "DELETE", "OPTIONS", "MKCOL", "COPY", "MOVE", "PROPFIND", "LOCK", "UNLOCK", "PATCH", "TRACE"] | 要使用的重写请求的 HTTP 方法。 |
4545
| regex_uri | array[string] | 否 | | | 用于匹配客户端请求的 URI 路径并组成新的上游 URI 路径的正则表达式。当同时配置 `uri` 和 `regex_uri` 时，`uri` 具有更高的优先级。该数组应包含一个或多个 **键值对**，其中键是用于匹配 URI 的正则表达式，值是新的上游 URI 路径。例如，对于 `["^/iresty/(. *)/(. *)", "/$1-$2", ^/theothers/*", "/theothers"]`，如果请求最初发送到 `/iresty/hello/world`，插件会将上游 URI 路径重写为 `/iresty/hello-world`；如果请求最初发送到 `/theothers/hello/world`，插件会将上游 URI 路径重写为 `/theothers`。|
4646
| host | string | 否 | | | 设置 [`Host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Host) 请求标头。|
4747
| headers | object | 否 | | | 要执行的标头操作。可以设置为动作动词 `add`、`remove` 和/或 `set` 的对象；或由要 `set` 的标头组成的对象。当配置了多个动作动词时，动作将按照“添加”、“删除”和“设置”的顺序执行。|
48-
| headers.add | object | 否 | | | 要附加到请求的标头。如果请求中已经存在标头，则会附加标头值。标头值可以设置为常量、一个或多个 [Nginx 变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)，或者 `regex_uri` 的匹配结果（使用变量，例如 `$1-$2-$3`）。|
49-
| headers.set | object | 否 | | | 要设置请求的标头。如果请求中已经存在标头，则会覆盖标头值。标头值可以设置为常量、一个或多个 [Nginx 变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)，或者 `regex_uri` 的匹配结果（使用变量，例如 `$1-$2-$3`）。不应将其用于设置 `Host`。|
48+
| headers.add | object | 否 | | | 要附加到请求的标头。如果请求中已经存在标头，则会附加标头值。标头值可以设置为常量、一个或多个 [NGINX 变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)，或者 `regex_uri` 的匹配结果（使用变量，例如 `$1-$2-$3`）。|
49+
| headers.set | object | 否 | | | 要设置请求的标头。如果请求中已经存在标头，则会覆盖标头值。标头值可以设置为常量、一个或多个 [NGINX 变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)，或者 `regex_uri` 的匹配结果（使用变量，例如 `$1-$2-$3`）。不应将其用于设置 `Host`。|
5050
| headers.remove | array[string] | 否 | | | 从请求中删除的标头。
5151
| use_real_request_uri_unsafe | boolean | 否 | false | | 如果为 True，则绕过 URI 规范化并允许完整的原始请求 URI。启用此选项被视为不安全。|
5252

@@ -56,7 +56,7 @@ description: proxy-rewrite 插件支持重写 APISIX 转发到上游服务的请
5656

5757
:::note
5858

59-
您可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量：
59+
你可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量：
6060

6161
```bash
6262
admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
@@ -66,7 +66,7 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/
6666

6767
### 重写主机标头
6868

69-
以下示例演示了如何修改请求中的 `Host` 标头。请注意，您不应使用 `headers.set` 来设置 `Host` 标头。
69+
以下示例演示了如何修改请求中的 `Host` 标头。请注意，你不应使用 `headers.set` 来设置 `Host` 标头。
7070

7171
```shell
7272
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
@@ -95,7 +95,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
9595
curl "http://127.0.0.1:9080/headers"
9696
```
9797

98-
您应该看到类似于以下内容的响应：
98+
你应该看到类似于以下内容的响应：
9999

100100
```text
101101
{
@@ -146,7 +146,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
146146
curl "http://127.0.0.1:9080/" -H '"X-Api-Version": "v2"'
147147
```
148148

149-
您应该看到类似于以下内容的响应：
149+
你应该看到类似于以下内容的响应：
150150

151151
```text
152152
{
@@ -209,7 +209,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
209209
curl "http://127.0.0.1:9080/" -H '"X-Api-Version": "v2"'
210210
```
211211

212-
您应该会看到类似以下内容的响应：
212+
你应该会看到类似以下内容的响应：
213213

214214
```text
215215
{
@@ -262,7 +262,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
262262
curl "http://127.0.0.1:9080/headers"
263263
```
264264

265-
您应该看到类似以下的响应，其中 `User-Agen` 标头已被移除：
265+
你应该看到类似以下的响应，其中 `User-Agen` 标头已被移除：
266266

267267
```text
268268
{
@@ -305,7 +305,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
305305
curl "http://127.0.0.1:9080/test/user/agent"
306306
```
307307

308-
您应该会看到类似以下内容的响应：
308+
你应该会看到类似以下内容的响应：
309309

310310
```text
311311
{
@@ -344,7 +344,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
344344
curl "http://127.0.0.1:9080/get"
345345
```
346346

347-
您应该会看到类似以下内容的响应：
347+
你应该会看到类似以下内容的响应：
348348

349349
```text
350350
{
@@ -396,7 +396,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
396396
curl "http://127.0.0.1:9080/get"
397397
```
398398

399-
您应该会看到类似以下内容的响应：
399+
你应该会看到类似以下内容的响应：
400400

401401
```text
402402
{
@@ -420,7 +420,7 @@ curl "http://127.0.0.1:9080/get"
420420

421421
### 将消费者名称转发到上游
422422

423-
以下示例演示了如何将成功验证的消费者名称转发到上游服务。例如，您将使用 `key-auth` 作为身份验证方法。
423+
以下示例演示了如何将成功验证的消费者名称转发到上游服务。例如，你将使用 `key-auth` 作为身份验证方法。
424424

425425
创建消费者 `JohnDoe`：
426426

@@ -480,7 +480,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
480480
curl -i "http://127.0.0.1:9080/get" -H 'apikey: john-key'
481481
```
482482

483-
您应该收到一个包含以下主体的 `HTTP/1.1 200 OK` 响应：
483+
你应该收到一个包含以下主体的 `HTTP/1.1 200 OK` 响应：
484484

485485
```text
486486
{
@@ -504,4 +504,88 @@ curl -i "http://127.0.0.1:9080/get" -H 'apikey: john-key'
504504
curl -i "http://127.0.0.1:9080/get"
505505
```
506506

507-
您应该收到 `HTTP/1.1 403 Forbidden` 响应。
507+
你应该收到 `HTTP/1.1 403 Forbidden` 响应。
508+
509+
### 在 `radixtree_uri_with_parameter` 路由模式下动态转发请求
510+
511+
以下示例演示如何使用 `uri_param_*` 变量提取 URL 路径的一部分，并将其值转发到上游服务的新标头中。此示例假设 APISIX 运行在 `radixtree_uri_with_parameter` [路由模式](../router-radixtree.md)下。
512+
513+
创建如下路由：
514+
515+
```shell
516+
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
517+
-H "X-API-KEY: ${admin_key}" \
518+
-d '{
519+
"id": "httpbin",
520+
"uri": "/anything/user/:user_id/profile",
521+
"plugins": {
522+
"proxy-rewrite": {
523+
"headers": {
524+
"set": {
525+
"X-User-Id": "$uri_param_user_id"
526+
}
527+
}
528+
}
529+
},
530+
"upstream": {
531+
"type": "roundrobin",
532+
"nodes": {
533+
"httpbin.org:80": 1
534+
}
535+
}
536+
}'
537+
```
538+
539+
`/anything/user/:user_id/profile` 匹配 `user_id` 为路由参数的请求。插件配置为将 `user_id` 参数值赋给新标头 `X-User-Id`。
540+
541+
发送请求到路由：
542+
543+
```shell
544+
curl "http://127.0.0.1:9080/anything/user/123/profile"
545+
```
546+
547+
你应该看到类似于以下内容的响应：
548+
549+
```text
550+
{
551+
"args": {},
552+
"data": "",
553+
"files": {},
554+
"form": {},
555+
"headers": {
556+
"Accept": "*/*",
557+
"Host": "127.0.0.1",
558+
"User-Agent": "curl/8.6.0",
559+
"X-Amzn-Trace-Id": "Root=1-68873cf5-7248f64d19d607ea50aa9735",
560+
"X-Forwarded-Host": "127.0.0.1",
561+
"X-User-Id": "123"
562+
},
563+
...
564+
}
565+
```
566+
567+
路由参数也支持 URL 编码字符串。例如，发送如下请求：
568+
569+
```shell
570+
curl -i "http://127.0.0.1:9080/anything/user/123%20456/profile"
571+
```
572+
573+
用户 ID 将被提取为 `123 456`：
574+
575+
```text
576+
{
577+
"args": {},
578+
"data": "",
579+
"files": {},
580+
"form": {},
581+
"headers": {
582+
"Accept": "*/*",
583+
"Host": "127.0.0.1",
584+
"User-Agent": "curl/8.6.0",
585+
"X-Amzn-Trace-Id": "Root=1-68873d37-7634825b20d05dee3a852cb9",
586+
"X-Forwarded-Host": "127.0.0.1",
587+
"X-User-Id": "123 456"
588+
},
589+
...
590+
}
591+
```

0 commit comments

Comments
 (0)