mirror of
https://gitee.com/iresty/apisix.git
synced 2024-12-15 01:11:58 +08:00
145 lines
6.8 KiB
Markdown
145 lines
6.8 KiB
Markdown
<!--
|
||
#
|
||
# Licensed to the Apache Software Foundation (ASF) under one or more
|
||
# contributor license agreements. See the NOTICE file distributed with
|
||
# this work for additional information regarding copyright ownership.
|
||
# The ASF licenses this file to You under the Apache License, Version 2.0
|
||
# (the "License"); you may not use this file except in compliance with
|
||
# the License. You may obtain a copy of the License at
|
||
#
|
||
# http://www.apache.org/licenses/LICENSE-2.0
|
||
#
|
||
# Unless required by applicable law or agreed to in writing, software
|
||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
# See the License for the specific language governing permissions and
|
||
# limitations under the License.
|
||
#
|
||
-->
|
||
|
||
|
||
Table of contents
|
||
===
|
||
|
||
* [Route](#route)
|
||
|
||
## Route
|
||
|
||
*API*：/apisix/admin/routes/{id}?ttl=0
|
||
|
||
*Description*：Route matches requests based on preset rules, and loads the appropriate plugin according to the matching result, then forwarding requests to target Upstream.
|
||
|
||
> Request Methods：
|
||
|
||
|Method |Request URI|Request Body|Description |
|
||
|---------|-------------------------|--|------|
|
||
|GET |/apisix/admin/routes/{id}|NULL|Fetch resource|
|
||
|PUT |/apisix/admin/routes/{id}|{...}|Create resource by ID|
|
||
|POST |/apisix/admin/routes |{...}|Create resource, and ID is generated by server|
|
||
|DELETE |/apisix/admin/routes/{id}|NULL|Remove resource|
|
||
|PATCH |/apisix/admin/routes/{id}/{path}|{...}|Update targeted content|
|
||
|
||
> URI Request Parameters：
|
||
|
||
|parameter |Required |Type |Description |Example|
|
||
|---------|---------|----|-----------|----|
|
||
|ttl |False |Auxiliary |Expires after target seconds|ttl=1|
|
||
|
||
> Request Body Parameters：
|
||
|
||
|Parameter |Required |Type |Description |Example|
|
||
|---------|---------|----|-----------|----|
|
||
|desc |False |Auxiliary |Identifies route names, usage scenarios, and more.|customer xxxx|
|
||
|uri |True |Match Rules|In addition to full matching such as `/foo/bar`、`/foo/gloo`, using different [Router](architecture-design.md#router) allows more advanced matching, see [Router](architecture-design.md#router) for more.|"/hello"|
|
||
|host |False |Match Rules|Currently requesting a domain name, such as `foo.com`; pan-domain names such as `*.foo.com` are also supported.|"foo.com"|
|
||
|hosts |False |Match Rules|The `host` in the form of a list means that multiple different hosts are allowed, and match any one of them.|{"foo.com", "*.bar.com"}|
|
||
|remote_addr|False |Match Rules|The client requests an IP address: `192.168.1.101`, `192.168.1.102`, and CIDR format support `192.168.1.0/24`. In particular, APISIX also fully supports IPv6 address matching: `::1`, `fe80::1`, `fe80::1/64`, etc.|"192.168.1.0/24"|
|
||
|remote_addrs|False |Match Rules|The `remote_addr` in the form of a list indicates that multiple different IP addresses are allowed, and match any one of them.|{"127.0.0.1", "192.0.0.0/8", "::1"}|
|
||
|methods |False |Match Rules|If empty or without this option, there are no `method` restrictions, and it can be a combination of one or more: `GET`,`POST`,`PUT`,`DELETE`,`PATCH`, `HEAD`,`OPTIONS`,`CONNECT`,`TRACE`.|{"GET", "POST"}|
|
||
|priority |False |Match Rules|If different routes contain the same `uri`, determine which route is matched first based on the attribute` priority`, the default value is 0.|priority = 10|
|
||
|vars |False |Match Rules (only `radixtree` route is supported)|A list of one or more `{var, operator, val}` elements, like this: `{{var, operator, val}, {var, operator, val}, ...}`. For example: `{"arg_name", "==", "json"}` means that the current request parameter `name` is `json`. The `var` here is consistent with the internal variable name of Nginx, so you can also use `request_uri`, `host`, etc. For the operator part, the currently supported operators are `==`, `~=`,`>`, `<`, and `~~`. For the `>` and `<` operators, the result is first converted to `number` and then compared. See a list of [supported operators](#available-operators) |{{"arg_name", "==", "json"}, {"arg_age", ">", 18}}|
|
||
|filter_func|False|Match Rules|User-defined filtering function. You can use it to achieve matching requirements for special scenarios. This function accepts an input parameter named `vars` by default, which you can use to get Nginx variables.|function(vars) return vars["arg_name"] == "json" end|
|
||
|plugins |False |Plugin|See [Plugin](architecture-design.md#plugin) for more ||
|
||
|upstream |False |Upstream|Enabled Upstream configuration, see [Upstream](architecture-design.md#upstream) for more||
|
||
|upstream_id|False |Upstream|Enabled upstream id, see [Upstream](architecture-design.md#upstream) for more ||
|
||
|service_id|False |Service|Binded Service configuration, see [Service](architecture-design.md#service) for more ||
|
||
|service_protocol|False|Upstream protocol type|only `grpc` and `http` are supported|`http` is the default value; Must set `grpc` if using `gRPC proxy` or `gRPC transcode`|
|
||
|
||
For the same type of parameters, such as `host` and `hosts`, `remote_addr` and `remote_addrs` cannot exist at the same time, only one of them can be selected. If enabled at the same time, the API will response an error.
|
||
|
||
Example：
|
||
|
||
```shell
|
||
# Create a route
|
||
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -X PUT -i -d '
|
||
{
|
||
"uri": "/index.html",
|
||
"hosts": ["foo.com", "*.bar.com"],
|
||
"remote_addrs": ["127.0.0.0/8"],
|
||
"methods": ["PUT", "GET"],
|
||
"upstream": {
|
||
"type": "roundrobin",
|
||
"nodes": {
|
||
"39.97.63.215:80": 1
|
||
}
|
||
}
|
||
}'
|
||
|
||
HTTP/1.1 201 Created
|
||
Date: Sat, 31 Aug 2019 01:17:15 GMT
|
||
...
|
||
|
||
# Create a route expires after 60 seconds, then it's deleted automatically
|
||
$ curl http://127.0.0.1:9080/apisix/admin/routes/2?ttl=60 -X PUT -i -d '
|
||
{
|
||
"uri": "/aa/index.html",
|
||
"upstream": {
|
||
"type": "roundrobin",
|
||
"nodes": {
|
||
"39.97.63.215:80": 1
|
||
}
|
||
}
|
||
}'
|
||
|
||
HTTP/1.1 201 Created
|
||
Date: Sat, 31 Aug 2019 01:17:15 GMT
|
||
...
|
||
|
||
```
|
||
|
||
> Response Parameters
|
||
|
||
Return response from etcd currently.
|
||
|
||
### Available Operators
|
||
|
||
|Operator |Description |Example|
|
||
|--------|-----------|-------|
|
||
|== |Equal |{"arg_name", "==", "json"}|
|
||
|~= |Not Equal |{"arg_name", "~=", "json"}|
|
||
|> |Greater Than |{"arg_age", ">", 24}|
|
||
|< |Less Than |{"arg_age", "<", 24}|
|
||
|~~ |Regex |{"arg_name", "~~", "[a-z]+"}|
|
||
|
||
Consider the following example: matching requests whose `request name` is equal to `json`, `age` is greater than `18`, and `address` begins with `China`:
|
||
|
||
```shell
|
||
curl http://127.0.0.1:9080/apisix/admin/routes/1 -X PUT -i -d '
|
||
{
|
||
"uri": "/index.html",
|
||
"vars": [
|
||
["arg_name", "==", "json"],
|
||
["arg_age", ">", "18"],
|
||
["arg_address", "~~", "China.*"]
|
||
],
|
||
"upstream": {
|
||
"type": "roundrobin",
|
||
"nodes": {
|
||
"39.97.63.215:80": 1
|
||
}
|
||
}
|
||
}'
|
||
```
|
||
|
||
[Back to TOC](#table-of-contents)
|